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: Offline / Wrapped

• Last Action: Overhauled the V3 Frontend Integration Guide and synced to agents_sync.

• Achievements: Finalized Data Store V3, fixed legacy router bugs, and established V4 standards documentation.

• Immediate Next Step: 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.