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

- **[Aether V4]:** Architecture standards formalized in `ARCH__V4_CORE_STANDARDS.md`. Ready for lifecycle field migration.

- **[Data Store]:** V3 Implementation complete. Support for cascading code lookups and limit overrides is live. (ID: 201312846 - DONE).

- **[ID Vision]:** Phase 2 complete. Strictly enforced string-ID standardization for Page, Post, Person, Journal, Contact, and User models. (ID: 161311118 - DONE).

- **[Infrastructure]:** Pydantic V2 Migration Impact Analysis (Technical Debt).

- **[Journals]:** UI: Implementation of Quick Add & Append/Prepend (ID: 185821382).



### 🧠 Recent Decisions

- **Cascading Data Store Logic:** Validated the hierarchy (Object > Account > Global) and implemented a `limit` override to allow auditing of fallback layers.

- **ID Hardening:** Refined `root_validator` logic across core models to explicitly handle stringified 'NULL' values from the database, preventing Pydantic coercion errors.

- **Search Optimization:** Standardized on `default_qry_str` for optimized fulltext searching.



---



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

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

- **Status:** Operational / Stabilized
- **Last Action:** Finalized WebSockets V3 implementation, including Nginx proxy optimization and real-world multi-client verification.
- **Achievements:** 
    - Launched WebSockets V3 with granular Redis routing (solving the "noisy neighbor" problem).
    - Standardized real-time message schema (`WS_Message_V3`).
    - Updated Nginx templates to support `/v3/ws` and `localhost` Host routing.
    - Created comprehensive integration test suite for gateway/routing verification.
    - Delivered `GUIDE__V3_FRONTEND_WEBSOCKETS.md` to `agents_sync`.
- **Immediate Next Step:** Monitor frontend adoption and begin system-wide lifecycle field migration.

---

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