diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 412bbb24ac..65cd62ca99 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -47,6 +47,8 @@ jobs: python-version: ${{ matrix.python-version }} - name: Run tests + env: + RUN_INTEGRATION_TESTS: "1" run: | uv run pytest tests/ \ -n auto \ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..800ddd0cef --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,80 @@ +# CLAUDE.md — AI Company + +## Project + +- **What**: Framework for orchestrating autonomous AI agents within a virtual company structure +- **Python**: 3.14+ (PEP 649 native lazy annotations) +- **License**: BUSL-1.1 (converts to Apache 2.0 on 2030-02-27) +- **Layout**: `src/ai_company/` (src layout), `tests/` (unit/integration/e2e) +- **Design**: [DESIGN_SPEC.md](DESIGN_SPEC.md) (full high-level spec) + +## Quick Commands + +```bash +uv sync # install all deps (dev + test) +uv run ruff check src/ tests/ # lint +uv run ruff check src/ tests/ --fix # lint + auto-fix +uv run ruff format src/ tests/ # format +uv run mypy src/ # type-check (strict) +uv run pytest tests/ -m unit # unit tests only +uv run pytest tests/ -m integration # integration tests only +uv run pytest tests/ -n auto --cov=ai_company --cov-fail-under=80 # full suite + coverage +uv run pre-commit run --all-files # all pre-commit hooks +``` + +## Package Structure + +```text +src/ai_company/ + api/ # FastAPI REST + WebSocket routes + budget/ # Per-agent cost tracking and spending controls + cli/ # Typer CLI commands + communication/ # Inter-agent message bus and channels + config/ # YAML company config loading and validation + core/ # Shared domain models and base classes + engine/ # Agent execution engine and task lifecycle + memory/ # Persistent agent memory (Mem0 adapter) + providers/ # LLM provider abstraction (LiteLLM adapter) + security/ # SecOps agent, approval gates, sandboxing + templates/ # Pre-built company templates and builder + tools/ # Tool registry, MCP integration, role-based access +``` + +## Code Conventions + +- **No `from __future__ import annotations`** — Python 3.14 has PEP 649 +- **Type hints**: all public functions, mypy strict mode +- **Docstrings**: Google style, required on public classes/functions (enforced by ruff D rules) +- **Immutability**: create new objects, never mutate existing ones +- **Models**: Pydantic v2 (`BaseModel`, `model_validator`, `ConfigDict`) +- **Line length**: 88 characters (ruff) +- **Functions**: < 50 lines, files < 800 lines +- **Errors**: handle explicitly, never silently swallow +- **Validate**: at system boundaries (user input, external APIs, config files) + +## Testing + +- **Markers**: `@pytest.mark.unit`, `@pytest.mark.integration`, `@pytest.mark.e2e`, `@pytest.mark.slow` +- **Coverage**: 80% minimum (enforced in CI) +- **Async**: `asyncio_mode = "auto"` — no manual `@pytest.mark.asyncio` needed +- **Timeout**: 30 seconds per test +- **Parallelism**: `pytest-xdist` via `-n auto` + +## Git + +- **Commits**: `: ` — types: feat, fix, refactor, docs, test, chore, perf, ci +- **Enforced by**: commitizen (commit-msg hook) +- **Branches**: `/` from main +- **Pre-commit hooks**: trailing-whitespace, end-of-file-fixer, check-yaml, check-toml, check-json, check-merge-conflict, check-added-large-files, no-commit-to-branch (main), ruff check+format, gitleaks + +## CI + +- **Jobs**: lint (ruff) + type-check (mypy) + test (pytest + coverage) run in parallel → ci-pass (gate) +- **Matrix**: Python 3.14 +- **Dependabot**: daily uv + github-actions updates, auto-merge for patch/minor + +## Dependencies + +- **Pinned**: all versions use `==` in `pyproject.toml` +- **Groups**: `test` (pytest + plugins), `dev` (includes test + ruff, mypy, pre-commit, commitizen, pydantic) +- **Install**: `uv sync` installs everything (dev group is default) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..035423c3b9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,142 @@ +# Contributing to AI Company + +## Quick Start + +```bash +git clone https://github.com/Aureliolo/ai-company.git +cd ai-company +uv sync +``` + +For the full setup walkthrough (prerequisites, IDE config, etc.), see [docs/getting_started.md](docs/getting_started.md). + +## Branching Strategy + +Branch from `main`. Use the naming convention: + +```text +/ +``` + +Examples: `feat/agent-engine`, `fix/config-validation`, `docs/api-reference` + +Types match commit types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`. + +## Making Changes + +1. Create a feature branch: `git checkout -b feat/my-feature main` +2. Install hooks (first time only): `uv run pre-commit install` +3. Make your changes +4. Run quality checks (see below) +5. Commit using conventional commit format +6. Push and open a pull request + +## Commit Conventions + +This project uses [Conventional Commits](https://www.conventionalcommits.org/) enforced by commitizen. + +```text +: + + +``` + +### Types + +| Type | When to use | +|------|-------------| +| `feat` | New feature | +| `fix` | Bug fix | +| `refactor` | Code restructuring (no behavior change) | +| `docs` | Documentation only | +| `test` | Adding or updating tests | +| `chore` | Maintenance, tooling, config | +| `perf` | Performance improvement | +| `ci` | CI/CD changes | + +### Examples + +```text +feat: add YAML config loader with schema validation +fix: prevent division by zero in budget calculator +test: add integration tests for message bus +docs: update API reference for provider layer +``` + +Keep the description lowercase, imperative, and under 72 characters. The optional body can provide additional context. + +## Code Quality Checks + +Run these before pushing: + +```bash +uv run ruff check src/ tests/ # lint +uv run ruff format --check src/ tests/ # format check +uv run mypy src/ # type check +``` + +Auto-fix lint and formatting issues: + +```bash +uv run ruff check src/ tests/ --fix +uv run ruff format src/ tests/ +``` + +## Running Tests + +```bash +uv run pytest tests/ -m unit # unit tests (fast) +uv run pytest tests/ -m integration # integration tests +uv run pytest tests/ -m e2e # end-to-end tests +uv run pytest tests/ -n auto --cov=ai_company --cov-fail-under=80 # full suite + coverage +``` + +All tests must pass and coverage must remain at or above 80%. + +## Pre-commit Hooks + +Hooks run automatically on `git commit`. If a hook fails: + +1. Review the output — most hooks (ruff, trailing whitespace) auto-fix the issue +2. Stage the auto-fixed files: `git add .` +3. Commit again + +To run all hooks manually: + +```bash +uv run pre-commit run --all-files +``` + +See [docs/getting_started.md](docs/getting_started.md) for the full list of hooks and what each one does. + +## Code Style + +Code conventions (type hints, docstrings, immutability, line length, etc.) are documented in [CLAUDE.md](CLAUDE.md). Both human contributors and AI assistants follow the same rules. + +## Pull Request Process + +1. Ensure all quality checks pass locally (lint, type-check, tests) +2. Push your branch: `git push -u origin feat/my-feature` +3. Open a PR against `main` +4. Fill in the PR description: what changed, why, and how to test +5. CI must pass (lint, type-check, test with coverage) +6. Address review feedback +7. Squash-merge when approved + +## Project Structure + +```text +src/ai_company/ # Main package + api/ budget/ cli/ communication/ config/ core/ + engine/ memory/ providers/ security/ templates/ tools/ +tests/ + unit/ integration/ e2e/ +docs/ # Developer documentation +.github/ # CI, dependabot, actions +``` + +See [docs/getting_started.md](docs/getting_started.md) for descriptions of each sub-package. + +## License + +This project is licensed under [BUSL-1.1](LICENSE). By contributing, you agree that your contributions will be licensed under the same terms. diff --git a/README.md b/README.md index 9b38d5ecba..cb9223c5d9 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,19 @@ AI Company lets you spin up a virtual organization staffed entirely by AI agents - **Vue 3** for web dashboard (planned) - **SQLite** → PostgreSQL for data persistence (planned) +## Getting Started + +```bash +git clone https://github.com/Aureliolo/ai-company.git +cd ai-company +uv sync +``` + +See [docs/getting_started.md](docs/getting_started.md) for prerequisites, IDE setup, and the full walkthrough. + ## Documentation +- [Getting Started](docs/getting_started.md) - Setup and installation guide +- [Contributing](CONTRIBUTING.md) - Branch, commit, and PR workflow +- [CLAUDE.md](CLAUDE.md) - Code conventions and AI assistant reference - [Design Specification](DESIGN_SPEC.md) - Full high-level design diff --git a/docs/.gitkeep b/docs/.gitkeep deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000000..b1302272fb --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,151 @@ +# Getting Started + +Step-by-step guide to set up a development environment for AI Company. + +## Prerequisites + +### Python 3.14+ + +Download from [python.org](https://www.python.org/downloads/) or use a version manager like pyenv. + +### uv (package manager) + +```bash +# macOS / Linux +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Windows (PowerShell) +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +### Git + +Required for cloning the repository and commit hooks. Install from [git-scm.com](https://git-scm.com/). + +## Clone and Install + +```bash +git clone https://github.com/Aureliolo/ai-company.git +cd ai-company +uv sync +``` + +`uv sync` creates a virtual environment in `.venv/` and installs all development dependencies (linters, type checker, test runner, pre-commit, etc.). + +## Verify Installation + +Run the smoke tests to confirm everything is working: + +```bash +uv run pytest tests/ -m unit +``` + +You should see all tests passing. + +## Pre-commit Hooks + +Install the Git hooks so code quality checks run automatically on each commit: + +```bash +uv run pre-commit install +``` + +This installs hooks for both `pre-commit` and `commit-msg` stages. To run all hooks manually against the entire codebase: + +```bash +uv run pre-commit run --all-files +``` + +### What the hooks do + +| Hook | Purpose | +|------|---------| +| trailing-whitespace | Remove trailing whitespace | +| end-of-file-fixer | Ensure files end with a newline | +| check-yaml / check-toml / check-json | Validate config file syntax | +| check-merge-conflict | Prevent committing merge conflict markers | +| check-added-large-files | Block files > 1 MB | +| no-commit-to-branch | Block direct commits to `main` | +| ruff (check + format) | Lint and format Python code | +| gitleaks | Detect hardcoded secrets | +| commitizen | Enforce conventional commit message format | + +## Quality Checks + +Run these before pushing to make sure CI will pass: + +```bash +# Lint +uv run ruff check src/ tests/ + +# Format check (no changes, just verify) +uv run ruff format --check src/ tests/ + +# Type check +uv run mypy src/ + +# Tests with coverage +uv run pytest tests/ -n auto --cov=ai_company --cov-fail-under=80 +``` + +To auto-fix lint issues and reformat: + +```bash +uv run ruff check src/ tests/ --fix +uv run ruff format src/ tests/ +``` + +## Project Layout + +```text +ai-company/ + src/ai_company/ # Main package (src layout) + api/ # FastAPI REST + WebSocket routes + budget/ # Cost tracking and spending controls + cli/ # Typer CLI commands + communication/ # Inter-agent message bus + config/ # YAML config loading and validation + core/ # Shared domain models + engine/ # Agent execution engine + memory/ # Persistent agent memory + providers/ # LLM provider abstraction + security/ # SecOps, approval gates, sandboxing + templates/ # Pre-built company templates + tools/ # Tool registry, MCP integration + tests/ + unit/ # Fast, isolated tests (no I/O) + integration/ # Tests with I/O, databases, APIs + e2e/ # Full system tests + docs/ # Developer documentation + .github/ # CI workflows, dependabot, actions + pyproject.toml # Project config (deps, tools, linters) + DESIGN_SPEC.md # Full high-level design specification + CLAUDE.md # AI assistant quick reference + CONTRIBUTING.md # Contributor workflow guide +``` + +## IDE Setup + +### VS Code / Cursor + +Recommended extensions: + +- **Ruff** (`charliermarsh.ruff`) — linting and formatting +- **Pylance** (`ms-python.vscode-pylance`) — type checking and IntelliSense + +Both Pylance (pyright) and mypy are configured in strict mode. They complement each other: Pylance provides real-time IDE feedback while mypy runs in CI as the authoritative check. + +Set the Python interpreter to the project virtual environment: + +```text +.venv/Scripts/python # Windows +.venv/bin/python # macOS / Linux +``` + +VS Code should auto-detect the `.venv` directory. If not, use **Python: Select Interpreter** from the command palette. + +## Next Steps + +- [CONTRIBUTING.md](../CONTRIBUTING.md) — branch, commit, and PR workflow +- [CLAUDE.md](../CLAUDE.md) — code conventions and quick command reference +- [DESIGN_SPEC.md](../DESIGN_SPEC.md) — full high-level design specification diff --git a/pyproject.toml b/pyproject.toml index 64cc8d2f87..1dc1675c40 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -152,7 +152,7 @@ warn_required_dynamic_aliases = true # --------------------------------------------------------------------------- [tool.pyright] pythonVersion = "3.14" -typeCheckingMode = "basic" +typeCheckingMode = "strict" venvPath = "." venv = ".venv"