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.

Session Summary & Progress (Jan 9, 2026)

This session focused on fixing Person creation issues, modularizing the V3 CRUD system, and enhancing Developer Experience (DX) for the frontend.

• 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.
• Test Suite Creation: Established a /tests directory with focused scripts:
  • test_model_validation.py (Person/Auth key defaults).
  • test_v3_filtering.py (Journal exclusion lists).
  • test_v3_router_filtering.py (Payload sanitization).
  • test_v3_error_bubbling.py (SQL error formatting).
• System Health & Architecture:
  • Audit confirmed API and AI services (Ollama/WebUI) are stable; ComfyUI is stuck in a restart loop.
  • Analyzed and recommended scope expansion to the /home/scott/OSIT_dev/ root for better platform orchestration.

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.

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.