OSIT-AE-API-FastAPI/GEMINI.md

Gemini Added Memories

My Role and Operating Principles

I am the primary orchestrator and main helper for the development of the Unified Aether AI Agent (UE-AE-01). My goal is to facilitate the creation of a single AI entity with total system awareness across MariaDB, FastAPI, SvelteKit, and Docker.

---

Project Context - Aether API (FastAPI)

• Owner/Developer: Scott Idem (user).
• System Name: Aether (AE).
• Purpose: Events Presentation Management, Events Badge Printing, Leads, Attendee Tracking, Presentation Launcher, Journals, Archives, Posts.
• Current API Version (FastAPI): v4.9.0.
• V3 Implementation: Modern parallel CRUD and Search endpoints under /v3/crud.
• Summary: This project serves as the backend for the Aether system, providing core API functionalities.

Key Technical Learnings (Cumulative)

• Circular Dependencies Fixed: Successfully resolved the fragile startup dependency chain by isolating Auth models and using strictly deferred DB imports in a dedicated dependencies_v3.py module.
• Bootstrap Paradox Solved: Implemented a guest-access exception for site_domain search, allowing the frontend to resolve site context without a JWT.
• V3 Searchable Fields: Confirmed that searchable_fields are fully implemented in app/object_definitions/ and utilized by app/lib_sql_search.py for dynamic query generation.
• Environment Sync Clarification: Critical understanding that the /home/scott/OSIT_dev/ directory is NOT a synchronized directory across different machines (e.g., Workstation vs. Laptop). This means virtual environments and installed dependencies are environment-specific and do not propagate via Syncthing. This is crucial for debugging cross-machine environment issues.
• Circular Import Sensitivity: Importing JSONResponse from fastapi in app/routers/api.py triggers a circular dependency crash. It is safer to rely on FastAPI's default dict-to-JSON serialization or use mk_resp without explicit JSONResponse typing in that specific file.

Session Summary & Progress (Jan 13, 2026)

This session focused on resolving startup errors in the ae_api container and improving database connectivity testing.

• Bug Fixes & Stability:
  • Fixed NameError: Resolved missing mk_resp import in app/main.py.
  • Fixed AttributeError: Corrected response_class=PlainTextResponse to JSONResponse (or default) for dict-returning endpoints.
  • Resolved Circular Dependency: Identified and fixed a circular import caused by JSONResponse usage in app/routers/api.py.
• Infrastructure & Testing:
  • Safe SQL Test Endpoint: Relocated and refactored the sql_test endpoint from app/main.py to app/routers/api.py (accessible at /api/sql_test).
  • Safety Improvement: Updated the test query to use SELECT NOW(), VERSION() instead of querying the account table, ensuring a safe connectivity check without exposing data.
• V3 CRUD Modularization (Phase 1-3):
  • Successfully refactored app/routers/api_crud_v3.py into a modular architecture.
  • Logic Extraction: Created app/lib_api_crud_v3.py for shared security and filtering logic.
  • Nested Routes: Created app/routers/api_crud_v3_nested.py to isolate relational parent-child endpoints.
  • Schema Extraction: Created app/lib_schema_v3.py for database/model introspection.
• DX & Error Transparency:
  • Error Bubbling: Updated app/db_sql.py to capture SQL exceptions and implemented format_db_error to provide human-readable details in API responses.
  • Validation Endpoint: Added POST /v3/crud/{obj_type}/validate for dry-run payload verification.
  • Automatic Sanitization: Backend now automatically strips virtual lookup fields (*_id_random) and view-only fields (via fields_to_exclude_from_db) from write payloads.
• Object Model Alignment:
  • Address & Contact: Updated models and JSON mappings to include hide, priority, sort, group, and notes. Fixed missing imports and unsafe validator access.
  • Journal: Added fields_to_exclude_from_db to filter out view-only fields (e.g., person_full_name) during updates.
  • Post: Added external_person_id to searchable fields.

Current To-Do List

1. High Priority & Urgent (UE-AE-01 Orchestration)

• Review codebase investigator report for Aether extension and journal management. (ID: 155435511) - In Progress (awaiting report from codebase_investigator).
• Implement scope expansion to /home/scott/OSIT_dev/. - Pending registry update.

2. Infrastructure & Technical Debt

• Psutil Container Update: Rebuilding the API image with C-build tools (GCC) to support native system monitoring. (Deferred / Paused)
• Fix ComfyUI Container: Resolve the restart loop in the Ollama/WebUI environment.

3. Other Agent Tasks

• Review and process new messages from various agents. (ID: 134908245) - In Progress (Internal gemini_cli task).
• [scott_wks] Perform Initial System Health Audit (ID: 131939030) - Done.
• [API-V3] Implement Error Bubbling and Validation Endpoint (ID: 163752448) - Done.
• [API] Fix Startup Errors and Refactor SQL Test Endpoint - Done.

Workflow & Collaboration

• Storage: Critical assets at /home/scott/OSIT/hosted_files/ (Synced via Syncthing).
• Agents Sync: Shared documentation and notifications pushed to ~/agents_sync/.
• Coding Standards: Adhering to prompts/coding_standards.md.