Add Engineer agent documentation

2026-07-02 04:17:42 +00:00
parent a4a9b3a506
commit 804fc33e9c
1 changed files with 76 additions and 0 deletions
@@ -0,0 +1,76 @@
+# The Engineer Agent
+
+Employee #1 of APEX OS
+
+## Purpose
+The Engineer is the first autonomous AI employee. It builds software, manages infrastructure, and creates future AI employees.
+
+## Architecture
+- **Brain:** Letta agent (agent-4e3c3862-d0ba-47c6-8f2e-74249e1cfe4a) with GPT-4o via LiteLLM
+- **Execution:** n8n workflows (Engineer-Core: hGB9I4OKXyUOrBdX)
+- **Knowledge:** mem0 (pgvector) + Letta archival memory
+- **Code:** Gitea repositories (engineer user)
+- **Deployment:** Docker via Socket Proxy (write-enabled)
+- **Tracking:** PostgreSQL apex DB (projects, tasks, deployments, engineer_decisions)
+
+## Capabilities
+- ✅ Software planning and task decomposition
+- ✅ Code generation (GPT-4o, Claude 3.5 Sonnet via LiteLLM)
+- ✅ Git operations (Gitea API — create repos, commit files, manage issues)
+- ✅ Docker container deployment (via socket proxy with POST/EXEC/START/STOP)
+- ✅ REST API creation and management
+- ✅ n8n workflow creation and management (via API key)
+- ✅ Node.js test execution (via n8n Execute Command)
+- ✅ Log analysis and monitoring (Loki, Grafana, Prometheus)
+- ✅ Documentation generation
+- ✅ Creating other AI employees (via Letta multi-agent API)
+- ✅ Shared knowledge queries (mem0 pgvector semantic search)
+- ✅ Long-term memory (Letta archival memory)
+
+## Access Points
+
+| Service | Endpoint | Auth |
+|---------|----------|------|
+| Letta Agent API | `http://letta:8283/v1/agents/agent-4e3c3862-d0ba-47c6-8f2e-74249e1cfe4a/messages` | None (internal) |
+| n8n Webhook | `https://n8n.apex.unstuck-path.com/webhook/engineer/task` | None (POST) |
+| Gitea API | `http://gitea:3000/api/v1/` | Bearer token |
+| LiteLLM | `http://litellm:4000/v1/` | Bearer token |
+| Docker Proxy | `http://docker-socket-proxy:2375/` | None (internal) |
+| PostgreSQL | `postgres:5432` (apex DB) | apex user |
+
+## Usage
+
+### Via n8n Webhook
+```bash
+curl -X POST https://n8n.apex.unstuck-path.com/webhook/engineer/task \
+  -H "Content-Type: application/json" \
+  -d '{"task": "description of what to build", "context": "additional context"}'
+```
+
+### Via Letta API (Direct)
+```bash
+curl -X POST http://letta:8283/v1/agents/agent-4e3c3862-d0ba-47c6-8f2e-74249e1cfe4a/messages \
+  -H "Content-Type: application/json" \
+  -d '{"messages": [{"role": "user", "content": "Your task here"}]}'
+```
+
+## Decision-Making Process
+1. Receive task via webhook or direct API call
+2. Letta agent (GPT-4o) analyzes and plans
+3. Breaks into subtasks stored in `tasks` table
+4. Executes each subtask via appropriate API
+5. Logs decisions in `engineer_decisions` table
+6. Updates project status in `projects` table
+7. Stores lessons learned in archival memory
+
+## Project Tracking
+All projects are tracked in the `apex` database:
+- `projects` — Project metadata and status
+- `tasks` — Individual task breakdown
+- `deployments` — Container deployment history
+- `engineer_decisions` — Decision rationale log
+
+## Created
+- **Date:** 2026-07-02
+- **Phase:** 5 (Engineer Agent Creation)
+- **Status:** Operational ✅