# 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

### 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=5432
export SQL_USER=postgres
export SQL_PASSWORD=change-me-strong
export SQL_DATABASE=appdb
export SQL_SSLMODE=disable
```

## 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

- Build: `uv build`
- Publish to PyPI: `uv publish`
- Build conda package: `conda build conda/`

## 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()`