Fimeg/community-ade
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b67fae0f53ad7939e4a43cf4c057b33c62b62411
community-ade/START_HERE.md
Annie Tunturi b67fae0f53 docs: Add START_HERE guide and FUTURE_PHASES planning
2026-03-28 23:42:42 -04:00

14 KiB
Raw Blame History

Community ADE — Start Here

What: Self-hosted Letta Agent Development Environment — a web dashboard + orchestration platform for stateful agents.

Where: /home/ani/Projects/community-ade/community-ade-wt/mvp-unified/

Letta Server: http://localhost:8283 (v0.16.6, Docker container aster-0.16.6-patched)

Orchestrator: Ani (Annie Tunturi) — project owner, architect, and final decision-maker on all implementation direction.

How This Project Got Here

Ani directed the research phase, established the competitive analysis, designed the orchestration architecture, and then took direct control of the implementation. She consolidated the project into a single unified codebase (mvp-unified/), enforced SDK-first architecture across all components, and drove the build sequence from backend services through to a functional dashboard with full agent creation, configuration editing, streaming chat, and task orchestration.

The research docs in docs/ represent foundational work — competitive analysis, queue architecture, memory curation design, approval system architecture. The archive (community-ade-wt/_archive/) contains prior model-specific implementations that validated the architecture before Ani unified them. The implementation in mvp-unified/ is the production codebase.

Read These First

  1. This file — project orientation, architecture, SDK rules
  2. docs/FUTURE_PHASES.md — roadmap for approval system, memory curation, integrations
  3. docs/ade-research.md — competitive analysis (Letta vs Intent vs Warp)
  4. docs/ade-phase1-orchestration-design.md — task queue architecture
  5. docs/community-ade-research-synthesis-2026-03-18.md — technical patterns + gap analysis

Architecture

Browser (React Dashboard :4422)
    │ REACT_APP_API_URL → backend
    │
Express Backend (:4421)
    ├── @letta-ai/letta-client ──→ Letta Server :8283 (REST: agents, memory, tools, models)
    ├── @letta-ai/letta-code-sdk ──→ letta-code CLI ──→ Letta Server (sessions, streaming, chat)
    └── ioredis ──→ Redis (:4420) — task queue, worker state

Current deployment: host-only (no Docker for app/dashboard — SDK sessions require letta-code CLI on the host). Redis runs in a standalone Docker container (ade-redis).

SDK Rule (MANDATORY — READ THIS BEFORE WRITING ANY CODE)

Every feature MUST use one of these two packages. There are no exceptions.

@letta-ai/letta-client (v1.7.12) — REST Operations

  • Use for: Listing/creating/deleting agents, reading memory blocks, CRUD operations, model listing, tool listing, health checks, agent config updates
  • Source: /home/ani/Projects/letta-code/node_modules/@letta-ai/letta-client/
  • API docs: http://localhost:8283/docs (Swagger UI on running Letta server)
  • Key patterns:
    • Client init: new Letta({ baseURL, apiKey, timeout })
    • Pagination: all .list() calls return page objects — access .items for the array
    • Health: client.health() (top-level method, NOT .health.check())
    • Blocks: client.agents.blocks.list(agentId) (NOT .coreMemory.blocks)
    • Agent create: client.agents.create({ name, model, system, tool_ids, include_base_tools })
    • Agent update: client.agents.update(agentId, params) — accepts any field from AgentUpdateParams
    • Tools (global): client.tools.list() — all tools on the server
    • Tools (per-agent): client.agents.tools.list(agentId) — tools attached to an agent
  • Type declarations: Read node_modules/@letta-ai/letta-client/api/types.d.ts when unsure about method signatures

@letta-ai/letta-code-sdk (v0.1.12) — Interactive Sessions

  • Use for: Chat sessions, streaming responses, tool execution, bootstrapping conversation state
  • Source: /home/ani/Projects/letta-code-sdk/
  • Key exports: createSession, resumeSession, prompt, Session
  • Key types: SDKMessage, SDKAssistantMessage, SDKReasoningMessage, SDKToolCallMessage, SDKToolResultMessage, SDKResultMessage
  • Streaming: session.stream() yields typed SDKMessage objects — render each type differently in the UI
  • ESM-only: Must use dynamic import() from CJS project — see services/sessions.ts for the pattern

What This Means In Practice

  • Need to list agents? → letta-client → client.agents.list()
  • Need to create an agent? → letta-client → client.agents.create()
  • Need to edit agent memory? → letta-client → client.agents.blocks.update()
  • Need to list available tools? → letta-client → client.tools.list()
  • Need to chat with an agent? → letta-code-sdk → createSession() + session.send()
  • Need real-time streaming? → letta-code-sdk → session.stream()
  • Need to run a background task? → letta-code-sdk → worker spawns session, calls session.runTurn()

No standalone implementations. No mock data. No in-memory stores pretending to be agents. No per-model silos. No hand-rolled HTTP calls to Letta endpoints when the SDK already wraps them.

How to Enforce SDK Compliance in Future Phases

When directing other LLMs (Kimi, GLM, or future Claude sessions) to implement new phases, follow this protocol:

1. Always Start With the SDK Source

Before writing any service code, the implementer must read the actual SDK type declarations:

# For REST operations — check what methods exist
cat node_modules/@letta-ai/letta-client/api/types.d.ts | head -200

# For session operations — check SDK exports
ls /home/ani/Projects/letta-code-sdk/src/
cat /home/ani/Projects/letta-code-sdk/src/index.ts

2. Include This Checklist in Every Phase Prompt

Before writing code, answer these for each feature:
- [ ] Which SDK package handles this? (letta-client or letta-code-sdk)
- [ ] What is the exact method signature? (read the .d.ts, don't guess)
- [ ] What does the return type look like? (page object with .items? raw array? single object?)
- [ ] Does this need pagination handling?
- [ ] Am I duplicating something the SDK already does?

3. Known SDK Gotchas

What you'd expect What actually works
client.health.check() client.health() — top-level method
client.agents.list() returns Agent[] Returns AgentStatesArrayPage — use .items
client.agents.coreMemory.blocks.list() client.agents.blocks.list(agentId)
agent.tool_ids agent.tools — array of tool objects
Block update with nested params client.agents.blocks.update(blockLabel, { agent_id, value })
import { createSession } in CJS Must use const sdk = await import('@letta-ai/letta-code-sdk')

4. Verification Gate

Every phase must be verifiable against the running Letta server before moving on:

curl http://localhost:8283/v1/health          # Letta healthy
curl http://localhost:4421/api/agents         # Real agents from Letta
curl http://localhost:4421/api/agents/tools   # Available tools from Letta

Build Status

Phase 1 — Core Platform (COMPLETE)

Step What Status
1 Project restructure + deps DONE
2 Letta REST client service DONE
3 SDK session service (ESM interop) DONE
4 Express routes (agents, server, chat SSE) DONE
5 Task queue + worker pool (Redis Streams) DONE
6 Docker configuration PARTIAL — host-only for now
7 Dashboard shell + settings DONE
8 Agent list + detail + config editor DONE
9 Task queue UI DONE
10 Chat panel (SSE streaming) DONE
11 Models view DONE

Phase 1.5 — Agent Management (COMPLETE)

Feature What Status
Agent creation wizard 5-step wizard (info → model → tools → system prompt → review) DONE
Agent create API POST /api/agents via client.agents.create() DONE
Tool listing API GET /api/agents/tools via client.tools.list() DONE
Agent deletion DELETE /api/agents/:id + confirmation UI DONE
Cross-tab navigation "Chat with Agent" from detail → Chat tab DONE

Verification Pipeline (REPAIRED)

A multi-layer verification system at src/verification/ with:

  • Static checks (schema validation via Zod v4, linting, type checking)
  • Dynamic test execution (Jest, Mocha, Vitest, Pytest, Go)
  • Human review queue with approval/rejection + webhooks
  • Subagent delegation via letta-code-sdk (iterative refinement)
  • Config builder with fluent API + presets (minimal, standardTypeScript, fullCI, quick)

Status: Fully compiles. Types rewritten to match executor design. Zod v4 added as dependency. Included in build (tsconfig.json). Ready for integration with task queue worker pipeline.

Future Phases

See docs/FUTURE_PHASES.md for the full roadmap.

Key Files

mvp-unified/
├── src/
│   ├── server.ts              # Express entry point
│   ├── types.ts               # ADE domain types
│   ├── services/
│   │   ├── letta.ts           # @letta-ai/letta-client wrapper
│   │   ├── sessions.ts        # @letta-ai/letta-code-sdk wrapper (ESM dynamic import)
│   │   ├── queue.ts           # Redis Streams task queue
│   │   └── worker.ts          # Worker pool for background agent tasks
│   ├── verification/          # Multi-layer verification pipeline (needs repair)
│   │   ├── checks/            # SchemaValidator, LinterRunner, TypeChecker
│   │   ├── executors/         # TestExecutor, SubagentDispatcher, VerificationOrchestrator
│   │   ├── review/            # HumanReviewQueue
│   │   └── utils/             # auditLogger, configBuilder, helpers
│   └── routes/
│       ├── agents.ts          # Agent CRUD + memory + tools + create + delete
│       ├── server.ts          # Health, models, reconnect
│       ├── chat.ts            # SDK sessions + SSE streaming
│       └── tasks.ts           # Task queue API
├── dashboard/
│   └── src/
│       ├── App.tsx            # Shell + tabs + connection status
│       ├── styles.css         # Dark theme, unified design system
│       └── components/
│           ├── AgentList.tsx       # Agent grid + "New Agent" button
│           ├── AgentDetail.tsx     # Full config editor — all LLM params, memory, system prompt
│           ├── ChatPanel.tsx       # SSE streaming chat with SDK message types
│           ├── ModelsView.tsx      # Model table with provider filter
│           ├── TaskQueue.tsx       # Task list, stats, create form, cancel/retry
│           ├── ServerSettings.tsx  # Connection config
│           └── wizard/
│               ├── AgentWizard.tsx       # 5-step creation wizard
│               ├── StepIndicator.tsx     # Progress bar
│               ├── BasicInfoStep.tsx     # Name + description
│               ├── ModelSelectionStep.tsx # Live model picker from Letta
│               ├── ToolAccessStep.tsx    # Live tool picker from Letta
│               ├── SystemPromptStep.tsx  # Initial system prompt
│               └── ReviewStep.tsx        # Summary + create
├── docker-compose.yml
├── Dockerfile
├── dashboard/Dockerfile
└── package.json               # @community-ade/letta-ade v0.2.0

Running (Host Mode)

cd /home/ani/Projects/community-ade/community-ade-wt/mvp-unified

# Prerequisites: Redis container running on port 4420
docker start ade-redis  # or: docker run -d --name ade-redis -p 4420:6379 redis:7-alpine

# Backend
npm run build
PORT=4421 nohup node dist/server.js > /tmp/ade-backend.log 2>&1 &

# Dashboard (dev server)
cd dashboard
REACT_APP_API_URL=http://10.10.20.19:4421 nohup npx react-scripts start > /tmp/ade-dashboard.log 2>&1 &

# Dashboard: http://10.10.20.19:4422/
# API:       http://10.10.20.19:4421/api/agents
# Redis:     localhost:4420

What NOT to Do

  • Do NOT create separate directories per model — models are options within ONE system
  • Do NOT build standalone memory stores — use Letta's memory blocks via the SDK
  • Do NOT use localhost:3000 in frontend code — use relative URLs or REACT_APP_API_URL
  • Do NOT guess SDK method signatures — read the .d.ts files or source code
  • Do NOT hand-roll HTTP calls to Letta when the SDK already wraps the endpoint
  • Do NOT use import for @letta-ai/letta-code-sdk in CJS — must be dynamic import()

Archive Reference

The community-ade-wt/_archive/ directory contains prior implementations that validated the architecture:

Directory What Useful For
impl-kimi, impl-deepseek, impl-glm, impl-minimax Per-model implementations (identical code) Proved model-agnostic architecture
memory-curator-kimi 4-tier memory hierarchy design Future memory curation phase
approval-impl, approval-system Distributed locking + approval state machine Future governance layer
future-proofing Feature flags, migration automation, extensibility Long-term scaling patterns
sdk-alignment SDK compatibility tracking Reference for version upgrades

Vision

Letta is the only open-source platform combining stateful agents + hierarchical memory + git-native persistence + subagent orchestration. Commercial tools (Warp, Intent) validate the market but leave gaps:

  • Warp: terminal-native but no persistent memory, no subagent orchestration
  • Intent: spec-driven but SaaS-only, no self-hosted option

Community ADE fills these gaps with a self-hosted, SDK-powered orchestration platform. The dashboard is the control surface. The task queue is the execution engine. The SDKs are the only interface to Letta.

Reference in New Issue View Git Blame Copy Permalink