Contributing to the Temporal AI Agent Project

This document provides guidelines for contributing to temporal-ai-agent. All setup and installation instructions can be found in setup.md.

Getting Started

We use black for code formatting and isort for import sorting to maintain a consistent codebase.

Format code:
```
uv run black .
uv run isort .
```
Please format your code before committing.

We use mypy for static type checking.

Run type checks:
```
uv run mypy --check-untyped-defs --namespace-packages .
```
Ensure all linting and type checks pass before submitting a pull request.

Comprehensive testing is crucial for this project. We use pytest and Temporal's testing framework.

Install test dependencies:
```
uv sync
```
Run all tests:
```
uv run pytest
```
Run tests with time-skipping (recommended for faster execution, especially in CI):
```
uv run pytest --workflow-environment=time-skipping
```

For detailed information on test categories, running specific tests, test environments, coverage, and troubleshooting, please refer to:

Ensure all tests pass before submitting a pull request.

If you're looking to extend the agent's capabilities:

Create your tool implementation in the tools/ directory.
Register your tool and associate it with relevant goals. For detailed instructions, please see:

When you're ready to submit your changes:

Push your branch to the remote repository.
Open a Pull Request (PR) against the main branch.
Describe your changes: Clearly explain what you changed and why. Reference any related issues.
Ensure tests pass: All CI checks, including tests and linters, must pass. The command uv run pytest --workflow-environment=time-skipping is a good one to run locally.
Request review: Request a review from one or more maintainers.

If you encounter a bug, please:

Search existing issues: Check if the bug has already been reported.
Open a new issue: If not, create a new issue.
- Provide a clear and descriptive title.
- Include steps to reproduce the bug.
- Describe the expected behavior and what actually happened.
- Provide details about your environment (OS, Python version, Temporal server version, etc.).
- Include any relevant logs or screenshots.

We welcome suggestions for new features or improvements!

Search existing issues/discussions: See if your idea has already been discussed.
Open a new issue:
- Use a clear and descriptive title.
- Provide a detailed explanation of the enhancement and its benefits.
- Explain the use case or problem it solves.
- Include any potential implementation ideas if you have them.