From 47e59d6bc347c131e9516ec130fca35bd739e1b3 Mon Sep 17 00:00:00 2001 From: Stas Moreinis Date: Wed, 24 Dec 2025 13:00:35 -0800 Subject: [PATCH 1/4] docs: Clarify that migrations must run inside Docker container Running `make migration` locally fails because Alembic is only available inside the Docker container. Updated CLAUDE.md to show the correct command using `docker exec agentex`. --- CLAUDE.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 91ceecd..b33375f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -255,10 +255,15 @@ Check `agentex/docker-compose.yml` for default values. Always create migrations when changing models: 1. Modify SQLAlchemy models in `database/models/` -2. Run `make migration NAME="description"` from `agentex/` +2. Run migrations **from inside the Docker container**: + ```bash + docker exec agentex make migration NAME="description" + ``` 3. Review generated migration in `database/migrations/versions/` 4. Apply with `make apply-migrations` +> **Note**: Running `make migration` locally won't work because Alembic is only available inside the Docker container. Always use `docker exec agentex ...` for migration commands. + Migrations run automatically during `make dev` startup. ### Redis Port Conflicts From d3498b3129424e3457d9bf39516c66994efa46f8 Mon Sep 17 00:00:00 2001 From: Stas Moreinis Date: Wed, 24 Dec 2025 13:04:51 -0800 Subject: [PATCH 2/4] docs: Add note about using make test instead of uv run pytest --- CLAUDE.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index b33375f..1c96dbe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -86,6 +86,9 @@ make test-integration # Integration tests shortcut make test-cov # Run with coverage report make test-docker-check # Verify Docker setup for tests +# NOTE: Always use `make test` commands rather than `uv run pytest` directly. +# The Makefile handles proper test configuration and Docker dependencies. + # Linting (ruff) uv run ruff check src/ # Check for lint errors uv run ruff check src/ --fix # Auto-fix lint errors From 84d9397e53550c6ee570324c6c4603b4f6ac6f2d Mon Sep 17 00:00:00 2001 From: Stas Moreinis Date: Wed, 24 Dec 2025 13:05:21 -0800 Subject: [PATCH 3/4] docs: Add note about fixing lint errors before committing --- CLAUDE.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 1c96dbe..820668e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -95,6 +95,9 @@ uv run ruff check src/ --fix # Auto-fix lint errors uv run ruff format src/ # Format code uv run ruff check path/to/file.py # Check specific file +# NOTE: Fix lint errors before committing. Pre-commit hooks will run ruff +# automatically, but it's faster to fix issues proactively. + # Documentation make serve-docs # Serve MkDocs on localhost:8001 make build-docs # Build documentation From 3327fc76412b18beb810e572ca03e398b106a7d7 Mon Sep 17 00:00:00 2001 From: Stas Moreinis Date: Wed, 24 Dec 2025 13:08:43 -0800 Subject: [PATCH 4/4] docs: Add architecture patterns and fix ORM location --- CLAUDE.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 820668e..ba7a7e6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -189,10 +189,29 @@ src/ Global dependencies are managed via a Singleton pattern in `src/config/dependencies.py`: - `GlobalDependencies`: Singleton holding connections to Temporal, databases, Redis, etc. -- FastAPI dependencies use `Annotated` types (e.g., `DDatabaseAsyncReadWriteEngine`) +- FastAPI dependencies use `Annotated` types with a `D` prefix convention: + ```python + DRedisStreamRepository = Annotated[RedisStreamRepository, Depends(RedisStreamRepository)] + ``` - Connection pools are configured with appropriate sizes for concurrency - Startup/shutdown lifecycle managed in `app.py` lifespan context +### Port/Adapter Pattern + +Adapters follow a port/adapter pattern with interfaces and implementations: + +- **Ports**: Abstract interfaces in `port.py` files (e.g., `src/adapters/streams/port.py`) +- **Adapters**: Concrete implementations in `adapter_*.py` files (e.g., `adapter_redis.py`) +- Example: `StreamRepository` (abstract) → `RedisStreamRepository` (implementation) + +### Environment Variables + +Environment variables are defined in `src/config/environment_variables.py`: + +- `EnvVarKeys`: Enum of all environment variable names +- `EnvironmentVariables`: Pydantic model with validation and defaults +- Add new variables to both the enum and the class + ### Testing Strategy Tests are organized by type and use different strategies: @@ -311,9 +330,9 @@ sudo systemctl stop redis-server ### Adding Database Tables -1. Create SQLAlchemy model in `database/models/` -2. Generate migration: `make migration NAME="add_table_name"` -3. Review and edit migration file if needed +1. Add SQLAlchemy model to `src/adapters/orm.py` +2. Generate migration from inside Docker: `docker exec agentex make migration NAME="add_table_name"` +3. Review and edit migration file in `database/migrations/alembic/versions/` 4. Apply migration: `make apply-migrations` ### Adding MongoDB Collections