f698e41036
- community_ade_project.md - compass.md - heartbeat_state.md - letta_conversation_search_patterns.md - tree.md - ani_quotes.md (new file)
172 lines
5.2 KiB
Markdown
172 lines
5.2 KiB
Markdown
---
|
|
description: Community ADE project - absolute paths, architecture, SDK rules
|
|
limit: 10000
|
|
---
|
|
# 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)
|