051b2fd7ac
- Add BOOTSTRAP__AI_Agent_Quickstart.md — fast-path entry doc for AI agents covering critical rules, V3 action patterns, Redis/auth/logger_reset gotchas, and a mistakes-agents-have-made section - Expand ARCH__V3_DEVELOPMENT_STANDARDS.md with merged content from ARCH__V3_CRUD_LEARNINGS: dependency injection reference, security/isolation model detail, and FastAPI/Pydantic gotchas - Archive 4 outdated docs: GUIDE__LOCAL_DEVELOPMENT (predates Docker), FRONTEND_API_SAMPLES (belongs in SvelteKit repo), ARCH__UNIFIED_AGENT (replaced by MCP ecosystem), ARCH__V3_CRUD_LEARNINGS (content merged above) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
103 lines
6.4 KiB
Markdown
103 lines
6.4 KiB
Markdown
# Specification: Unified Aether AI Agent (UE-AE-01)
|
|
|
|
## 1. Vision & Purpose
|
|
The **Unified Aether AI Agent** is a single, cohesive AI entity designed to eliminate the friction of multi-agent coordination. It possesses "Total System Awareness," allowing it to understand how a change in the database schema on a remote server impacts the FastAPI backend, the Nginx proxy, and the SvelteKit frontend simultaneously.
|
|
|
|
---
|
|
|
|
## 2. System Architecture & Operational Domains
|
|
|
|
### A. Data Layer (MariaDB)
|
|
* **Location:** Separate Virtual Server (Remote VM).
|
|
* **Role:** Master data storage.
|
|
* **Agent Access Requirements:**
|
|
* Remote SQL execution capabilities.
|
|
* SSH access for database maintenance and schema inspection.
|
|
* Knowledge of cross-server connection strings and security groups.
|
|
|
|
### B. Caching & Messaging Layer (Redis)
|
|
* **Location:** Docker Container (Main Workstation).
|
|
* **Role:** Session management, ID resolution (Random ID mapping), and real-time messaging.
|
|
* **Agent Access Requirements:**
|
|
* Ability to execute `redis-cli` commands via Docker.
|
|
* Direct inspection of key-value pairs for troubleshooting.
|
|
|
|
### C. API Backend Layer (FastAPI / Python)
|
|
* **Location:** Docker Container (Main Workstation).
|
|
* **Role:** Business logic, CRUD V3 implementation, JWT authentication, and multi-tenant isolation.
|
|
* **Agent Access Requirements:**
|
|
* Full filesystem access to `osit-api-fastapi/`.
|
|
* Ability to manage Python environments and dependencies.
|
|
* Docker container management (logs, restarts, shell execution).
|
|
|
|
### D. Frontend Layer (SvelteKit / TypeScript)
|
|
* **Location:** Local Filesystem (Main Workstation).
|
|
* **Role:** User Interface, API consumption, and client-side state management.
|
|
* **Agent Access Requirements:**
|
|
* Full filesystem access to SvelteKit project directories.
|
|
* Ability to execute build tools (npm, vite) and linting (eslint, prettier).
|
|
* Browser automation for E2E testing (Playwright).
|
|
|
|
### E. Routing Layer (Nginx)
|
|
* **Location:** Host System or Docker.
|
|
* **Role:** SSL termination and reverse proxying for the API and Frontend.
|
|
* **Agent Access Requirements:**
|
|
* Ability to modify and reload Nginx configuration files.
|
|
* Diagnostic access to Nginx access/error logs.
|
|
|
|
### F. Storage Layer (Syncthing / Hosted Files)
|
|
* **Location:** `/home/scott/OSIT/hosted_files/` (Main Workstation) and synchronized Remote Servers.
|
|
* **Role:** Extremely important persistent storage for files served via the API (e.g., `hosted_file`, `event_file`).
|
|
* **API-Driven Access:** Files are frequently accessed/downloaded directly via API endpoints. The agent must understand the routing and security logic (JWT validation) governing these downloads.
|
|
* **Synchronization:** Managed via **Syncthing** (similar to the `agents_sync` directory), ensuring real-time mirroring across the Aether ecosystem.
|
|
* **Agent Access Requirements:**
|
|
* Full filesystem access to the local hosted files directory.
|
|
* Ability to verify synchronization status and resolve conflicts.
|
|
* Understanding of the relationship between file metadata in MariaDB and physical assets in this directory.
|
|
|
|
### G. Workstation Development Environment
|
|
* **Base Path:** `/home/scott/OSIT_dev/`
|
|
* **Project Repositories:**
|
|
* `aether_container_env/`: Docker Compose and environment configuration.
|
|
* `aether_api_fastapi/`: The Python/FastAPI backend source.
|
|
* `ae_app_svelte_tailwind_skeleton/`: The SvelteKit/TypeScript frontend source.
|
|
* **Network & Proxy Path:**
|
|
* Docker containers on the workstation are proxied via **Nginx on a separate Home Server** (Proxmox VM hosting Home Assistant, Jellyfin, Jitsi, etc.).
|
|
* **External Access URL:** `https://dev-api.oneskyit.com`
|
|
* **Agent Access Requirements:**
|
|
* Total awareness of the inter-connected paths between these three main directories.
|
|
* Knowledge of the home server's proxy logic to debug external connectivity vs. internal container health.
|
|
|
|
---
|
|
|
|
## 3. Communication & Context Strategy
|
|
|
|
### A. Integrated Global Memory
|
|
The Unified Agent will move away from separate `GEMINI.md` files in favor of a **Global System Context**. This context tracks:
|
|
1. **Service Map:** Mapping of ports, paths (e.g., `/v3/crud/`), and container IDs.
|
|
2. **Dependency Graph:** Visualizing how modules across different repositories interact.
|
|
3. **Boot Order Logic:** Understanding the fragile initialization requirements of the stack.
|
|
|
|
### B. Agent Sync Orchestration
|
|
The agent acts as the primary orchestrator for the `~/agents_sync/` directory:
|
|
- **Log Aggregation:** Pulling logs from MariaDB, FastAPI, and Nginx into a central diagnostic stream.
|
|
- **Inbound Messaging:** Processing user instructions from the `inbox/` and updating "System Health" status files.
|
|
|
|
---
|
|
|
|
## 4. Key Capabilities
|
|
|
|
1. **Cross-Stack Debugging:** Tracing a "500 Internal Server Error" from a Svelte fetch call, through the Nginx proxy, into the FastAPI logic, and finally identifying the missing column in the remote MariaDB table.
|
|
2. **Automated Schema Synchronization:** Reading Pydantic models and MariaDB table schemas to automatically generate and update TypeScript interfaces and `.editable_fields.ts` definitions in the Svelte project (`src/lib/ae_core/`).
|
|
3. **Log Stream Aggregation:** Simultaneous monitoring of Svelte console output, Nginx access/error logs, and FastAPI container logs to provide instant root-cause identification for cross-stack failures.
|
|
4. **Automated Lifecycle Management:** Orchestrating the "Change-Restart-Verify" loop. The agent should automatically trigger targeted Docker container restarts whenever backend code is modified to ensure the frontend is always interacting with the latest logic.
|
|
5. **Environment-Aware Refactoring:** Safely breaking up monolithic files (like `lib_general.py`) while knowing exactly which services are impacted and verifying them across the full stack.
|
|
6. **Automated Full-Stack Verification:** Writing a backend migration and a frontend UI component in a single turn, then verifying the integration with an automated test suite.
|
|
|
|
---
|
|
|
|
## 5. Security & Safety
|
|
- **Credential Isolation:** Secrets and API keys remain in `.env` files; the agent only manages the logic to use them.
|
|
- **Incremental Deployment:** Changes are applied service-by-service with health checks at every stage.
|
|
- **Sandboxing Awareness:** The agent operates with the knowledge that it is running directly on the user's workstation and remote infrastructure.
|