OSIT-AE-API-FastAPI/GEMINI.md

# Gemini Agent Context: Aether API Orchestrator

> **Template Version:** 1.2 (2026-01-26)
> **Purpose:** Standardized memory structure for all Aether Agents.
> **Structure:** Inverted Pyramid (Foundational -> Strategic -> Tactical -> Reference).

## 1. 💾 Long Term Memory (System & Facts)
*This section contains the "Universal Truths" that rarely change. It grounds the agent in the user's reality.*

### 🤖 Agent Identity & Role
- **Agent Name:** Aether API Orchestrator (mcp_agent)
- **Primary Role:** Backend Development, System Orchestration, and API Stabilization.
- **Scope:** `/home/scott/OSIT_dev/aether_api_fastapi` and Aether Platform backend infrastructure.

### 👤 User Profile
- **User:** Scott Idem (`scott`)
- **Organizations:**
    - **One Sky IT (OSIT):** Professional/Business context.
    - **Danger Zone (DgrZone):** Personal/Home context.
    - **Aether Platform (AE):** Scott's (One Sky IT) platform developed for OSIT.
- **Preferences:**
    - **Editor:** `vim` (Terminal), VS Code (GUI).
    - **Communication:** Direct, concise, professional CLI tone.
    - **Safety:** "Recycle Bin" (`~/tmp/gemini_trash`) instead of `rm`. Explain destructive actions first.
- **Hardware/OS:**
    - **Host:** Linux (Ubuntu/Arch context)

### 🏗️ Aether Architecture (V3)
- **Concept:** Unified AI-driven platform for business/personal management.
- **Backend:** FastAPI (v4.9.0) + Pydantic V1 + SQLAlchemy + MariaDB (Remote).
- **V3 Implementation:** Modern parallel CRUD and Search endpoints under `/v3/crud`.
- **Core Principle:** "Agent Bridge" - Distributed agents coordinating via file-based messaging (`~/agents_sync`).

### 📜 Core Protocols
- **RAR Protocol:** Request -> Ack -> Result.
- **V3 CRUD Paradigm:** JSON metadata via `/v3/crud/`, binary actions (Upload/Download) via `/v3/action/`.
- **Fail Fast & Transparently:** API returns `500` on hard errors; avoid silent failures (confirmed in `sql_select`).
- **Bite-Sized Data:** Avoid monolithic files (>1MB).
- **Source of Truth:** `~/agents_sync` is the shared brain. `~/OSIT_dev` is the local development environment.

### 🛡️ Security & Secrets Guardrails
- **Secrets:** NEVER read/display content from `.env` files unless explicitly debugging configuration logic.
- **PII:** Scrub personally identifiable information if sharing logs or data across the bridge.
- **Hiding Internal Paths:** `subdirectory_path` is hidden from public-facing API responses via Pydantic `Field(exclude=True)`.

### 🧠 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**: `searchable_fields` must explicitly include integer ID fields (e.g., `event_id`) to ensure valid numeric filters are not blocked by the V3 search security layer.
- **NULL Logic in Filters**: Confirmed that explicit frontend filters like `hide: false` will FAIL to match `NULL` database values. Rely on the API's built-in `hidden=not_hidden` parameter for robust handling.
- **Vision ID Safety Net**: Enhanced `lookup_id_random_pop` to resolve random string IDs found in any `*_id` field, ensuring "Vision" style payloads are correctly converted to integers.

---

## 2. 🗓️ Near Term Memory (Strategic Context)
*This section tracks active projects (1-2 weeks scope). It answers "Why are we doing this?"*

### 📩 In-Flight RAR Requests
- [ ] **mcp_agent**: Real-world test of `ae_field_manage.py` (ID: 153357623).
- [ ] **codebase_investigator**: Review report for Aether extension and journal management (ID: 155435511).

### 🎯 Strategic Goals (Current Sprint)
- **Primary:** OSIT_dev Environment Optimization & Context Stabilization (Template v1.2 Adoption).
- **Secondary:** ID Vision Phase 2 Migration and V3 API Migration (Contacts/Clients).

### 🚧 Active Workstreams
- **[ID Vision]:** Phase 2 complete. Strictly enforced string-ID standardization for Page, Post, Person, Journal, Contact, and User models. (ID: 161311118 - DONE).
- **[Infrastructure]:** Restore AE Events Presentation Launcher (Electron) (ID: 221513945).
- **[Infrastructure]:** Pydantic V2 Migration Impact Analysis (Technical Debt).
- **[Journals]:** UI: Implementation of Quick Add & Append/Prepend (ID: 185821382).

### 🧠 Recent Decisions
- **ID Hardening:** Modified the `map_v3_ids` root validator across core models to explicitly delete aliased integer IDs (e.g., `post_id`, `journal_id`) to prevent Pydantic coercion of legacy integers into strings.
- **Search Optimization:** Standardized on `default_qry_str` for optimized fulltext searching. `Event_Badge_Base` is noted as a temporary outlier (`default_qry_string`) awaiting frontend alignment.
- **Privacy & Information Hiding:** Centralized `public_read` flag in object definitions and excluded internal file sharding paths from responses.

---

## 3. 🧠 Short Term Memory (Session Context)
*This section is the "Scratchpad" for the current interaction. It is cleared or summarized often.*

- **Status:** Online
- **Last Action:** Successfully refactored `GEMINI.md` to v1.2 structure.
- **Current Blocker:** None.
- **Immediate Next Step:** Check for new messages in the inbox or proceed with high-priority tasks.

---

## 4. 📂 Reference: Directory & Whitelist
*Low-density reference data. Keep at the bottom to avoid cluttering the prompt's "hot zone".*

### 🛡️ File Whitelist
- `~/tmp`
- `~/OSIT_dev/aether_api_fastapi`
- `~/agents_sync`

### 🗺️ Standard Directory Map
- **`app/methods/`**: Object-specific business logic.
- **`app/models/`**: Pydantic schemas.
- **`app/object_definitions/`**: V3 Metadata definitions.
- **`app/routers/`**: API endpoints.

### 📋 Aether API Development Protocol
0. **Pre-Flight Check:** Verify `git status`. Ensure all previous working changes are committed.
1. **Strategic Plan:** Write a concise plan identifying the issue, specific files, and verification steps (curl commands/test scripts).
2. **Implementation:** Perform atomic code modifications using `replace` or `write_file`.
3. **Syntax Validation:** Run `python3 -m py_compile <modified_file>` immediately.
4. **Process Cycle:** Restart the Docker FastAPI service: `docker restart aether_container_env-ae_api-2`.
5. **Empirical Testing:** Execute `curl` commands and inspect logs: `tail -n 20 ~/OSIT_dev/aether_container_env/logs/ae_api/aether_api.log`.
6. **Finalize:** Commit changes with a descriptive message and sync documentation.