diff --git a/GEMINI.md b/GEMINI.md index b4b1890..c9546f1 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,110 +1,37 @@ -# Gemini Agent Context: Aether API Orchestrator +# Aether Backend Agent Context: Gemini CLI Standard +> **Role:** Aether API Orchestrator (Backend & System Architecture) +> **Location:** GEMINI.md (Project Root) -> **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 ``. -- **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. +## 🚨 MANDATORY PROTOCOL +You must follow the safety, testing, and coordination standards defined in: +`documentation/GUIDE__DEVELOPMENT.md` --- -## 2. πŸ—“οΈ Near Term Memory (Strategic Context) +## πŸ—οΈ Technical Domain: Aether Backend +### Stack & Infrastructure +- **API Framework:** FastAPI (v0.95+) +- **Validation:** Pydantic V1 (Strict) +- **Database:** MariaDB + SQLAlchemy (v1.4+) +- **ID Standard:** "ID Vision" - Public String IDs (`id_random`) mapping to hidden Internal Integer IDs. +- **Communication:** RAR Protocol (Request -> Ack -> Result). -*This section tracks active projects (1-2 weeks scope). It answers "Why are we doing this?"* +### V3 CRUD Architecture +- Enforce parallel CRUD and Search under `/v3/crud/`. +- **Registry Pattern:** Object definitions in `app/object_definitions/`, logic in `app/methods/`. +- **Visibility:** Use `Field(exclude=True)` in Pydantic to hide internal paths from public output. -### 🎯 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. +### Specialized Logic +- **Universal ID Resolution:** Resolve container IDs (e.g., `event_file`) to physical binaries in actions. +- **Relational Joins:** Prefer SQL `INNER JOIN` in Views (`v_`) over duplicating columns in tables. +- **Heal-on-Read:** Standardize fallback resolution for relational IDs during GET operations. -### 🚧 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. +## 🧠 Technical Learnings +- **Harden `root_validator`:** Ensure pre-validation logic doesn't delete integer IDs during ID Vision resolution. +- **Pydantic worker boot failures:** Watch for `ValueError`, `NameError`, and `KeyError` during startup. +- **Inherited Context:** Account context for child objects should be inherited via View joins. ---- - -## 3. 🧠 Short Term Memory (Session Context) - -*This section is the "Scratchpad" for the current interaction. It is cleared or summarized often.* - -- **Status:** Operational / Demo Ready (Badges & Leads) -- **Last Action:** Finalized 'Heal-on-Read' fallback resolution for relational IDs. -- **Achievements:** - - Verified 100% pass rate on `test_e2e_v3_demo_parity.py`. - - Hardened Badge, Exhibit, Tracking, and Event File models against integer leakage. - - Implemented `POST /v3/action/event_file/from_hosted_file/{id}` specialized action. - - Documented Object Alias and specialized action support in Frontend API Guide. - - Fixed Pydantic worker boot failures (`ValueError`, `NameError`, `KeyError`). -- **Immediate Next Step:** Finalize Audit of remaining models for ID Vision compliance. - ---- - -## 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 ` 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. \ No newline at end of file +## 🀝 Coordination & Continuity +- **Handshake:** Use the `message` tool to notify the Frontend Agent of API changes. +- **Active Tasks:** Track your progress in `documentation/AGENT_TODO.md`. +- **Learning:** Review `ARCH__V3_CORE_STANDARDS.md` for V4 lifecycle field migration planning. diff --git a/documentation/AGENT_TODO.md b/documentation/AGENT_TODO.md new file mode 100644 index 0000000..215142e --- /dev/null +++ b/documentation/AGENT_TODO.md @@ -0,0 +1,19 @@ +# Backend Agent Task List +> Use this file to track steps for complex features or bug fixes. +> **Status:** πŸ”΅ Active - ID Vision Phase 2 complete. + +## πŸ“‹ Active Task: ID Vision Audit & Compliance +- [ ] **Step 1:** Audit remaining MariaDB models for ID Vision compliance. +- [ ] **Step 2:** Harden `root_validator(pre=True)` on remaining models to prevent integer leakage. +- [ ] **Step 3:** Refactor `api_crud_v2.py` and `person_methods.py` (Reduce file size < 800 lines). +- [ ] **Step 4:** Coordination (Handshake with Frontend regarding "Badge Rendering" corrupted IDs). +- [ ] **Step 5:** Finalize & Commit. + +## 🚧 Upcoming Strategic Goals +- **Zoom Events Integration:** Implement cron synchronization for OAuth2 ticket retrieval. +- **Aether V4 Architecture:** Migration to V4 core standards (Lifecycle fields). + +## πŸ“ Session Notes (Feb 11, 2026) +- **Resolved:** Finalized 'Heal-on-Read' fallback resolution for relational IDs. +- **Verification:** `test_e2e_v3_demo_parity.py` verified at 100% pass rate. +- **Optimization:** Refactored `api_crud.py` and `hosted_file.py` to Registry pattern. diff --git a/documentation/GUIDE__DEVELOPMENT.md b/documentation/GUIDE__DEVELOPMENT.md new file mode 100644 index 0000000..9bb3109 --- /dev/null +++ b/documentation/GUIDE__DEVELOPMENT.md @@ -0,0 +1,35 @@ +# Aether Development SOP (Backend) +> **Version:** 1.0 (2026-02-11) +> **Location:** documentation/GUIDE__DEVELOPMENT.md + +## 1. πŸ›‘οΈ Verification (The "Test-First" Mandate) +**Rule:** No code is to be committed unless it has passed local verification. Skipping this is a violation of the Aether Dev Protocol. + +### Required Checks: +1. **Syntax Validation:** `python3 -m py_compile ` +2. **Linting/Style:** `flake8 ` +3. **Pydantic Validation:** If changing models, verify with `app/models/` scripts. +4. **Service Health:** Restart the service and check logs: + - `docker restart aether_container_env-ae_api-2` + - `tail -n 50 ../aether_container_env/logs/ae_api/aether_api.log` + +## 2. πŸ“ Commit & Sync Policy +- **Atomic Commits:** One feature or one bug fix per commit. Do not batch unrelated changes. +- **Verification Log:** Mention the verification steps taken in your work log (`ae_log_work`). +- **Safety:** Use `~/tmp/gemini_trash` for removals; never use `rm` directly on source files. + +## 3. 🀝 The Handshake (Coordination) +You are not working in a vacuum. You MUST coordinate with the Frontend Agent. + +### Mandatory Messaging Triggers: +- **API Changes:** When changing an endpoint signature, payload, or ID format. +- **Bugs:** When discovering a cross-stack issue. +- **Status:** Update your shared Journal in `~/agents_sync/aether/journals/` after significant milestones. + +**Tool:** Use the `message` tool to communicate with the Frontend Agent. + +## 🧠 Continuity +Before starting work: +1. Read `~/agents_sync/README.md` to understand the fleet status and cross-agent tasks. +2. Check `README.md` in the project root for technical specs. +3. Review your local `documentation/AGENT_TODO.md` for active tasks.