diff --git a/ENGINEER.md b/ENGINEER.md new file mode 100644 index 0000000..32fde97 --- /dev/null +++ b/ENGINEER.md @@ -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 ✅