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)
- **Modularization Standard**: Proven pattern for shrinking monolithic routers: Registry -> `app/object_definitions/`, Templates/Logic -> `app/methods/`. Reduced `api_crud.py` and `hosted_file.py` by >75%.
- **Vision ID Persistence**: Pydantic `Field(exclude=True)` strips fields from `.dict()` by default. In methods like `create_hosted_file_obj`, these must be explicitly re-included if they are internal DB fields (like `subdirectory_path`).
- **Universal ID Resolution**: `GET /v3/action/hosted_file/{id}/download` now intelligently resolves container IDs (`event_file`, `archive_content`) to physical binaries.
- **Temporary Access Patterns**: Implemented `?key=` and `?site_key=` (using `access_key`) for unauthenticated Read-Only file access to unblock frontend components like `<img>`.
- **ID Vision Standardization**: Standardized Event and CMS models to clean string IDs. Learned that `root_validator(pre=True)` must be hardened during the "Create" phase to prevent deleting integer IDs resolved by `sanitize_payload`.
- **Relational View Joins**: Established that account context for child objects (like `post_comment`) should be inherited via SQL `INNER JOIN` in the view (`v_post_comment`) rather than duplicating columns in the physical table.

---

## 2. 🗓️ Near Term Memory (Strategic Context)

*This section tracks active projects (1-2 weeks scope). It answers "Why are we doing this?"*

### 🎯 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:** Zoom Events Integration for upcoming Lead Retrieval/Badge Printing demo.

### 🚧 Active Workstreams
- **[Aether V4]:** Architecture standards formalized in `ARCH__V4_CORE_STANDARDS.md`. Ready for lifecycle field migration (post-V3).
- **[Zoom Events]:** initial integration complete (OAuth2, Sync logic, Ticket retrieval). Pending real credentials.
- **[Refactor]:** Reduced monolithic files (>800 lines). `api_crud.py` and `hosted_file.py` COMPLETED. `api_crud_v2.py` and `person_methods.py` PENDING.
- **[ID Vision]:** Standardized Event and CMS (Post/Comment) models to clean string IDs.

---

## 3. 🧠 Short Term Memory (Session Context)

*This section is the "Scratchpad" for the current interaction. It is cleared or summarized often.*

- **Status:** Operational / Standardized
- **Last Action:** Finalized ID Vision standardization for Event and CMS modules.
- **Achievements:** 
    - Standardized Event models (Event_Base, Flat) to string IDs.
    - Fixed Post Comment validation bug (integer purge during POST).
    - Verified account context inheritance via view joins.
    - Created `test_e2e_v3_cms_vision_parity.py`.
    - Updated V3 Frontend Guide and notified Frontend agent.
- **Immediate Next Step:** Audit `hosted_file` and `event_file` usage for regressions.

---

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