From 09a45095fa8dc0f6d0806c751ff072986621dfff Mon Sep 17 00:00:00 2001
From: lingyuzeng <pylyzeng@gmail.com>
Date: Mon, 19 Jan 2026 23:16:16 +0800
Subject: [PATCH] add AGENTS.md for AI agent guidelines

---
 AGENTS.md                           | 113 ++++++++++++++++++++++++++++
 notebooks/07_postgres_minimal.ipynb |   5 +-
 2 files changed, 115 insertions(+), 3 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9d0fd43
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,113 @@
+# 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()`
diff --git a/notebooks/07_postgres_minimal.ipynb b/notebooks/07_postgres_minimal.ipynb
index 298d33a..459e9bb 100644
--- a/notebooks/07_postgres_minimal.ipynb
+++ b/notebooks/07_postgres_minimal.ipynb
@@ -52,7 +52,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "id": "23860bb5",
    "metadata": {},
    "outputs": [
@@ -101,7 +101,6 @@
     "        size=2,\n",
     "    )\n",
     "    print(\"First page of in-stock widgets:\", [(w.id, w.name) for w in page])\n",
-    "\n",
     "    search_term = \"ro\"\n",
     "    search_stmt = (\n",
     "        select(Widget)\n",
@@ -153,4 +152,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
\ No newline at end of file
+}