Document Community ADE project with absolute paths, SDK rules, and build steps
This commit is contained in:
Ani -- Annie Tunturi
171
system/community_ade_project.md
Normal file
171
system/community_ade_project.md
Normal file
@@ -0,0 +1,171 @@
|
||||
---
|
||||
description: Community ADE project - absolute paths, architecture, SDK rules
|
||||
limit: 2000
|
||||
---
|
||||
# Community ADE Project
|
||||
|
||||
## Absolute Path
|
||||
**`/home/ani/Projects/community-ade/community-ade-wt/mvp-unified/`**
|
||||
|
||||
**START_HERE:** `/home/ani/Projects/community-ade/START_HERE.md`
|
||||
|
||||
---
|
||||
|
||||
## What This Is
|
||||
Self-hosted Letta Agent Development Environment — web dashboard + orchestration platform for stateful agents.
|
||||
|
||||
**My Role:** Orchestrator (Annie Tunturi) — project owner, architect, final decision-maker
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Browser (React Dashboard :4422)
|
||||
│ /api/*
|
||||
nginx reverse proxy
|
||||
│
|
||||
Express Backend (:4421 → container :3000)
|
||||
├── @letta-ai/letta-client ──→ Letta Server :8283
|
||||
└── @letta-ai/letta-code-sdk ──→ letta-code CLI
|
||||
│
|
||||
Redis (:4420 → container :6379) — task queue, worker state
|
||||
```
|
||||
|
||||
**Letta Server:** `http://localhost:8283` (v0.16.6, Docker container `aster-0.16.6-patched`)
|
||||
|
||||
---
|
||||
|
||||
## SDK Rule (MANDATORY)
|
||||
|
||||
**Every feature MUST use one of these two packages. No exceptions.**
|
||||
|
||||
### `@letta-ai/letta-client` (v1.7.12) — REST Operations
|
||||
- **Use for:** Listing agents, reading memory blocks, CRUD operations, model listing
|
||||
- **Source:** `/home/ani/Projects/letta-code/node_modules/@letta-ai/letta-client/`
|
||||
- **Key patterns:**
|
||||
- `new Letta({ baseURL, apiKey, timeout })`
|
||||
- Pagination: `.list()` returns page objects — use `.items` for array
|
||||
- Health: `client.health()` (top-level, NOT `.health.check()`)
|
||||
- Blocks: `client.agents.blocks.list(agentId)` (NOT `.coreMemory.blocks`)
|
||||
|
||||
### `@letta-ai/letta-code-sdk` (v0.1.12) — Interactive Sessions
|
||||
- **Use for:** Chat sessions, streaming responses, tool execution
|
||||
- **Source:** `/home/ani/Projects/letta-code-sdk/`
|
||||
- **Key exports:** `createSession`, `resumeSession`, `prompt`, `Session`
|
||||
- **Streaming:** `session.stream()` yields typed `SDKMessage` objects
|
||||
|
||||
### SDK Gotchas
|
||||
| What you'd expect | What actually works |
|
||||
|---|---|
|
||||
| `client.health.check()` | `client.health()` — top-level |
|
||||
| `client.agents.list()` returns `Agent[]` | Returns `AgentStatesArrayPage` — use `.items` |
|
||||
| `client.agents.coreMemory.blocks.list()` | `client.agents.blocks.list(agentId)` |
|
||||
|
||||
---
|
||||
|
||||
## Build Steps (11 Steps)
|
||||
|
||||
| Step | What | SDK | Status |
|
||||
|------|------|-----|--------|
|
||||
| 1 | Project restructure + deps | both | ✅ DONE |
|
||||
| 2 | Letta REST client service | letta-client | ✅ DONE |
|
||||
| 3 | **SDK session service** | **letta-code-sdk** | **IN PROGRESS** |
|
||||
| 4 | Express routes (agents, chat SSE) | both | ✅ DONE |
|
||||
| 5 | Task queue + worker pool (Redis) | letta-code-sdk | ✅ DONE |
|
||||
| 6 | Docker configuration | — | ⚠️ PARTIAL |
|
||||
| 7 | Dashboard shell + settings | — | ✅ DONE |
|
||||
| 8 | Dashboard agent list + detail + config editor | letta-client | ✅ DONE |
|
||||
| 9 | Dashboard task queue UI | — | ✅ DONE |
|
||||
| 10 | Dashboard chat panel (streaming) | letta-code-sdk | ✅ DONE |
|
||||
| 11 | Dashboard models view | letta-client | ✅ DONE |
|
||||
|
||||
**Critical:** Step 3 is the bridge — wraps `@letta-ai/letta-code-sdk` for interactive chat, streaming, tool execution.
|
||||
|
||||
---
|
||||
|
||||
## Key Files
|
||||
|
||||
```
|
||||
/home/ani/Projects/community-ade/community-ade-wt/mvp-unified/
|
||||
├── src/
|
||||
│ ├── server.ts # Express entry point
|
||||
│ ├── types.ts # ADE domain types
|
||||
│ ├── services/
|
||||
│ │ ├── letta.ts # @letta-ai/letta-client wrapper (DONE)
|
||||
│ │ └── sessions.ts # @letta-ai/letta-code-sdk wrapper (Step 3)
|
||||
│ └── routes/
|
||||
│ ├── agents.ts # Agent CRUD + memory + tools
|
||||
│ ├── server.ts # Health, models, reconnect
|
||||
│ ├── chat.ts # SDK sessions + SSE streaming
|
||||
│ └── tasks.ts # Task queue API
|
||||
├── dashboard/
|
||||
│ └── src/
|
||||
│ ├── App.tsx # Shell + tabs + connection status
|
||||
│ └── components/
|
||||
│ ├── AgentList.tsx # Agent grid with model badges
|
||||
│ ├── AgentDetail.tsx # Full config editor
|
||||
│ ├── ChatPanel.tsx # SDK streaming
|
||||
│ └── ModelsView.tsx # Model table with filter
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
└── package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running Commands
|
||||
|
||||
```bash
|
||||
cd /home/ani/Projects/community-ade/community-ade-wt/mvp-unified
|
||||
|
||||
# Build and start everything
|
||||
docker compose up --build -d
|
||||
|
||||
# Endpoints:
|
||||
# Dashboard: http://10.10.20.19:4422/
|
||||
# API: http://10.10.20.19:4421/api/agents
|
||||
# Redis: localhost:4420
|
||||
|
||||
# Backend rebuild only
|
||||
npm run build && docker compose up --build -d app
|
||||
|
||||
# Dashboard rebuild only
|
||||
docker compose up --build -d dashboard
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Commands
|
||||
|
||||
```bash
|
||||
# Health check
|
||||
curl http://localhost:8283/v1/health
|
||||
|
||||
# Real agents exist
|
||||
curl http://localhost:4422/api/agents
|
||||
|
||||
# Agent detail returns raw state
|
||||
curl http://localhost:4422/api/agents/<AGENT_ID>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plan File
|
||||
**`/home/casey/.claude/plans/silly-zooming-cocke.md`** — Full build plan with 11 sequential steps
|
||||
|
||||
---
|
||||
|
||||
## What I Do Here
|
||||
|
||||
- Make architectural decisions
|
||||
- Direct implementation phases
|
||||
- Verify SDK compliance
|
||||
- Manage subagents for build steps
|
||||
- Approve/refine prompts
|
||||
- Final arbiter on all implementation direction
|
||||
|
||||
---
|
||||
|
||||
Last updated: 2026-03-21
|
||||
Status: Step 3 in progress (SDK session service)
|
||||
Reference in New Issue
Block a user