Skip to content

Contributing

Your contributions are highly appreciated!

Prerequisites

Before proceeding, ensure the following tools and credentials are set up:

Tip

Once uv is installed, you can easily install pre-commit by running: 

uv tool install pre-commit

  • Set up pre-commit hook: 
    pre-commit install --install-hooks
  • Generate an OpenAI API Key:
    1. Create an openai account.
    2. Visit the API key page.
    3. Generate a new secret key.
      You'll need this key in the setup section below.

Installation and Setup

To run timecopilot in your local environment:

  1. Fork and clone the repository: 
    git clone git@github.com:<your username>/timecopilot.git
  2. Navigate into the project folder: 
    cd timecopilot
  3. Install the required dependencies for local development: 
    uv sync --frozen --all-extras --all-packages --group docs
  4. Export your OpenAI API key as an environment variable: 
    export OPENAI_API_KEY="<your-new-secret-key>"
  5. Test timecopilot with a sample forecast: 
    uvx timecopilot forecast https://otexts.com/fpppy/data/AirPassengers.csv

✅ You're ready to start contributing!

Running Tests

To run tests, run:

uv run pytest

Documentation Changes

To run the documentation page in your local environment, run:

uv run mkdocs serve

Documentation Notes

  • Each pull request is tested to ensure it can successfully build the documentation, preventing potential errors.
  • Merging into the main branch triggers a deployment of a documentation preview, accessible at preview.timecopilot.dev.
  • When a new version of the library is released, the documentation is deployed to timecopilot.dev.

File Naming Convention

All documentation files should use kebab-case (e.g., model-hub.md, forecasting-parameters.md). Kebab-case is widely used in static site generators and web contexts because it is URL-friendly, consistent, and avoids ambiguity with underscores or camelCase. Using a single convention improves readability and prevents broken links in deployment.

For further reference, see the Google Developer Documentation Style Guide on file names.

Adding Models & Adapters

In order for new models and adapters to show up in TimeCopilot's documentation properly there are a couple steps to take:

  • Add the model/adapter in its own file or the appropriate file in docs/api/models or the appropriate subdirectory. For adapters, it may also be good to create an example notebook in docs/examples and add it to the Examples section of mkdocs.yml.
    • when creating a new file in docs/api/models for this step, add that file in the API Reference section of mkdocs.yml
  • A docstring should be present for the new model/adapter with an example in the forecast() method in a similar style to the TimeCopilot agent query method. Note: when adding an adapter with its own dependencies you may need to add those dependencies as dev dependencies with uv add new_dep --group dev.

Adding New Datasets

The datasets utilized in our documentation are hosted on AWS at https://timecopilot.s3.amazonaws.com/public/data/. If you wish to contribute additional datasets for your changes, please contact @AzulGarza for guidance.

Forked Dependencies

TimeCopilot uses some forked Python packages, maintained under custom names on PyPI: