Skip to content

Commit 0d76f85

Browse files
enitratenitrat
committed
minor fixes
1 parent 398089c commit 0d76f85

4 files changed

Lines changed: 546 additions & 23 deletions

File tree

‎docs/API.md‎

Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,293 @@
1+
# Cairo Coder API
2+
3+
This document describes the HTTP API served by the Cairo Coder backend. The API is compatible with OpenAI's Chat Completions interface, with Cairo-specific extensions.
4+
5+
## Base URL
6+
7+
The service listens on `http://<host>:3001` by default.
8+
9+
## Authentication
10+
11+
No authentication is enforced by the server. Add your own gateway (API key, OAuth, etc.) if exposing publicly.
12+
13+
## Common Conventions
14+
15+
- **Content type**: `application/json` for non-streaming, `text/event-stream` for streaming
16+
- **Charset**: UTF-8
17+
- **Request body**: JSON-encoded payloads
18+
- **Date & time**: Epoch seconds (`created` fields)
19+
20+
### Headers
21+
22+
| Header | Required | Description |
23+
| --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
24+
| `Content-Type` | Yes | `application/json` for JSON POSTs |
25+
| `Accept` | No | `application/json` or `text/event-stream` |
26+
| `x-mcp-mode` or `mcp` | No | When present, returns raw documentation snippets instead of synthesized answers |
27+
| `x-conversation-id` | No | Links multiple requests to the same conversation for analytics |
28+
| `x-user-id` | No | Anonymous user identifier (hashed before storage) |
29+
| `x-api-key` | No | When present, hash is used as user identifier (takes precedence over `x-user-id`). If you are using a custom authentication system, you can forward this header to identify users. |
30+
31+
## Endpoints
32+
33+
### Health Check
34+
35+
```text
36+
GET /
37+
```
38+
39+
**Response** `200 OK`
40+
41+
```json
42+
{ "status": "ok" }
43+
```
44+
45+
### Agent Directory
46+
47+
```text
48+
GET /v1/agents
49+
```
50+
51+
Lists all registered agents.
52+
53+
**Response** `200 OK`
54+
55+
```json
56+
[
57+
{
58+
"id": "cairo-coder",
59+
"name": "Cairo Coder",
60+
"description": "General Cairo programming assistant",
61+
"sources": ["cairo_book", "starknet_docs", "starknet_foundry", ...]
62+
},
63+
{
64+
"id": "starknet-agent",
65+
"name": "Starknet Agent",
66+
"description": "Assistant for the Starknet ecosystem (contracts, tools, docs).",
67+
"sources": ["cairo_book", "starknet_docs", ...]
68+
}
69+
]
70+
```
71+
72+
#### Available Documentation Sources
73+
74+
| Source ID | Description |
75+
| ------------------- | ------------------------------------------ |
76+
| `cairo_book` | Cairo book reference |
77+
| `starknet_docs` | Starknet official documentation |
78+
| `starknet_foundry` | Starknet Foundry resources |
79+
| `cairo_by_example` | Cairo by Example guides |
80+
| `openzeppelin_docs` | OpenZeppelin Cairo contracts documentation |
81+
| `corelib_docs` | Cairo core library docs |
82+
| `scarb_docs` | Scarb package manager documentation |
83+
| `starknet_js` | StarknetJS guides and SDK documentation |
84+
| `starknet_blog` | Starknet blog posts and announcements |
85+
| `dojo_docs` | Dojo game engine documentation |
86+
87+
### Chat Completions
88+
89+
Three route variants exist (all share the same behavior):
90+
91+
- `POST /v1/agents/{agent_id}/chat/completions` - Target a specific agent
92+
- `POST /v1/chat/completions` - Default agent (`cairo-coder`)
93+
- `POST /chat/completions` - Legacy alias
94+
95+
#### Request Schema
96+
97+
```json
98+
{
99+
"model": "cairo-coder",
100+
"messages": [
101+
{ "role": "system", "content": "Optional instructions" },
102+
{ "role": "user", "content": "Your Cairo/StarkNet question" }
103+
],
104+
"stream": false,
105+
"temperature": 0.2,
106+
"max_tokens": 1024
107+
}
108+
```
109+
110+
**Notes:**
111+
112+
- `messages` must contain at least one entry with the final message having `role: "user"`
113+
- Roles accepted: `system`, `user`, `assistant`
114+
- Set `stream: true` to receive Server-Sent Events (SSE) chunks
115+
- History is implied by providing earlier messages; backend keeps the last 10 history items
116+
117+
#### Non-Streaming Response
118+
119+
```bash
120+
curl -X POST http://localhost:3001/v1/agents/cairo-coder/chat/completions \
121+
-H 'Content-Type: application/json' \
122+
-d '{
123+
"messages": [
124+
{"role": "user", "content": "How do I define a storage variable?"}
125+
]
126+
}'
127+
```
128+
129+
**Response** `200 OK`
130+
131+
```json
132+
{
133+
"id": "fa43012d-2d0c-4ad2-82c9-2e1ec7aaa43d",
134+
"object": "chat.completion",
135+
"created": 1718123456,
136+
"model": "cairo-coder",
137+
"choices": [
138+
{
139+
"index": 0,
140+
"message": {
141+
"role": "assistant",
142+
"content": "<answer text>"
143+
},
144+
"finish_reason": "stop"
145+
}
146+
],
147+
"usage": {
148+
"prompt_tokens": 123,
149+
"completion_tokens": 512,
150+
"total_tokens": 635
151+
}
152+
}
153+
```
154+
155+
#### Streaming Response
156+
157+
Set `"stream": true` to receive Server-Sent Events (SSE).
158+
159+
```bash
160+
curl -N -X POST http://localhost:3001/v1/chat/completions \
161+
-H 'Content-Type: application/json' \
162+
-d '{
163+
"stream": true,
164+
"messages": [{"role": "user", "content": "Explain felt252 arithmetic."}]
165+
}'
166+
```
167+
168+
**Stream format:**
169+
170+
```text
171+
data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"}}]}
172+
173+
data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Felt252 is..."}}]}
174+
175+
data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop"}]}
176+
177+
data: [DONE]
178+
```
179+
180+
#### Custom Stream Events
181+
182+
In addition to OpenAI-compatible chunks, Cairo Coder emits custom events:
183+
184+
| Event Type | Description |
185+
| ---------------- | ------------------------------------------------------------------------- |
186+
| `processing` | Progress updates (e.g., "Processing query...", "Retrieving documents...") |
187+
| `sources` | Sources used to answer the query (emitted after retrieval) |
188+
| `reasoning` | Optional model reasoning stream (token-level) |
189+
| `final_response` | Full, final answer text |
190+
191+
**Example sources event:**
192+
193+
```json
194+
{
195+
"type": "sources",
196+
"data": [
197+
{
198+
"metadata": {
199+
"title": "Introduction to Cairo",
200+
"url": "https://book.cairo-lang.org/..."
201+
}
202+
}
203+
]
204+
}
205+
```
206+
207+
### Suggestions
208+
209+
```text
210+
POST /v1/suggestions
211+
```
212+
213+
Generate follow-up conversation suggestions based on chat history.
214+
215+
**Request:**
216+
217+
```json
218+
{
219+
"chat_history": [
220+
{ "role": "user", "content": "How do I create a Cairo contract?" },
221+
{ "role": "assistant", "content": "Here's how..." }
222+
]
223+
}
224+
```
225+
226+
**Response** `200 OK`
227+
228+
```json
229+
{
230+
"suggestions": [
231+
"How do I deploy this contract to testnet?",
232+
"What are the best practices for contract security?",
233+
"Can you explain how storage works in Cairo contracts?",
234+
"How do I write tests for this contract?"
235+
]
236+
}
237+
```
238+
239+
### Query Insights
240+
241+
```text
242+
GET /v1/insights/queries
243+
```
244+
245+
Fetch paginated user queries for analytics.
246+
247+
**Query Parameters:**
248+
249+
- `start_date` - ISO 8601, inclusive lower bound
250+
- `end_date` - ISO 8601, inclusive upper bound
251+
- `agent_id` - Filter by agent
252+
- `query_text` - Filter by text (case-insensitive)
253+
- `limit` - Maximum rows (default: 100)
254+
- `offset` - Pagination offset (default: 0)
255+
- `conversation_id` - Filter by conversation
256+
- `user_id` - Filter by hashed user id
257+
258+
## MCP Mode
259+
260+
Setting `mcp` or `x-mcp-mode` headers triggers Model Context Protocol mode:
261+
262+
- Returns curated documentation blocks instead of synthesized answers
263+
- Does not consume generation tokens
264+
- Useful for integration with other tools needing Cairo documentation
265+
266+
```bash
267+
curl -X POST http://localhost:3001/v1/chat/completions \
268+
-H 'Content-Type: application/json' \
269+
-H 'x-mcp-mode: true' \
270+
-d '{"messages": [{"role": "user", "content": "Selectors"}]}'
271+
```
272+
273+
## Error Handling
274+
275+
Errors return HTTP status codes with an OpenAI-compatible JSON envelope:
276+
277+
```json
278+
{
279+
"error": {
280+
"message": "Agent 'foo' not found",
281+
"type": "invalid_request_error",
282+
"code": "agent_not_found",
283+
"param": "agent_id"
284+
}
285+
}
286+
```
287+
288+
| Status | Description |
289+
| --------------------------- | ---------------------- |
290+
| `400 Bad Request` | Validation failures |
291+
| `404 Not Found` | Unknown agent id |
292+
| `422 Unprocessable Entity` | Invalid message format |
293+
| `500 Internal Server Error` | Backend issues |

0 commit comments

Comments
 (0)