innercontext/AGENTS.md

AGENTS.md

Personal health & skincare data hub with LLM agent integration. Monorepo: Python FastAPI backend + SvelteKit frontend.

Structure

innercontext/
├── backend/           # Python 3.12, FastAPI, SQLModel, PostgreSQL, Gemini
│   ├── innercontext/  # Main package
│   │   ├── api/       # 7 FastAPI routers + LLM endpoints
│   │   ├── models/    # SQLModel tables + Pydantic types (12 files)
│   │   ├── validators/# LLM response validators (6 validators)
│   │   ├── services/  # FX rates (NBP API), pricing jobs
│   │   └── workers/   # Background pricing worker
│   ├── tests/         # pytest (171 tests, SQLite in-memory)
│   ├── alembic/       # DB migrations (17 versions)
│   ├── main.py        # App entry, lifespan, CORS, router registration
│   └── db.py          # Engine, get_session(), create_db_and_tables()
├── frontend/          # SvelteKit 2, Svelte 5, Tailwind v4, bits-ui
│   └── src/
│       ├── routes/    # File-based routing (15+ pages)
│       ├── lib/       # API client, types, components, i18n
│       └── app.css    # Theme + editorial design system
├── docs/              # Deployment guides + frontend-design-cookbook.md
├── nginx/             # Reverse proxy (strips /api prefix → backend:8000)
├── systemd/           # 3 units: backend, frontend-node, pricing-worker
├── scripts/           # Health checks, backups, env validation
└── deploy.sh          # Push-based deploy (Capistrano-style symlinked releases)

Agent Skills

• svelte-code-writer: REQUIRED for .svelte, .svelte.ts, .svelte.js files.
• frontend-design: Frontend UI, page, and component design work.
• conventional-commit: Commit messages following Conventional Commits.
• gemini-api-dev: Gemini API integrations, multimodal, function calling, structured output.

When editing frontend code, follow docs/frontend-design-cookbook.md and update it when introducing or modifying reusable UI patterns, visual rules, or shared styling conventions.

Where to Look

Task	Location	Notes
Add API endpoint	backend/innercontext/api/	Follow router pattern, use get_or_404()
Add/modify model	backend/innercontext/models/	See backend/AGENTS.md for JSON col + timestamp conventions
Add DB migration	backend/alembic/	cd backend && uv run alembic revision --autogenerate -m "desc"
Add frontend page	frontend/src/routes/	+page.svelte + +page.server.ts (load + actions)
Add component	frontend/src/lib/components/	Use bits-ui primitives, check design cookbook
Add LLM feature	backend/innercontext/api/ + llm.py	call_gemini() or call_gemini_with_function_tools()
Add LLM validator	backend/innercontext/validators/	Extend BaseValidator, return ValidationResult
Add i18n strings	frontend/messages/{en,pl}.json	Auto-generates to src/lib/paraglide/
Modify design system	frontend/src/app.css + docs/frontend-design-cookbook.md	Update both in same change
Modify types	backend/innercontext/models/ → pnpm generate:api → frontend/src/lib/types.ts	Auto-generated from OpenAPI; bridge file may need augmentation

Commands

# Backend
cd backend && uv run python main.py          # Start API server
cd backend && uv run ruff check .             # Lint
cd backend && uv run black .                  # Format
cd backend && uv run isort .                  # Sort imports
cd backend && uv run pytest                   # Run tests

# Frontend
cd frontend && pnpm dev                       # Dev server (API proxied to :8000)
cd frontend && pnpm check                     # Type check + Svelte validation
cd frontend && pnpm lint                      # ESLint
cd frontend && pnpm format                    # Prettier
cd frontend && pnpm build                     # Production build → build/
cd frontend && pnpm generate:api              # Regenerate types from backend OpenAPI

Commit Guidelines

Conventional Commits: feat(api): ..., fix(frontend): ..., test(models): .... Include scope indicating which part of the monorepo is affected.

Architecture

Backend: Python 3.12, FastAPI, SQLModel 0.0.37 + SQLAlchemy, Pydantic v2, PostgreSQL (psycopg3), Gemini API (google-genai).

Frontend: SvelteKit 2, Svelte 5 (Runes), TypeScript, Tailwind CSS v4, bits-ui (shadcn-svelte), Paraglide (i18n), svelte-dnd-action, adapter-node.

Cross-Cutting Patterns

• Type sharing: Auto-generated from backend OpenAPI schema via @hey-api/openapi-ts. Run cd frontend && pnpm generate:api after backend model changes. src/lib/types.ts is a bridge file with re-exports, renames, and Require<> augmentations. See frontend/AGENTS.md § Type Generation.
• API proxy: Frontend server-side uses PUBLIC_API_BASE (http://localhost:8000). Browser uses /api (nginx strips prefix → backend).
• Auth: None. Single-user personal system.
• Error flow: Backend HTTPException(detail=...) → Frontend catches .detail field → FlashMessages or StructuredErrorDisplay.
• LLM validation errors: Non-blocking (HTTP 200). Returned in validation_warnings field. Frontend parses semicolon-separated strings into list.

Models

File	Tables
product.py	products, product_inventory
health.py	medication_entries, medication_usages, lab_results
routine.py	routines, routine_steps, grooming_schedules
skincare.py	skin_condition_snapshots
profile.py	user_profiles
pricing.py	pricing_recalc_jobs
ai_log.py	ai_call_logs

Product is the core model with JSON columns for inci, actives, recommended_for, targets, product_effect_profile, and context_rules. to_llm_context() returns a token-optimised dict for LLM usage.

Deployment

• CI: Forgejo (.forgejo/workflows/), manual trigger only.
• Deploy: deploy.sh pushes via SSH to LXC host. Capistrano-style timestamped releases with current symlink. Auto-rollback on health check failure.
• Services: 3 systemd units — backend (uvicorn :8000), frontend-node (:3000), pricing-worker.
• Env: Backend .env has DATABASE_URL + GEMINI_API_KEY. Frontend PUBLIC_API_BASE set at build time.

Anti-Patterns (this project)

• model_validator(mode="after") does NOT fire on table=True SQLModel instances (SQLModel 0.0.37 + Pydantic v2 bug). Validators in Product are documentation only.
• Never use plain Field(default_factory=...) for updated_at — must use sa_column=Column(DateTime(timezone=True), onupdate=utc_now).
• JSON columns use sa_column=Column(JSON, nullable=...) — NOT JSONB. DB-agnostic.
• Gemini API rejects int-enum in response_schema — AIActiveIngredient overrides with int + # type: ignore[assignment].
• backend/skincare.yaml is legacy notes — ignore, not part of data model.
• ESLint rule svelte/no-navigation-without-resolve has ignoreGoto: true workaround (upstream bug sveltejs/eslint-plugin-svelte#1327).
• _ev() helper in product.py normalises enum values when fields may be raw dicts (from DB) or Python enum instances.
• No frontend tests exist. Backend tests use SQLite in-memory (not PostgreSQL).