this repo has no description
docs: update architecture for LiteLLM proxy chain
README.md:
- Add detailed architecture diagram with all proxy layers
- Document LiteLLM and auth-adapter services
- Add LiteLLM troubleshooting section
- Update project structure with new files
CLAUDE.md:
- Fix Letta handle to openai/claude-opus-4-5-20251101
- Document agent creation workaround with code example
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+68
-14
+29
CLAUDE.md
+29
CLAUDE.md
···
108
108
109
109
---
110
110
111
+
## Claude Model
112
+
113
+
**Always use Claude Opus 4.5** for this project:
114
+
- Model ID: `claude-opus-4-5-20251101`
115
+
- Letta handle: `openai/claude-opus-4-5-20251101` (via LiteLLM proxy)
116
+
117
+
Do NOT use other Claude models (sonnet, haiku, etc.) unless explicitly requested.
118
+
119
+
### Letta Agent Creation Workaround
120
+
121
+
Due to a Letta bug with BYOK model handles, agents must be created in two steps:
122
+
123
+
1. Create agent with `letta/letta-free` model
124
+
2. Update agent's `llm_config` to use Claude:
125
+
```typescript
126
+
await client.agents.update(agentId, {
127
+
llm_config: {
128
+
handle: 'openai/claude-opus-4-5-20251101',
129
+
model: 'claude-opus-4-5-20251101',
130
+
model_endpoint_type: 'openai',
131
+
model_endpoint: 'http://litellm:4000',
132
+
context_window: 200000,
133
+
temperature: 0.7,
134
+
},
135
+
});
136
+
```
137
+
138
+
---
139
+
111
140
## Code Quality (MANDATORY)
112
141
113
142
**CRITICAL**: All code changes MUST pass these checks before completion:
+39
-14
README.md
+39
-14
README.md
···
5
5
## Architecture
6
6
7
7
```
8
-
Telegram → Bun Adapter → Letta Agent → Anthropic (via proxy)
8
+
Telegram Bot (Bun)
9
+
↓
10
+
Letta (port 8283) - AI agent framework
11
+
↓ OpenAI-compatible API
12
+
LiteLLM (port 4000) - API translation layer
13
+
↓ Anthropic API format
14
+
auth-adapter (port 4002) - Header translation
15
+
↓
16
+
anthropic-proxy (port 4001) - OAuth session management
17
+
↓
18
+
Anthropic API (Claude Opus 4.5)
9
19
```
10
20
11
-
- **Bun**: Runtime and HTTP server
21
+
- **Bun**: Runtime and HTTP server for Telegram bot
12
22
- **Letta**: AI agent framework with persistent memory
23
+
- **LiteLLM**: Translates OpenAI-compatible requests to Anthropic format
24
+
- **auth-adapter**: Middleware for header translation (Bearer → x-api-key)
13
25
- **anthropic-proxy**: OAuth proxy for Anthropic API access
14
26
- **SQLite**: Local storage for items, wins, and context
15
27
···
46
58
```
47
59
48
60
This starts:
49
-
- `anthropic-proxy` on port 4001
50
-
- `letta` on port 8283
61
+
- `anthropic-proxy` on port 4001 - OAuth proxy for Anthropic API
62
+
- `auth-adapter` on port 4002 - Header translation middleware
63
+
- `litellm` on port 4000 - OpenAI-compatible API proxy
64
+
- `letta` on port 8283 - AI agent framework
51
65
52
66
The dev override (`docker-compose.dev.yml`) excludes the app service so you can run it locally.
53
67
···
65
79
ANTHROPIC_PROXY_SESSION_ID=your_session_id_here
66
80
```
67
81
68
-
### 5. Configure Letta provider
82
+
### 5. Verify Letta setup
69
83
70
-
Add the anthropic-proxy as a custom LLM provider in Letta:
84
+
Verify that Letta can access Claude models via LiteLLM:
71
85
72
86
```bash
73
87
bun run setup:letta
74
88
```
75
89
76
-
This registers the proxy with Letta so it can use Claude models.
90
+
This checks that the proxy chain is working and Claude models are available.
77
91
78
92
### 6. Run the app
79
93
···
182
196
183
197
```
184
198
├── src/
185
-
│ ├── config.ts # Environment configuration
186
-
│ ├── health.ts # Health check endpoints
187
-
│ ├── letta.ts # Letta client bootstrap
188
-
│ ├── index.ts # Main server (M1)
189
-
│ ├── bot.ts # Telegram bot (M1)
190
-
│ ├── db/ # Database schema (M2)
191
-
│ └── tools/ # Agent tools (M2+)
199
+
│ ├── config.ts # Environment configuration
200
+
│ ├── health.ts # Health check endpoints
201
+
│ ├── letta.ts # Letta client bootstrap
202
+
│ ├── index.ts # Main server (M1)
203
+
│ ├── bot.ts # Telegram bot (M1)
204
+
│ ├── auth-adapter.ts # Header translation middleware
205
+
│ ├── db/ # Database schema (M2)
206
+
│ └── tools/ # Agent tools (M2+)
207
+
├── scripts/
208
+
│ └── setup-letta-provider.ts # Setup verification
209
+
├── litellm-config.yaml # LiteLLM model configuration
192
210
├── docker-compose.yml
193
211
├── docker-compose.dev.yml
194
212
├── Dockerfile.anthropic-proxy
···
228
246
1. Verify the proxy is running: `curl http://localhost:4001/health`
229
247
2. Check if OAuth is complete (session ID should be set)
230
248
3. Check logs: `docker compose logs anthropic-proxy`
249
+
250
+
### LiteLLM not routing to Claude
251
+
252
+
1. Verify LiteLLM is running: `curl http://localhost:4000/health`
253
+
2. Check available models: `curl http://localhost:4000/models`
254
+
3. Test direct call: `curl -X POST http://localhost:4000/chat/completions -H "Content-Type: application/json" -d '{"model":"claude-opus-4-5-20251101","messages":[{"role":"user","content":"Hi"}],"max_tokens":10}'`
255
+
4. Check logs: `docker compose logs litellm`
231
256
232
257
### Can't connect to Telegram
233
258