Skip to content

Commit 749f825

Browse files
M3gA-MindM3gA-Mind
committed
chore: update TinyHumans AI SDK to version 0.1.6 and add documentation for Rust SDK E2E tests
- Updated the TinyHumans AI SDK version in Cargo.lock and Cargo.toml. - Added new documentation files for the Rust SDK E2E test run and TinyHumans AI SDK reference. - Updated the skills subproject commit reference. - Refactored memory client methods for improved functionality and consistency.
1 parent 861acc5 commit 749f825

8 files changed

Lines changed: 1021 additions & 10 deletions

File tree

‎docs/sdk-rust-e2e-test-run.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
# Rust SDK E2E Test Run — `example_e2e.rs`
2+
3+
**Run date:** 2026-03-27
4+
**Source:** `neocortex/packages/sdk-rust/tests/example_e2e.rs`
5+
**API base URL:** `https://staging-api.alphahuman.xyz`
6+
**Namespace:** `sdk-rust-e2e`
7+
**Document ID:** `sdk-rust-e2e-doc-single-1774605977640`
8+
9+
---
10+
11+
## What the test does
12+
13+
The file is a standalone end-to-end integration program (not a `#[test]`-annotated unit test). It exercises the `tinyhumansai` Rust SDK against the staging API in six sequential steps:
14+
15+
| Step | Operation | SDK method |
16+
|------|-----------|------------|
17+
| 1 | Insert a memory document | `insert_memory` |
18+
| 2 | Poll ingestion job until complete | `get_ingestion_job` + `wait_for_ingestion_job` |
19+
| 3 | List documents filtered by namespace | `list_documents` |
20+
| 4 | Fetch the specific document | `get_document` |
21+
| 5 | Semantic query over the namespace | `query_memory` |
22+
| 6 | Recall all memory context | `recall_memory` |
23+
24+
The document inserted contains sprint velocity data for four teams (Atlas, Beacon, Comet, Delta).
25+
26+
---
27+
28+
## How to run
29+
30+
The file has its own `async fn main()` (annotated with `#[tokio::main]`), so Cargo's default test harness intercepts it and reports 0 tests. To run it as intended, add `harness = false` to `Cargo.toml` temporarily:
31+
32+
```toml
33+
[[test]]
34+
name = "example_e2e"
35+
harness = false
36+
```
37+
38+
Then:
39+
40+
```bash
41+
cd neocortex/packages/sdk-rust
42+
cargo test --test example_e2e
43+
```
44+
45+
> **Note:** `TINYHUMANS_TOKEN` in the file is intentionally left blank. Populate it with a valid API token before running.
46+
47+
---
48+
49+
## Step-by-step output
50+
51+
### Step 1 — `insertMemory`
52+
53+
**Endpoint:** `POST /memory/insert`
54+
55+
**Request body** (serialized from `InsertMemoryBody`; `priority`, `createdAt`, `updatedAt` omitted because they are `None` and marked `skip_serializing_if`):
56+
57+
```json
58+
{
59+
"title": "Sprint Dataset - Team Velocity",
60+
"content": "Sprint snapshot: Team Atlas completed 42 story points with 3 blockers, Team Beacon completed 35 story points with 1 blocker, Team Comet completed 48 story points with 5 blockers, and Team Delta completed 39 story points with 2 blockers. The highest velocity team is Team Comet and the fewest blockers team is Team Beacon.",
61+
"namespace": "sdk-rust-e2e",
62+
"sourceType": "doc",
63+
"metadata": { "source": "example_e2e.rs" },
64+
"documentId": "sdk-rust-e2e-doc-single-1774605977640"
65+
}
66+
```
67+
68+
**Result:** success
69+
**Job ID:** `a2a1396c-bcf5-4552-afc0-6c822bafd7c6`
70+
**Initial job state:** `pending`
71+
72+
```
73+
InsertMemoryResponse {
74+
success: true,
75+
data: InsertMemoryData {
76+
job_id: Some("a2a1396c-bcf5-4552-afc0-6c822bafd7c6"),
77+
state: Some("pending"),
78+
...
79+
},
80+
}
81+
```
82+
83+
---
84+
85+
### Step 2 — `getIngestionJob` + `waitForIngestionJob`
86+
87+
**Endpoint:** `GET /memory/ingestion/jobs/{jobId}` (no request body)
88+
89+
**URL:** `GET /memory/ingestion/jobs/a2a1396c-bcf5-4552-afc0-6c822bafd7c6`
90+
91+
`wait_for_ingestion_job` then polls the same endpoint repeatedly (every 1 s, up to 30 s) until the state is not in `{pending, queued, processing, in_progress, started}`.
92+
93+
Initial poll returned state `processing`, so the SDK waited. Job completed successfully.
94+
95+
**Final state:** `completed`
96+
**Completed at:** `2026-03-27T10:06:24.974Z`
97+
**Ingestion latency:** `2.6173 s`
98+
99+
Key stats from the completed job response:
100+
101+
| Metric | Value |
102+
|--------|-------|
103+
| Chunks new | 1 |
104+
| Chunks total | 1 |
105+
| Chunks deduplicated | 0 |
106+
| Entities extracted | 15 |
107+
| Relations extracted | 25 |
108+
| Sections | 1 |
109+
| Source type | `doc` |
110+
| Embedding tokens used | 244 |
111+
| Cost (USD) | $0.00000488 |
112+
113+
Timing breakdown (selected):
114+
115+
| Stage | Seconds |
116+
|-------|---------|
117+
| Chunking | 0.000826 |
118+
| Chunk embedding | 0.2688 |
119+
| Chunk storage | 0.2049 |
120+
| Entity extraction | 0.8131 |
121+
| Entity embedding | 0.0476 |
122+
| Graph structure | 0.2427 |
123+
| Relationship storage | 0.3800 |
124+
| Storage total | 1.2504 |
125+
126+
---
127+
128+
### Step 3 — `listDocuments`
129+
130+
**Endpoint:** `GET /memory/documents?namespace=sdk-rust-e2e&limit=10&offset=0` (no request body)
131+
132+
This run uses the updated `list_documents(ListDocumentsParams { namespace, limit, offset })` signature (new in the local SDK). Passing `namespace` now filters results correctly — previous runs returned an empty array because no namespace filter was applied.
133+
134+
**4 documents returned** (all previous E2E runs in this namespace):
135+
136+
| Document ID | Created at |
137+
|-------------|------------|
138+
| `sdk-rust-e2e-doc-single-1774598994566` | 2026-03-27T08:09:56 |
139+
| `sdk-rust-e2e-doc-single-1774600415507` | 2026-03-27T08:33:37 |
140+
| `sdk-rust-e2e-doc-single-1774604625874` | 2026-03-27T09:43:47 |
141+
| `sdk-rust-e2e-doc-single-1774605977640` | 2026-03-27T10:06:20 ← this run |
142+
143+
All share `namespace: "sdk-rust-e2e"`, `title: "Sprint Dataset - Team Velocity"`, `chunk_count: 1`.
144+
145+
---
146+
147+
### Step 4 — `getDocument`
148+
149+
**Endpoint:** `GET /memory/documents/{documentId}?namespace={namespace}` (no request body)
150+
151+
**URL:** `GET /memory/documents/sdk-rust-e2e-doc-single-1774605977640?namespace=sdk-rust-e2e`
152+
153+
```json
154+
{
155+
"success": true,
156+
"data": {
157+
"document_id": "sdk-rust-e2e-doc-single-1774605977640",
158+
"namespace": "sdk-rust-e2e",
159+
"title": "Sprint Dataset - Team Velocity",
160+
"chunk_count": 1,
161+
"chunk_ids": [-1427053832764092200],
162+
"created_at": "2026-03-27T10:06:20.655791+00:00",
163+
"updated_at": "2026-03-27T10:06:21.964953+00:00",
164+
"user_id": "69b12a6fd11460481185a040"
165+
}
166+
}
167+
```
168+
169+
---
170+
171+
### Step 5 — `queryMemory`
172+
173+
**Endpoint:** `POST /memory/query`
174+
175+
**Request body** (serialized from `QueryMemoryParams` with `#[serde(rename_all = "camelCase")]`; `documentIds` and `llmQuery` omitted because they are `None`):
176+
177+
```json
178+
{
179+
"query": "Which team has the highest velocity and which team has the fewest blockers?",
180+
"includeReferences": true,
181+
"namespace": "sdk-rust-e2e",
182+
"maxChunks": 5.0
183+
}
184+
```
185+
186+
**Result:** 1 chunk returned with score `19.117`
187+
188+
The relevant chunk was retrieved correctly. The LLM context message assembled by the API:
189+
190+
```
191+
## Sources
192+
193+
[1] Section: Sprint Dataset - Team Velocity
194+
[1] Sprint snapshot: Team Atlas completed 42 story points with 3 blockers,
195+
Team Beacon completed 35 story points with 1 blocker, Team Comet
196+
completed 48 story points with 5 blockers, and Team Delta completed 39
197+
story points with 2 blockers. The highest velocity team is Team Comet
198+
and the fewest blockers team is Team Beacon.
199+
```
200+
201+
Top entity mentions extracted from the chunk (by normalized importance):
202+
203+
| Entity | Normalized importance | Count |
204+
|--------|-----------------------|-------|
205+
| THE FEWEST BLOCKERS TEAM | 1.000 | 6 |
206+
| 42 STORY POINTS | 0.842 | 14 |
207+
| TEAM BEACON | 0.486 | 2 |
208+
| TEAM COMET | 0.476 | 2 |
209+
| THE HIGHEST VELOCITY TEAM | 0.440 | 4 |
210+
211+
**Usage:**
212+
- Embedding tokens: 20
213+
- Cost: $0.0000004
214+
- Cached: false
215+
216+
---
217+
218+
### Step 6 — `recallMemoryContext`
219+
220+
**Endpoint:** `POST /memory/recall`
221+
222+
**Request body** (serialized from `RecallMemoryParams` with `#[serde(rename_all = "camelCase")]`):
223+
224+
```json
225+
{
226+
"namespace": "sdk-rust-e2e",
227+
"maxChunks": 5.0
228+
}
229+
```
230+
231+
Recall (no query — returns all recent/relevant context) returned the same chunk with a higher score of `31.357` (recall scoring differs from query scoring).
232+
233+
**Counts:** 1 chunk, 0 entities, 0 relations
234+
**Latency:** 2.8183 s
235+
**Usage:** 0 tokens, $0 cost (recall is embedding-free)
236+
**Cached:** false
237+
238+
The LLM context message was identical to step 5.
239+
240+
---
241+
242+
## Changes since previous run
243+
244+
| Area | Previous run | This run |
245+
|------|-------------|----------|
246+
| `step3_list_documents` signature | `list_documents()` — no args | `list_documents(ListDocumentsParams { namespace, limit, offset })` |
247+
| Step 3 result | Empty `documents: []` (no filter) | 4 documents returned (namespace filter working) |
248+
| Job ID | `4b3cc8e2-...` | `a2a1396c-...` |
249+
| Document ID | `sdk-rust-e2e-doc-single-1774600415507` | `sdk-rust-e2e-doc-single-1774605977640` |
250+
| Ingestion latency | 1.7791 s | 2.6173 s |
251+
| Entity extraction time | 0.0117 s | 0.8131 s |
252+
253+
---
254+
255+
## Overall result
256+
257+
```
258+
E2E Rust SDK example completed.
259+
```
260+
261+
All 6 steps passed. The SDK correctly:
262+
- Inserted a document and received a job ID
263+
- Polled and waited for the ingestion job to reach `completed`
264+
- Listed documents filtered by namespace (returning all 4 prior E2E inserts)
265+
- Retrieved the document metadata by ID
266+
- Performed a semantic query and received the correct chunk with entity importance scores
267+
- Recalled memory context with latency and count metadata

0 commit comments

Comments
 (0)