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 Hack/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.
-   **ID Vision Mapping Stability**: Resolved a critical conflict in `app/lib_sql_search.py` where backend-injected integer filters (e.g., `account_id`) were being incorrectly mapped to `_random` string columns. Mapping now only occurs for non-integer values.
-   **API Error Transparency**: Modified `sql_select` to return `False` on hard database errors (instead of empty results). Updated the V3 search endpoint to return a `500 Internal Server Error` in these cases, preventing "silent failures" where frontend developers would see `200 OK` with zero results during system errors.
-   **NULL Logic in Filters**: Confirmed that explicit frontend filters like `hide: false` will FAIL to match `NULL` database values in standard SQL equality. It is more robust to rely on the API's built-in `hidden=not_hidden` URL parameter, which handles `(hide = false OR hide IS NULL)` automatically.
-   **V3 Action Router Paradigm**: Established a new pattern for specialized binary operations (Upload/Download) under `/v3/action/`, keeping the standard `/v3/crud/` routes clean for JSON metadata.
-   **Vision ID safety Net**: Enhanced `lookup_id_random_pop` to resolve random string IDs found in any `*_id` field, ensuring "Vision" style payloads (where IDs are strings) are correctly converted to integers before database insertion even if the `*_id_random` field is missing.
-   **Pydantic Response Exclusion**: Confirmed that `Field(exclude=True)` in Pydantic models is the most robust way to hide internal logistics fields (like `subdirectory_path`) from the client while keeping them available for backend logic.
-   **V3 Search Security Mapping**: Discovered and fixed a gap where integer IDs (like `event_id`) were not explicitly listed in `searchable_fields` for some objects, preventing valid numeric filters from reaching the database.

## Session Summary & Progress (Jan 26, 2026)

This session focused on stabilizing V3 object definitions and enhancing API privacy for file-related objects.

*   **V3 Search Stabilization:**
    *   Updated `event_device` object definitions to include integer ID fields (`id`, `event_device_id`, `account_id`, `event_id`, `event_location_id`) in `searchable_fields`. This resolves issues where lookups by parent IDs were being blocked by the V3 search security layer.
*   **Privacy & Information Hiding:**
    *   Hiden internal file sharding paths (`subdirectory_path`) from all public-facing API responses.
    *   Implemented this via Pydantic `Field(exclude=True)` in `Hosted_File_Base`, `Event_File_Base`, and `Archive_Content_Base` models.
    *   Removed these fields from `exp_default` and `searchable_fields` metadata to ensure a clean API contract.
*   **Code Quality:**
    *   Fixed syntax errors (missing commas) in the `hosted_file` object definition within `app/object_definitions/other.py`.
    *   Verified all changes via `py_compile` and service restarts.
    *   Committed all changes to the `development` branch.

## Current To-Do List

### 1. High Priority & Urgent (UE-AE-01 Orchestration)
- [ ] **Real-world test of ae_field_manage.py.** (ID: 153357623) - Pending user verification of first field addition.
- [ ] **Review codebase investigator report for Aether extension and journal management.** (ID: 155435511) - In Progress.

### 2. Infrastructure & Technical Debt
- [ ] **Pydantic V2 Migration**: Begin impact analysis for the 400+ validators and .dict() calls.
- [ ] **Psutil Container Update**: Rebuilding the API image with C-build tools (GCC). (Paused)

### 3. Other Agent Tasks
- [ ] **Review and process new messages from various agents.** (ID: 134908245) - In Progress (Internal gemini_cli task).


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


## 📋 Aether API Development Protocol

0. Pre-Flight Check: Verify git status. Ensure all previous working changes are committed to maintain a "known good" state before starting a new cycle.
1. Strategic Plan: Write a concise plan identifying the issue, the specific files to be modified, and the verification steps (including specific curl commands or test scripts).
2. Implementation: Perform atomic code modifications using the replace or write_file tools.
3. Syntax Validation: Run python3 -m py_compile <modified_file> immediately. If syntax errors exist, they must be fixed before proceeding to deployment.
4. Process Cycle: Restart the Docker FastAPI service to apply changes:
    * "docker restart aether_container_env-ae_api-2"
5. Empirical Testing:
    * Execute the curl commands or test scripts identified in Step 1.
    * Inspect the live log stream for regressions:

    1 "tail -n 20 ~/OSIT_dev/aether_container_env/logs/ae_api/aether_api.log"
6. Finalize: Once verified, commit the changes with a descriptive message and sync relevant documentation.