10xgraph-api 0.7.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (203) hide show
  1. 10xgraph_api-0.7.0.dist-info/METADATA +618 -0
  2. 10xgraph_api-0.7.0.dist-info/RECORD +203 -0
  3. 10xgraph_api-0.7.0.dist-info/WHEEL +5 -0
  4. 10xgraph_api-0.7.0.dist-info/entry_points.txt +3 -0
  5. 10xgraph_api-0.7.0.dist-info/licenses/LICENSE +21 -0
  6. 10xgraph_api-0.7.0.dist-info/top_level.txt +2 -0
  7. agentflow_cli/__init__.py +69 -0
  8. tenxgraph_api/__init__.py +23 -0
  9. tenxgraph_api/cli/__init__.py +6 -0
  10. tenxgraph_api/cli/capabilities.py +127 -0
  11. tenxgraph_api/cli/commands/__init__.py +49 -0
  12. tenxgraph_api/cli/commands/api.py +262 -0
  13. tenxgraph_api/cli/commands/audit.py +213 -0
  14. tenxgraph_api/cli/commands/build.py +305 -0
  15. tenxgraph_api/cli/commands/config.py +71 -0
  16. tenxgraph_api/cli/commands/demo.py +93 -0
  17. tenxgraph_api/cli/commands/eval.py +909 -0
  18. tenxgraph_api/cli/commands/init.py +531 -0
  19. tenxgraph_api/cli/commands/skills.py +532 -0
  20. tenxgraph_api/cli/commands/test.py +113 -0
  21. tenxgraph_api/cli/commands/version.py +47 -0
  22. tenxgraph_api/cli/config_editor/__init__.py +15 -0
  23. tenxgraph_api/cli/config_editor/schema.py +566 -0
  24. tenxgraph_api/cli/config_editor/server.py +240 -0
  25. tenxgraph_api/cli/config_editor/static/app.css +2 -0
  26. tenxgraph_api/cli/config_editor/static/app.js +3 -0
  27. tenxgraph_api/cli/config_editor/static/favicon.svg +11 -0
  28. tenxgraph_api/cli/config_editor/static/index.html +20 -0
  29. tenxgraph_api/cli/config_editor/store.py +120 -0
  30. tenxgraph_api/cli/config_editor/validation.py +377 -0
  31. tenxgraph_api/cli/constants.py +112 -0
  32. tenxgraph_api/cli/context.py +46 -0
  33. tenxgraph_api/cli/core/__init__.py +0 -0
  34. tenxgraph_api/cli/core/animations.py +550 -0
  35. tenxgraph_api/cli/core/config.py +279 -0
  36. tenxgraph_api/cli/core/output.py +625 -0
  37. tenxgraph_api/cli/core/prompts.py +220 -0
  38. tenxgraph_api/cli/core/screen.py +287 -0
  39. tenxgraph_api/cli/core/steps.py +621 -0
  40. tenxgraph_api/cli/core/theme.py +242 -0
  41. tenxgraph_api/cli/core/validation.py +251 -0
  42. tenxgraph_api/cli/exceptions.py +129 -0
  43. tenxgraph_api/cli/logger.py +84 -0
  44. tenxgraph_api/cli/main.py +936 -0
  45. tenxgraph_api/cli/templates/__init__.py +0 -0
  46. tenxgraph_api/cli/templates/defaults.py +844 -0
  47. tenxgraph_api/cli/templates/dev/.env.example +1 -0
  48. tenxgraph_api/cli/templates/dev/10xgraph.json +16 -0
  49. tenxgraph_api/cli/templates/dev/graph/__init__.py +0 -0
  50. tenxgraph_api/cli/templates/dev/graph/agent.py +63 -0
  51. tenxgraph_api/cli/templates/prod/.env.example +75 -0
  52. tenxgraph_api/cli/templates/prod/.pre-commit-config.yaml +50 -0
  53. tenxgraph_api/cli/templates/prod/.python-version +1 -0
  54. tenxgraph_api/cli/templates/prod/10xgraph.json +42 -0
  55. tenxgraph_api/cli/templates/prod/auth/__init__.py +0 -0
  56. tenxgraph_api/cli/templates/prod/auth/agent_auth.py +46 -0
  57. tenxgraph_api/cli/templates/prod/evals/__init__.py +0 -0
  58. tenxgraph_api/cli/templates/prod/evals/user_simulator_eval.py +76 -0
  59. tenxgraph_api/cli/templates/prod/evals/weather_agents_eval.py +53 -0
  60. tenxgraph_api/cli/templates/prod/graph/__init__.py +0 -0
  61. tenxgraph_api/cli/templates/prod/graph/agent.py +50 -0
  62. tenxgraph_api/cli/templates/prod/graph/state.py +5 -0
  63. tenxgraph_api/cli/templates/prod/graph/thread_name_generator.py +7 -0
  64. tenxgraph_api/cli/templates/prod/graph/tools/__init__.py +0 -0
  65. tenxgraph_api/cli/templates/prod/graph/tools/weather_tool.py +43 -0
  66. tenxgraph_api/cli/templates/prod/graph/validators/__init__.py +0 -0
  67. tenxgraph_api/cli/templates/prod/graph/validators/lifecyle.py +107 -0
  68. tenxgraph_api/cli/templates/prod/graph/validators/manager.py +9 -0
  69. tenxgraph_api/cli/templates/prod/graph/validators/validators.py +21 -0
  70. tenxgraph_api/cli/templates/prod/pyproject.toml +79 -0
  71. tenxgraph_api/cli/templates/prod/tests/__init__.py +0 -0
  72. tenxgraph_api/cli/templates/prod/tests/conftest.py +6 -0
  73. tenxgraph_api/cli/templates/prod/tests/test_agent_eval.py +78 -0
  74. tenxgraph_api/cli/templates/prod/tests/test_catalog_tools.py +47 -0
  75. tenxgraph_api/cli/templates/prod/tests/test_graph_nodes.py +57 -0
  76. tenxgraph_api/cli/templates/skills/10xgraph/SKILL.md +92 -0
  77. tenxgraph_api/cli/templates/skills/10xgraph/references/agents-and-tools.md +389 -0
  78. tenxgraph_api/cli/templates/skills/10xgraph/references/api-client.md +61 -0
  79. tenxgraph_api/cli/templates/skills/10xgraph/references/api-configuration.md +75 -0
  80. tenxgraph_api/cli/templates/skills/10xgraph/references/api-settings-and-middleware.md +89 -0
  81. tenxgraph_api/cli/templates/skills/10xgraph/references/architecture.md +91 -0
  82. tenxgraph_api/cli/templates/skills/10xgraph/references/auth-and-authorization.md +149 -0
  83. tenxgraph_api/cli/templates/skills/10xgraph/references/callbacks-and-command.md +283 -0
  84. tenxgraph_api/cli/templates/skills/10xgraph/references/checkpointing-and-threads.md +63 -0
  85. tenxgraph_api/cli/templates/skills/10xgraph/references/cli-commands.md +73 -0
  86. tenxgraph_api/cli/templates/skills/10xgraph/references/client-auth-and-errors.md +94 -0
  87. tenxgraph_api/cli/templates/skills/10xgraph/references/client-messages-invoke-stream.md +115 -0
  88. tenxgraph_api/cli/templates/skills/10xgraph/references/client-threads-memory-files.md +80 -0
  89. tenxgraph_api/cli/templates/skills/10xgraph/references/context-id-background.md +80 -0
  90. tenxgraph_api/cli/templates/skills/10xgraph/references/dependency-injection.md +58 -0
  91. tenxgraph_api/cli/templates/skills/10xgraph/references/evaluation.md +500 -0
  92. tenxgraph_api/cli/templates/skills/10xgraph/references/id-and-thread-name-generators.md +69 -0
  93. tenxgraph_api/cli/templates/skills/10xgraph/references/media-and-files.md +66 -0
  94. tenxgraph_api/cli/templates/skills/10xgraph/references/memory-and-store.md +70 -0
  95. tenxgraph_api/cli/templates/skills/10xgraph/references/prebuilt-agents-and-tools.md +394 -0
  96. tenxgraph_api/cli/templates/skills/10xgraph/references/production-runtime.md +56 -0
  97. tenxgraph_api/cli/templates/skills/10xgraph/references/providers-and-adapters.md +89 -0
  98. tenxgraph_api/cli/templates/skills/10xgraph/references/publishers-and-runtime-protocols.md +84 -0
  99. tenxgraph_api/cli/templates/skills/10xgraph/references/rate-limiting.md +194 -0
  100. tenxgraph_api/cli/templates/skills/10xgraph/references/realtime.md +172 -0
  101. tenxgraph_api/cli/templates/skills/10xgraph/references/remote-tools.md +55 -0
  102. tenxgraph_api/cli/templates/skills/10xgraph/references/rest-api-and-errors.md +97 -0
  103. tenxgraph_api/cli/templates/skills/10xgraph/references/security-and-validators.md +86 -0
  104. tenxgraph_api/cli/templates/skills/10xgraph/references/state-and-messages.md +68 -0
  105. tenxgraph_api/cli/templates/skills/10xgraph/references/state-graph.md +232 -0
  106. tenxgraph_api/cli/templates/skills/10xgraph/references/stream-emitter.md +144 -0
  107. tenxgraph_api/cli/templates/skills/10xgraph/references/streaming.md +53 -0
  108. tenxgraph_api/cli/templates/skills/10xgraph/references/testing-and-evaluation.md +64 -0
  109. tenxgraph_api/cli/templates/skills/10xgraph/references/unit-testing.md +202 -0
  110. tenxgraph_api/cli/templates/skills/copilot/10xgraph.instructions.md +108 -0
  111. tenxgraph_api/py.typed +0 -0
  112. tenxgraph_api/src/__init__.py +0 -0
  113. tenxgraph_api/src/app/__init__.py +13 -0
  114. tenxgraph_api/src/app/core/__init__.py +15 -0
  115. tenxgraph_api/src/app/core/auth/__init__.py +0 -0
  116. tenxgraph_api/src/app/core/auth/auth_backend.py +38 -0
  117. tenxgraph_api/src/app/core/auth/authorization.py +379 -0
  118. tenxgraph_api/src/app/core/auth/base_auth.py +27 -0
  119. tenxgraph_api/src/app/core/auth/jwt_auth.py +122 -0
  120. tenxgraph_api/src/app/core/auth/ownership_resolver.py +170 -0
  121. tenxgraph_api/src/app/core/auth/permissions.py +354 -0
  122. tenxgraph_api/src/app/core/auth/request_config.py +130 -0
  123. tenxgraph_api/src/app/core/auth/route_guard.py +105 -0
  124. tenxgraph_api/src/app/core/config/__init__.py +0 -0
  125. tenxgraph_api/src/app/core/config/graph_config.py +532 -0
  126. tenxgraph_api/src/app/core/config/media_settings.py +72 -0
  127. tenxgraph_api/src/app/core/config/sentry_config.py +60 -0
  128. tenxgraph_api/src/app/core/config/settings.py +202 -0
  129. tenxgraph_api/src/app/core/config/setup_logs.py +65 -0
  130. tenxgraph_api/src/app/core/config/setup_middleware.py +483 -0
  131. tenxgraph_api/src/app/core/config/worker_middleware.py +99 -0
  132. tenxgraph_api/src/app/core/exceptions/__init__.py +17 -0
  133. tenxgraph_api/src/app/core/exceptions/general_exception.py +58 -0
  134. tenxgraph_api/src/app/core/exceptions/handle_errors.py +363 -0
  135. tenxgraph_api/src/app/core/exceptions/resources_exceptions.py +72 -0
  136. tenxgraph_api/src/app/core/exceptions/user_exception.py +58 -0
  137. tenxgraph_api/src/app/core/middleware/__init__.py +25 -0
  138. tenxgraph_api/src/app/core/middleware/rate_limit/__init__.py +15 -0
  139. tenxgraph_api/src/app/core/middleware/rate_limit/base.py +27 -0
  140. tenxgraph_api/src/app/core/middleware/rate_limit/factory.py +98 -0
  141. tenxgraph_api/src/app/core/middleware/rate_limit/keying.py +133 -0
  142. tenxgraph_api/src/app/core/middleware/rate_limit/memory.py +98 -0
  143. tenxgraph_api/src/app/core/middleware/rate_limit/middleware.py +90 -0
  144. tenxgraph_api/src/app/core/middleware/rate_limit/redis.py +115 -0
  145. tenxgraph_api/src/app/core/middleware/request_limits.py +154 -0
  146. tenxgraph_api/src/app/core/middleware/security_headers.py +239 -0
  147. tenxgraph_api/src/app/core/utils/__init__.py +14 -0
  148. tenxgraph_api/src/app/core/utils/log_sanitizer.py +216 -0
  149. tenxgraph_api/src/app/loader.py +516 -0
  150. tenxgraph_api/src/app/main.py +180 -0
  151. tenxgraph_api/src/app/routers/__init__.py +4 -0
  152. tenxgraph_api/src/app/routers/ag_ui/__init__.py +10 -0
  153. tenxgraph_api/src/app/routers/ag_ui/converter.py +195 -0
  154. tenxgraph_api/src/app/routers/ag_ui/event_mapper.py +353 -0
  155. tenxgraph_api/src/app/routers/ag_ui/router.py +90 -0
  156. tenxgraph_api/src/app/routers/ag_ui/service.py +193 -0
  157. tenxgraph_api/src/app/routers/checkpointer/__init__.py +1 -0
  158. tenxgraph_api/src/app/routers/checkpointer/router.py +482 -0
  159. tenxgraph_api/src/app/routers/checkpointer/schemas/__init__.py +1 -0
  160. tenxgraph_api/src/app/routers/checkpointer/schemas/checkpointer_schemas.py +121 -0
  161. tenxgraph_api/src/app/routers/checkpointer/services/__init__.py +1 -0
  162. tenxgraph_api/src/app/routers/checkpointer/services/checkpointer_service.py +300 -0
  163. tenxgraph_api/src/app/routers/evals/__init__.py +6 -0
  164. tenxgraph_api/src/app/routers/evals/router.py +38 -0
  165. tenxgraph_api/src/app/routers/evals/services/__init__.py +1 -0
  166. tenxgraph_api/src/app/routers/evals/services/eval_report_service.py +354 -0
  167. tenxgraph_api/src/app/routers/graph/__init__.py +6 -0
  168. tenxgraph_api/src/app/routers/graph/realtime_guard.py +161 -0
  169. tenxgraph_api/src/app/routers/graph/router.py +821 -0
  170. tenxgraph_api/src/app/routers/graph/schemas/__init__.py +1 -0
  171. tenxgraph_api/src/app/routers/graph/schemas/graph_schemas.py +386 -0
  172. tenxgraph_api/src/app/routers/graph/services/__init__.py +1 -0
  173. tenxgraph_api/src/app/routers/graph/services/graph_service.py +1219 -0
  174. tenxgraph_api/src/app/routers/graph/services/multimodal_preprocessor.py +164 -0
  175. tenxgraph_api/src/app/routers/media/__init__.py +506 -0
  176. tenxgraph_api/src/app/routers/media/router.py +242 -0
  177. tenxgraph_api/src/app/routers/media/schemas.py +39 -0
  178. tenxgraph_api/src/app/routers/ping/__init__.py +4 -0
  179. tenxgraph_api/src/app/routers/ping/router.py +28 -0
  180. tenxgraph_api/src/app/routers/setup_router.py +60 -0
  181. tenxgraph_api/src/app/routers/store/__init__.py +4 -0
  182. tenxgraph_api/src/app/routers/store/router.py +200 -0
  183. tenxgraph_api/src/app/routers/store/schemas/__init__.py +28 -0
  184. tenxgraph_api/src/app/routers/store/schemas/store_schemas.py +200 -0
  185. tenxgraph_api/src/app/routers/store/services/__init__.py +4 -0
  186. tenxgraph_api/src/app/routers/store/services/store_service.py +203 -0
  187. tenxgraph_api/src/app/tasks/__init__.py +0 -0
  188. tenxgraph_api/src/app/tasks/user_tasks.py +38 -0
  189. tenxgraph_api/src/app/utils/__init__.py +12 -0
  190. tenxgraph_api/src/app/utils/callable_helper.py +26 -0
  191. tenxgraph_api/src/app/utils/media/__init__.py +15 -0
  192. tenxgraph_api/src/app/utils/media/extractor.py +172 -0
  193. tenxgraph_api/src/app/utils/media/pipeline.py +83 -0
  194. tenxgraph_api/src/app/utils/parse_output.py +17 -0
  195. tenxgraph_api/src/app/utils/response_helper.py +129 -0
  196. tenxgraph_api/src/app/utils/schemas/__init__.py +11 -0
  197. tenxgraph_api/src/app/utils/schemas/output_schemas.py +28 -0
  198. tenxgraph_api/src/app/utils/schemas/user_schemas.py +13 -0
  199. tenxgraph_api/src/app/utils/snowflake_id_generator.py +90 -0
  200. tenxgraph_api/src/app/utils/swagger_helper.py +160 -0
  201. tenxgraph_api/src/app/utils/telemetry_store.py +123 -0
  202. tenxgraph_api/src/app/utils/thread_name_generator.py +304 -0
  203. tenxgraph_api/src/app/worker.py +91 -0
@@ -0,0 +1,94 @@
1
+ # Client Auth and Errors
2
+
3
+ Use this when changing `@10xscale/agentflow-client` authentication, request headers, credentials, timeouts, debug behavior, or structured error handling.
4
+
5
+ ## Auth Helpers
6
+
7
+ Public auth types and helpers live in https://github.com/10xHub/agentflow-client/blob/main/src/request.ts.
8
+
9
+ Auth union:
10
+
11
+ - `AgentFlowBearerAuth`: `{ type: "bearer", token }`
12
+ - `AgentFlowBasicAuth`: `{ type: "basic", username, password }`
13
+ - `AgentFlowHeaderAuth`: `{ type: "header", name, value, prefix? }`
14
+ - `AgentFlowAuth`: union of the above
15
+
16
+ Helpers:
17
+
18
+ - `bearerAuth(token)`
19
+ - `basicAuth(username, password)`
20
+ - `headerAuth(name, value, prefix?)`
21
+ - `buildHeaders(context, defaults?)`
22
+ - `getRequestCredentials(context)`
23
+
24
+ ## AgentFlowClient Config
25
+
26
+ `AgentFlowConfig` fields:
27
+
28
+ - `baseUrl`: required API base URL.
29
+ - `authToken`: bearer-token shorthand.
30
+ - `auth`: structured auth helper.
31
+ - `headers`: additional headers merged into every request.
32
+ - `credentials`: browser fetch credentials mode.
33
+ - `timeout`: request timeout in milliseconds; default is 300000.
34
+ - `debug`: enables client debug logging.
35
+
36
+ Auth precedence:
37
+
38
+ 1. Defaults are applied first.
39
+ 2. `headers` are merged next.
40
+ 3. If `auth` is set, it writes auth headers.
41
+ 4. Otherwise, `authToken` writes `Authorization: Bearer ...` only if no authorization header already exists.
42
+
43
+ Use `credentials` for cookie-based auth or same-origin sessions.
44
+
45
+ ## Structured Errors
46
+
47
+ All endpoint helpers call `createErrorFromResponse` for non-OK HTTP responses where implemented.
48
+
49
+ Core error types:
50
+
51
+ - `AgentFlowError`
52
+ - `BadRequestError`
53
+ - `AuthenticationError`
54
+ - `PermissionError`
55
+ - `NotFoundError`
56
+ - `ValidationError`
57
+ - `ServerError`
58
+ - `GraphError`
59
+ - `NodeError`
60
+ - `GraphRecursionError`
61
+ - `StorageError`
62
+ - `TransientStorageError`
63
+ - `MetricsError`
64
+ - `SchemaVersionError`
65
+ - `SerializationError`
66
+
67
+ Error instances expose:
68
+
69
+ - `statusCode`
70
+ - `errorCode`
71
+ - `requestId`
72
+ - `timestamp`
73
+ - `details`
74
+ - `context`
75
+ - `endpoint`
76
+ - `method`
77
+ - `recoverySuggestion`
78
+ - `getUserMessage()`
79
+ - `toJSON()`
80
+
81
+ ## Rules
82
+
83
+ - Prefer structured `auth` helpers for new examples; keep `authToken` as shorthand.
84
+ - Do not overwrite an explicit user-provided `Authorization` header unless `auth` is set.
85
+ - Keep fetch `credentials` forwarding in every endpoint helper.
86
+ - Keep new server error codes mapped in `createErrorFromResponse`.
87
+ - In UI code, show `getUserMessage()` to users and log `toJSON()` for debugging.
88
+
89
+ ## Source Map
90
+
91
+ - Auth/request helpers: https://github.com/10xHub/agentflow-client/blob/main/src/request.ts
92
+ - Error classes: https://github.com/10xHub/agentflow-client/blob/main/src/errors.ts
93
+ - Client facade: https://github.com/10xHub/agentflow-client/blob/main/src/client.ts
94
+ - Docs: https://10xgraph.com/
@@ -0,0 +1,115 @@
1
+ # Client Messages, Invoke, and Stream
2
+
3
+ Use this when changing TypeScript message classes, invoke behavior, streaming behavior, response granularity, partial callbacks, or SSE parsing.
4
+
5
+ ## Message Model
6
+
7
+ Message and content block classes live in https://github.com/10xHub/agentflow-client/blob/main/src/message.ts.
8
+
9
+ Core classes:
10
+
11
+ - `Message`
12
+ - `MediaRef`
13
+ - `AnnotationRef`
14
+ - `TokenUsages`
15
+
16
+ Content blocks:
17
+
18
+ - `TextBlock`
19
+ - `ImageBlock`
20
+ - `AudioBlock`
21
+ - `VideoBlock`
22
+ - `DocumentBlock`
23
+ - `DataBlock`
24
+ - `ToolCallBlock`
25
+ - `RemoteToolCallBlock`
26
+ - `ToolResultBlock`
27
+ - `ReasoningBlock`
28
+ - `AnnotationBlock`
29
+ - `ErrorBlock`
30
+
31
+ Message helpers:
32
+
33
+ - `Message.text_message(content, role?, message_id?)`
34
+ - `Message.tool_message(content, message_id?, meta?)`
35
+ - `message.text()`
36
+ - `message.attach_media(media, as_type)`
37
+ - `Message.withImage(text, imageUrl, altText?)`
38
+ - `Message.withFile(text, fileId, mimeType, filename?)`
39
+ - `Message.multimodal(text, mediaItems)`
40
+
41
+ The client serializes message content as arrays of content blocks. Avoid sending plain strings directly to API endpoints.
42
+
43
+ ## Invoke
44
+
45
+ `AgentFlowClient.invoke(messages, options?)` wraps `/v1/graph/invoke`.
46
+
47
+ Options:
48
+
49
+ - `initial_state`
50
+ - `config`
51
+ - `recursion_limit`
52
+ - `response_granularity`: `"full"`, `"partial"`, or `"low"`
53
+ - `onPartialResult`
54
+
55
+ `InvokeResult` includes:
56
+
57
+ - `messages`
58
+ - `state`
59
+ - `context`
60
+ - `summary`
61
+ - `meta`
62
+ - `all_messages`
63
+ - `iterations`
64
+ - `recursion_limit_reached`
65
+
66
+ `onPartialResult` receives `InvokePartialResult` for every iteration, including `has_tool_calls` and `is_final`. Use it to observe remote tool loops or intermediate server results.
67
+
68
+ ## Remote Tool Loop
69
+
70
+ Invoke automatically loops when server responses include `remote_tool_call` blocks and a `ToolExecutor` is available. The client executes registered handlers, sends tool result messages, and repeats until no remote calls remain or `recursion_limit` is reached.
71
+
72
+ Read `remote-tools.md` for the full remote tool flow.
73
+
74
+ ## Stream
75
+
76
+ `AgentFlowClient.stream(messages, options?)` wraps `/v1/graph/stream` and returns `AsyncGenerator<StreamChunk>`.
77
+
78
+ `StreamEventType` values:
79
+
80
+ - `MESSAGE`
81
+ - `STATE`
82
+ - `ERROR`
83
+ - `UPDATES`
84
+
85
+ `StreamChunk` includes:
86
+
87
+ - `event`
88
+ - `message`
89
+ - `state`
90
+ - `data`
91
+ - `thread_id`
92
+ - `run_id`
93
+ - `metadata`
94
+ - `timestamp`
95
+
96
+ The stream endpoint parses server-sent event payloads and newline-delimited JSON variants. It also participates in the remote tool loop when remote tool calls appear.
97
+
98
+ Use `client.stopGraph(threadId, config?)` to request cancellation for a running stream.
99
+
100
+ ## Rules
101
+
102
+ - Keep TypeScript `Message` block types aligned with Python `Message` and REST schemas.
103
+ - Use `response_granularity: "low"` for UI streaming unless state is needed.
104
+ - Surface `recursion_limit_reached` when remote tool loops do not finish.
105
+ - In React/browser code, consume streams with `for await`.
106
+ - Test both invoke and stream when changing message serialization.
107
+
108
+ ## Source Map
109
+
110
+ - Message classes: https://github.com/10xHub/agentflow-client/blob/main/src/message.ts
111
+ - Client facade: https://github.com/10xHub/agentflow-client/blob/main/src/client.ts
112
+ - Invoke endpoint: https://github.com/10xHub/agentflow-client/blob/main/src/endpoints/invoke.ts
113
+ - Stream endpoint: https://github.com/10xHub/agentflow-client/blob/main/src/endpoints/stream.ts
114
+ - Stop graph endpoint: https://github.com/10xHub/agentflow-client/blob/main/src/endpoints/stopGraph.ts
115
+ - Docs: https://10xgraph.com/
@@ -0,0 +1,80 @@
1
+ # Client Threads, Memory, and Files
2
+
3
+ Use this when changing TypeScript APIs for thread management, checkpoint state/messages, memory store access, or file upload/multimodal helpers.
4
+
5
+ ## Threads
6
+
7
+ Thread methods on `AgentFlowClient`:
8
+
9
+ - `threads(request?)`
10
+ - `threadDetails(threadId)`
11
+ - `deleteThread(threadId, config?)`
12
+ - `threadState(threadId)`
13
+ - `updateThreadState(threadId, config, state)`
14
+ - `clearThreadState(threadId)`
15
+ - `threadMessages(threadId, request?)`
16
+ - `addThreadMessages(threadId, messages, config?, metadata?)`
17
+ - `singleMessage(threadId, messageId)`
18
+ - `deleteMessage(threadId, messageId, config?)`
19
+
20
+ Request patterns:
21
+
22
+ - Thread listing supports search, offset, and limit.
23
+ - Thread message listing supports search, offset, and limit.
24
+ - Thread IDs may be string or number in most facade methods, but some endpoint signatures are narrower; check source before changing types.
25
+
26
+ ## Memory
27
+
28
+ Memory methods:
29
+
30
+ - `storeMemory(request)`
31
+ - `searchMemory(request)`
32
+ - `getMemory(memoryId, options?)`
33
+ - `updateMemory(memoryId, content, options?)`
34
+ - `deleteMemory(memoryId, options?)`
35
+ - `listMemories(options?)`
36
+ - `forgetMemories(options?)`
37
+
38
+ Important enums/types:
39
+
40
+ - `MemoryType`
41
+ - `RetrievalStrategy`
42
+ - `DistanceMetric`
43
+ - memory result/response interfaces in endpoint files
44
+
45
+ The API must have a store configured for memory endpoints to work.
46
+
47
+ ## Files and Multimodal
48
+
49
+ File methods:
50
+
51
+ - `uploadFile(file)`
52
+ - `getFile(fileId)`
53
+ - `getFileInfo(fileId)`
54
+ - `getFileAccessUrl(fileId)`
55
+ - `getMultimodalConfig()`
56
+
57
+ `uploadFile` accepts:
58
+
59
+ - Browser `File`
60
+ - `Blob`
61
+ - `{ data: Blob; filename: string }`
62
+
63
+ Use returned `file_id` in multimodal messages through `MediaRef(kind: "file_id", ...)` and content blocks such as `ImageBlock`, `DocumentBlock`, and `AudioBlock`.
64
+
65
+ ## Rules
66
+
67
+ - Use stable `config.thread_id` for continuity; thread APIs inspect and mutate server-side checkpoints.
68
+ - Keep pagination options backwards-compatible.
69
+ - Keep memory enum values aligned with server store schemas.
70
+ - In browser code, ensure CORS and auth headers are configured before file or memory calls.
71
+ - Preserve MIME types and filenames when uploading files.
72
+ - Use `getFileAccessUrl` for fresh direct/signed URLs instead of caching old URLs indefinitely.
73
+
74
+ ## Source Map
75
+
76
+ - Client facade: https://github.com/10xHub/agentflow-client/blob/main/src/client.ts
77
+ - Thread endpoints: https://github.com/10xHub/agentflow-client/tree/main/src/endpoints
78
+ - Memory endpoints: https://github.com/10xHub/agentflow-client/tree/main/src/endpoints
79
+ - File endpoint: https://github.com/10xHub/agentflow-client/blob/main/src/endpoints/files.ts
80
+ - Docs: https://10xgraph.com/
@@ -0,0 +1,80 @@
1
+ # Context, ID Generation, and Background Tasks
2
+
3
+ Use this when changing context trimming, generated IDs, background work, or graceful shutdown.
4
+
5
+ ## Context Managers
6
+
7
+ `MessageContextManager` controls what conversation history is sent to the model without deleting stored state.
8
+
9
+ Use it for:
10
+
11
+ - Token budget control.
12
+ - Preserving important system/tool messages.
13
+ - Summarizing or trimming old context.
14
+ - Custom context policies per graph.
15
+
16
+ Pass a context manager to `StateGraph(context_manager=...)`. Custom managers should subclass `BaseContextManager` and implement the required transform behavior.
17
+
18
+ ## ID Generators
19
+
20
+ Import ID generators from `tenxgraph.utils`.
21
+
22
+ Built-ins:
23
+
24
+ - `DefaultIDGenerator`
25
+ - `UUIDGenerator`
26
+ - `BigIntIDGenerator`
27
+ - `TimestampIDGenerator`
28
+ - `IntIDGenerator`
29
+ - `HexIDGenerator`
30
+ - `ShortIDGenerator`
31
+ - `AsyncIDGenerator`
32
+
33
+ Related types:
34
+
35
+ - `BaseIDGenerator`
36
+ - `IDType`
37
+
38
+ Pass an ID generator to `StateGraph(id_generator=...)`. Generated IDs can be accessed through runtime config/container patterns where supported.
39
+
40
+ ## Background Tasks
41
+
42
+ `BackgroundTaskManager` manages async background work such as non-blocking memory writes.
43
+
44
+ Important methods:
45
+
46
+ - `create_task`
47
+ - `get_task_count`
48
+ - `get_task_info`
49
+ - `wait_for_all`
50
+ - `cancel_all`
51
+ - `shutdown`
52
+
53
+ Use `TaskMetadata` for task tracking.
54
+
55
+ ## Graceful Shutdown
56
+
57
+ Utilities include:
58
+
59
+ - `GracefulShutdownManager`
60
+ - `DelayedKeyboardInterrupt`
61
+ - `delayed_keyboard_interrupt`
62
+ - `shutdown_with_timeout`
63
+ - `setup_exception_handler`
64
+
65
+ Use these when a process needs to stop streams, wait for background tasks, and close publishers or storage clients cleanly.
66
+
67
+ ## Rules
68
+
69
+ - Context managers change model input, not persisted checkpointer history.
70
+ - ID generator changes can affect API/client assumptions; verify serialized ID types.
71
+ - Always wait for or cancel background tasks during shutdown.
72
+ - Keep background task payloads bounded and avoid capturing large graph state unless needed.
73
+
74
+ ## Source Map
75
+
76
+ - Context managers: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/state/message_context_manager.py
77
+ - ID generators: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/utils/id_generator.py
78
+ - Background tasks: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/utils/background_task_manager.py
79
+ - Shutdown utilities: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/utils/shutdown.py
80
+ - Docs: https://10xgraph.com/
@@ -0,0 +1,58 @@
1
+ # Dependency Injection
2
+
3
+ Use this when wiring services into nodes/tools, configuring API dependencies, or removing hidden globals.
4
+
5
+ ## Automatic Injection
6
+
7
+ 10xGraph injects these parameters by name/type conventions when they appear in node or tool signatures:
8
+
9
+ - `state`: current `AgentState` or subclass.
10
+ - `config`: execution config such as `thread_id`, `user_id`, and `run_id`.
11
+ - `tool_call_id`: current tool call ID, tools only.
12
+
13
+ Injected parameters are hidden from the model-facing tool schema.
14
+
15
+ ## Service Injection
16
+
17
+ Use `injectq` for application services:
18
+
19
+ ```python
20
+ from injectq import Inject, InjectQ
21
+
22
+ container = InjectQ.get_instance()
23
+ container.bind_instance(MyService, service)
24
+
25
+ def tool(query: str, service: MyService = Inject[MyService]) -> str:
26
+ """Search with MyService."""
27
+ return service.search(query)
28
+ ```
29
+
30
+ You can bind singleton instances, string keys, or factories. Pass a container to `StateGraph(container=container)` when using a non-default container.
31
+
32
+ ## API Configuration
33
+
34
+ In `10xgraph.json`, use import paths to wire dependencies into the server runtime:
35
+
36
+ ```json
37
+ {
38
+ "agent": "graph.react:app",
39
+ "checkpointer": "graph.dependencies:checkpointer",
40
+ "store": "graph.dependencies:store",
41
+ "injectq": "graph.dependencies:container"
42
+ }
43
+ ```
44
+
45
+ The API loader imports these and binds them for graph execution.
46
+
47
+ ## Rules
48
+
49
+ - Prefer `InjectQ` over module-level globals for databases, stores, callbacks, and custom services.
50
+ - Keep user-provided tool arguments model-visible; keep runtime context injected.
51
+ - Configure shared services at graph/server boundaries, not deep inside individual tools.
52
+
53
+ ## Source Map
54
+
55
+ - Docs: https://10xgraph.com/
56
+ - API loader: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/loader.py
57
+ - Graph config: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/config/graph_config.py
58
+ - Tool/node call helpers: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/utils/callable_utils.py