132 lines
4.3 KiB
Markdown
132 lines
4.3 KiB
Markdown
# AGENTS.md
|
|
|
|
This file contains configuration and guidelines for AI agents working on this project.
|
|
|
|
## Project Overview
|
|
|
|
**sqlmodel-pg-kit** is a reusable SQLModel + PostgreSQL toolkit providing:
|
|
- Database configuration and connection management (sync/async)
|
|
- Generic CRUD repositories for common operations
|
|
- CSV import utilities for automatic model generation
|
|
- Example workflows for cheminformatics use cases
|
|
|
|
## Testing Commands
|
|
|
|
After making changes to the code, run these commands to verify:
|
|
|
|
### Fast smoke tests (SQLite only)
|
|
```bash
|
|
make test-sqlite
|
|
```
|
|
|
|
### Full test suite (includes Postgres integration if env vars set)
|
|
```bash
|
|
make test
|
|
```
|
|
|
|
### Postgres integration tests
|
|
```bash
|
|
# Requires environment variables: SQL_HOST, SQL_PORT, SQL_USER, SQL_PASSWORD, SQL_DATABASE, SQL_SSLMODE
|
|
make test-pg
|
|
```
|
|
|
|
### Run across multiple Python versions (3.10-3.13)
|
|
```bash
|
|
make test-pg-once
|
|
```
|
|
|
|
## Code Style
|
|
|
|
- **No comments** in code (unless explicitly requested)
|
|
- Follow existing patterns in the codebase
|
|
- Use existing libraries and utilities before adding new dependencies
|
|
- Check `pyproject.toml` for dependencies already available
|
|
|
|
## Key Files
|
|
|
|
### Core Library
|
|
- `src/sqlmodel_pg_kit/config.py` - DatabaseConfig dataclass
|
|
- `src/sqlmodel_pg_kit/db.py` - Engine and session management
|
|
- `src/sqlmodel_pg_kit/crud.py` - Repository and AsyncRepository classes
|
|
- `src/sqlmodel_pg_kit/csv_import.py` - CSV to SQLModel utilities
|
|
|
|
### Examples
|
|
- `examples/01_sync_crud.py` - Basic CRUD operations
|
|
- `examples/02_bulk_and_filters.py` - Bulk insert and filtering
|
|
- `examples/03_relationships.py` - Model relationships
|
|
- `examples/04_async_crud.py` - Async CRUD operations
|
|
- `examples/05_cheminformatics.py` - Cheminformatics use case
|
|
- `examples/06_csv_to_sqlmodel.py` - CSV import workflow
|
|
- `examples/07_postgres_minimal.py` - Minimal Postgres workflow with REST-style operations
|
|
|
|
### Notebooks
|
|
- `notebooks/01_cheminformatics_quickstart.ipynb` - End-to-end cheminformatics tutorial
|
|
- `notebooks/01_sync_crud.ipynb` - Sync CRUD tutorial
|
|
- `notebooks/02_bulk_and_filters.ipynb` - Bulk insert and filtering
|
|
- `notebooks/03_relationships.ipynb` - Model relationships
|
|
- `notebooks/04_async_crud.ipynb` - Async CRUD operations
|
|
- `notebooks/05_cheminformatics.ipynb` - Cheminformatics step-by-step
|
|
- `notebooks/06_csv_import.ipynb` - CSV import workflow
|
|
- `notebooks/07_postgres_minimal.ipynb` - Postgres minimal example
|
|
|
|
### Tests
|
|
- `tests/test_smoke.py` - Fast SQLite tests
|
|
- `tests/test_pg_integration.py` - Postgres integration tests
|
|
|
|
## Database Setup
|
|
|
|
For local development with Docker:
|
|
```bash
|
|
make db-up # Start Postgres
|
|
make db-down # Stop Postgres
|
|
make db-logs # View logs
|
|
```
|
|
|
|
Environment variables (for Postgres):
|
|
```bash
|
|
export SQL_HOST=127.0.0.1
|
|
export SQL_PORT=5433 # or 5432 for native Postgres
|
|
export SQL_USER=postgres
|
|
export SQL_PASSWORD=change-me-strong
|
|
export SQL_DATABASE=appdb
|
|
export SQL_SSLMODE=disable
|
|
```
|
|
|
|
Note: The project supports both `SQL_*` and `PG*` environment variables (e.g., `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`). Docker Compose uses port `5433` mapped from container's `5432`.
|
|
|
|
## Common Workflows
|
|
|
|
### Adding a new CRUD operation
|
|
1. Add method to `Repository` or `AsyncRepository` in `src/sqlmodel_pg_kit/crud.py`
|
|
2. Update `__all__` exports in `src/sqlmodel_pg_kit/__init__.py` if exposing publicly
|
|
3. Add test in `tests/test_smoke.py` (SQLite) or `tests/test_pg_integration.py` (Postgres)
|
|
4. Run `make test-sqlite` to verify
|
|
|
|
### Adding CSV import features
|
|
1. Modify `src/sqlmodel_pg_kit/csv_import.py`
|
|
2. Add example in `examples/06_csv_to_sqlmodel.py` or create new example
|
|
3. Test with: `uv run python examples/06_csv_to_sqlmodel.py --csv ./data/molecules.csv --sqlite ./demo.db`
|
|
|
|
### Running examples
|
|
```bash
|
|
make examples
|
|
```
|
|
|
|
## Build and Package
|
|
|
|
### PyPI
|
|
- Build: `uv build`
|
|
- Publish: `uv publish`
|
|
|
|
### Conda
|
|
- Build conda package: `conda build conda/` (if conda recipe exists)
|
|
|
|
## Important Notes
|
|
|
|
- SQLite in-memory is used for fast smoke tests
|
|
- Postgres is recommended for production and integration tests
|
|
- The project uses `uv` for dependency management (PEP 621/517)
|
|
- All SQLModel models are registered in `SQLModel.metadata` for `create_all()`
|
|
- For production, prefer `sslmode=verify-full` and least-privileged DB users
|
|
- Bring your own Alembic migrations; set `target_metadata = SQLModel.metadata` in env.py
|