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,194 @@
1
+ # Rate Limiting
2
+
3
+ Use this when adding, configuring, or debugging 10xGraph's built-in sliding-window rate limiter.
4
+
5
+ ## Overview
6
+
7
+ 10xGraph provides a sliding-window rate limiter configured via the `rate_limit` block in
8
+ `10xgraph.json`. The limiter is disabled by default — add the block to activate it.
9
+
10
+ ## Quick Start
11
+
12
+ In-memory backend for local development or single-process services:
13
+
14
+ ```json
15
+ {
16
+ "agent": "graph.react:app",
17
+ "rate_limit": {
18
+ "enabled": true,
19
+ "backend": "memory",
20
+ "requests": 100,
21
+ "window": 60,
22
+ "by": "ip",
23
+ "exclude_paths": ["/ping", "/docs", "/redoc", "/openapi.json"]
24
+ }
25
+ }
26
+ ```
27
+
28
+ Each client IP may make `requests` calls every `window` seconds.
29
+
30
+ ## Redis Backend (Production)
31
+
32
+ Redis stores counters centrally so the limit is enforced across multiple workers,
33
+ containers, or servers. Install the optional extra first:
34
+
35
+ ```bash
36
+ pip install "10xgraph-api[redis]"
37
+ ```
38
+
39
+ ```json
40
+ {
41
+ "agent": "graph.react:app",
42
+ "rate_limit": {
43
+ "enabled": true,
44
+ "backend": "redis",
45
+ "requests": 1000,
46
+ "window": 60,
47
+ "by": "ip",
48
+ "trusted_proxy_headers": true,
49
+ "exclude_paths": ["/ping", "/metrics", "/docs", "/redoc", "/openapi.json"],
50
+ "redis": {
51
+ "url": "${RATE_LIMIT_REDIS_URL}",
52
+ "prefix": "10xgraph:rate-limit"
53
+ },
54
+ "fail_open": true
55
+ }
56
+ }
57
+ ```
58
+
59
+ Set the environment variable:
60
+
61
+ ```bash
62
+ RATE_LIMIT_REDIS_URL=redis://localhost:6379/0
63
+ ```
64
+
65
+ The Redis backend uses an atomic Lua script with sorted sets — check and record happen as a
66
+ single Redis operation, which prevents concurrent requests from racing past the limit.
67
+
68
+ ## Configuration Reference
69
+
70
+ | Field | Type | Default | Description |
71
+ | --- | --- | --- | --- |
72
+ | `enabled` | boolean | `true` | Enables the middleware when the `rate_limit` block exists. |
73
+ | `backend` | string | `"memory"` | `memory`, `redis`, or `custom`. |
74
+ | `requests` | integer | `100` | Maximum requests allowed in each window. |
75
+ | `window` | integer | `60` | Window size in seconds. |
76
+ | `by` | string | `"ip"` | Limit by client IP (`"ip"`) or one shared quota (`"global"`). |
77
+ | `exclude_paths` | string array | `[]` | Paths that bypass rate limiting entirely. |
78
+ | `trusted_proxy_headers` | boolean | `false` | Use `X-Forwarded-For` as the client IP (only behind a trusted proxy). |
79
+ | `redis.url` | string | `null` | Redis URL; required for the Redis backend. Supports `${ENV_VAR}` expansion. |
80
+ | `redis.prefix` | string | `"10xgraph:rate-limit"` | Prefix for all Redis keys. |
81
+ | `fail_open` | boolean | `true` | On Redis errors, allow (`true`) or deny (`false`) requests. |
82
+
83
+ ## Identity Modes
84
+
85
+ Per-IP limit (most public APIs):
86
+
87
+ ```json
88
+ { "rate_limit": { "requests": 100, "window": 60, "by": "ip" } }
89
+ ```
90
+
91
+ Global limit (one shared quota for the whole service):
92
+
93
+ ```json
94
+ { "rate_limit": { "requests": 5000, "window": 60, "by": "global" } }
95
+ ```
96
+
97
+ Only enable `trusted_proxy_headers` when your app sits behind a trusted proxy that strips
98
+ untrusted `X-Forwarded-For` headers from direct clients.
99
+
100
+ ## Response Headers
101
+
102
+ Every response includes:
103
+
104
+ | Header | Description |
105
+ | --- | --- |
106
+ | `X-RateLimit-Limit` | Configured request limit. |
107
+ | `X-RateLimit-Remaining` | Requests remaining in the current window. |
108
+ | `X-RateLimit-Reset` | Unix timestamp for the window reset estimate. |
109
+ | `X-RateLimit-Reset-After` | Seconds until the window reset estimate. |
110
+ | `Retry-After` | Present on `429` responses only. |
111
+
112
+ When the limit is exceeded, 10xGraph returns `429 Too Many Requests`:
113
+
114
+ ```json
115
+ {
116
+ "error": {
117
+ "code": "RATE_LIMIT_EXCEEDED",
118
+ "message": "Too many requests. Limit: 100 per 60s. Retry after 12s.",
119
+ "limit": 100,
120
+ "window_seconds": 60,
121
+ "retry_after_seconds": 12
122
+ },
123
+ "metadata": {
124
+ "request_id": "request-id",
125
+ "status": "error"
126
+ }
127
+ }
128
+ ```
129
+
130
+ ## Custom Backend
131
+
132
+ Implement `BaseRateLimitBackend` and bind the instance through InjectQ, then set
133
+ `"backend": "custom"` in `10xgraph.json`.
134
+
135
+ ```python
136
+ from tenxgraph_api.src.app.core.middleware.rate_limit import (
137
+ BaseRateLimitBackend,
138
+ RateLimitDecision,
139
+ )
140
+
141
+
142
+ class MyRateLimitBackend(BaseRateLimitBackend):
143
+ async def check(self, key: str, *, limit: int, window: int) -> RateLimitDecision:
144
+ allowed = True
145
+ remaining = limit - 1
146
+ reset_after = window
147
+ return RateLimitDecision(
148
+ allowed=allowed,
149
+ remaining=remaining,
150
+ reset_after=reset_after,
151
+ )
152
+
153
+ async def close(self) -> None:
154
+ return None
155
+ ```
156
+
157
+ ```json
158
+ {
159
+ "rate_limit": {
160
+ "enabled": true,
161
+ "backend": "custom",
162
+ "requests": 100,
163
+ "window": 60,
164
+ "by": "ip"
165
+ }
166
+ }
167
+ ```
168
+
169
+ ## Choosing a Backend
170
+
171
+ | Scenario | Backend |
172
+ | --- | --- |
173
+ | Local development, tests, demos | `memory` |
174
+ | Single-process production | `memory` |
175
+ | Gunicorn/Uvicorn with multiple workers | `redis` |
176
+ | Docker / Kubernetes (multiple replicas) | `redis` |
177
+ | Custom storage or quotas | `custom` |
178
+
179
+ ## Rules
180
+
181
+ - Do not enable `trusted_proxy_headers` unless a reverse proxy strips untrusted forwarding headers.
182
+ - Always add health-check and observability paths to `exclude_paths`.
183
+ - In production with Redis set `fail_open: false` only when hard enforcement is required; otherwise `true` prevents availability issues during Redis outages.
184
+ - The `redis` backend requires the `redis` extra: `pip install "10xgraph-api[redis]"`.
185
+ - The `RATE_LIMIT_REDIS_URL` value supports `${ENV_VAR}` expansion — keep secrets out of committed config.
186
+
187
+ ## Source Map
188
+
189
+ - Middleware: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/src/app/core/middleware/rate_limit
190
+ - Base class: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/middleware/rate_limit/base.py
191
+ - Rate-limit config model: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/config/graph_config.py
192
+ - Middleware setup: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/config/setup_middleware.py
193
+ - Docs: https://github.com/10xGraph/10xgraph-api/blob/main/docs/rate-limiting.md
194
+ - Configuration reference: https://github.com/10xGraph/10xgraph-api/blob/main/docs/configuration.md — "Rate Limiting" section
@@ -0,0 +1,172 @@
1
+ # Realtime audio-to-audio (Gemini Live)
2
+
3
+ Use this when building live, full-duplex audio (voice) agents. Unlike `invoke` / `stream`
4
+ (turn-based super-step traversal), a realtime graph is driven by a separate runtime because the
5
+ provider owns the turn loop. Provider neutrality is built in: contracts import no provider SDK, so
6
+ OpenAI Realtime can be added later behind the same `RealtimeClient` Protocol. Today only Gemini
7
+ Live is implemented.
8
+
9
+ ## Install and environment
10
+
11
+ - `pip install "10xgraph[realtime]"` (pulls `google-genai>=1.56.0`).
12
+ - Set `GEMINI_API_KEY`; optionally `GEMINI_LIVE_MODEL` (default `gemini-live-2.5-flash-preview`).
13
+ - Provider SDK imports are lazy: importing `tenxgraph.core.realtime` never requires the extra.
14
+
15
+ ## Audio and media formats
16
+
17
+ - Input audio: PCM16 mono @ 16 kHz. Output audio: PCM16 @ 24 kHz.
18
+ - Transcripts are persisted as `Message`s (`metadata={"modality": "audio"}`); raw audio is never
19
+ stored.
20
+ - Image / video input: still images and video frames are sent live to the model as JPEG frames via
21
+ `LiveInputQueue.send_image(...)`. Like ADK, there is no media store/offload in the realtime path;
22
+ image frames are not persisted (a reconnect reseeds text transcripts only).
23
+
24
+ ## Prebuilt `AudioAgent`
25
+
26
+ `from tenxgraph.prebuilt.agent import AudioAgent` — a React-style builder mirroring `ReactAgent`'s
27
+ construction surface, wrapping a `LiveAgent` as the graph root.
28
+
29
+ ```python
30
+ from tenxgraph.prebuilt.agent import AudioAgent
31
+ from tenxgraph.core.realtime import RealtimeConfig
32
+
33
+ app = AudioAgent(
34
+ "gemini-live-2.5-flash-preview",
35
+ realtime_config=RealtimeConfig(model="gemini-live-2.5-flash-preview", voice="Puck"),
36
+ tools=[my_tool], # advertised to the model automatically; runs React-style
37
+ ).compile()
38
+ ```
39
+
40
+ - Constructor (positional): `model`, then optional `state`, `context_manager`, `publisher`,
41
+ `id_generator`, `container`; keyword-only: `realtime_config`, `system_prompt`, `tools`, `client`,
42
+ `pass_user_info_to_mcp`, `skills`, `memory`, `realtime_client_factory`, `live_node_name="LIVE"`.
43
+ - `compile()` takes `checkpointer`, `store`, `callback_manager`, `shutdown_timeout` (default 30.0).
44
+ It does **not** take `media_store` or `interrupt_before` / `interrupt_after` — those belong to the
45
+ turn-based super-step executor, which realtime bypasses.
46
+ - Tools work like a normal `ToolNode` (reason -> tool -> respond, including barge-in). No
47
+ sub-agents / handoff in v1.
48
+ - `system_prompt`, `skills`, and `memory` work like `ReactAgent`: the agent's `system_prompt` (plus
49
+ the skills catalog / session-mode skill content and the memory system prompt) is flattened
50
+ into the single Gemini Live `system_instruction` at connect, and `{field}` placeholders are
51
+ interpolated from state exactly like the turn-based path. Skill/memory **tools** are advertised
52
+ normally. Caveat: `system_instruction` is fixed for the session, so state-dependent content
53
+ (session-mode skill from a state field, memory preload) is a connect-time snapshot. Mid-session
54
+ dynamism goes through `activate_skill` / memory tools, which work continuously.
55
+
56
+ `LiveAgent` (the graph root `AudioAgent` wraps) is at
57
+ `from tenxgraph.core.realtime.live_agent import LiveAgent`. It is not re-exported from
58
+ `tenxgraph.core.realtime`; import it from the module if you build the graph by hand.
59
+
60
+ ## Driving a session: `CompiledGraph.arealtime` / `realtime`
61
+
62
+ - `arealtime(input_queue, config=None, state=None)` is an async generator yielding normalized
63
+ `RealtimeEvent`s. `realtime(...)` is the sync wrapper (run with no active event loop).
64
+ - Forcing rule: the graph must contain exactly one `LiveAgent`; ordinary graphs raise. Conversely a
65
+ graph containing a `LiveAgent` must use `arealtime()` — `invoke` / `stream` raise.
66
+
67
+ ```python
68
+ from tenxgraph.core.realtime import LiveInputQueue
69
+
70
+ queue = LiveInputQueue()
71
+ queue.send_audio(pcm16_bytes) # non-blocking; safe from an audio callback
72
+ async for event in app.arealtime(queue, {"thread_id": "t1"}):
73
+ ... # AudioDeltaEvent / transcripts / ToolCallEvent / ...
74
+ queue.close() # ends the session once the provider goes idle
75
+ ```
76
+
77
+ ## Public API (`tenxgraph.core.realtime`)
78
+
79
+ - `LiveInputQueue` / `LiveInput` / `LiveInputKind` — non-blocking upstream input queue. Methods
80
+ (all synchronous, callable from any context): `send_audio`, `send_text`, `send_image` (still
81
+ image / video frame, default mime `image/jpeg`), `send_activity_start`, `send_activity_end`,
82
+ `close`.
83
+ - `RealtimeConfig` — per-session config. Fields and defaults:
84
+ - `model: str` (required)
85
+ - `response_modalities: list[...] = ["AUDIO"]` (exactly one per session)
86
+ - `voice: str | None = None`
87
+ - `system_instruction: str | None = None`
88
+ - `input_audio_transcription: bool = True`
89
+ - `output_audio_transcription: bool = True`
90
+ - `vad: VADConfig = VADConfig()`
91
+ - `reconnect: ReconnectConfig = ReconnectConfig()`
92
+ - `context_window_compression: bool = False`
93
+ - `session_resumption: bool = True`
94
+ - `tools: list | None = None`, `tools_tags: list[str] | None = None`
95
+ - `VADConfig` — voice-activity detection; disable for push-to-talk (manual activity via
96
+ `send_activity_start` / `send_activity_end`).
97
+ - `ReconnectConfig` — reconnect/backoff for a dropped socket: `base_delay=0.5`, `max_delay=10.0`,
98
+ `max_attempts=5` (set `0` to disable error-driven reconnect).
99
+ - `RealtimeEvent` — discriminated union (keyed on `type`): `AudioDeltaEvent`,
100
+ `InputTranscriptEvent`, `OutputTranscriptEvent`, `ToolCallEvent`, `ToolResultEvent`,
101
+ `TurnCompleteEvent`, `InterruptedEvent` (barge-in), `SessionUpdateEvent`, `GoAwayEvent`,
102
+ `AgentChangedEvent`, `ErrorEvent`.
103
+ - `RealtimeClient` — provider Protocol (one implementation per provider).
104
+ - `GeminiLiveClient` / `normalize_message` — the Gemini Live provider client.
105
+
106
+ ## Reconnection and resumption
107
+
108
+ Reconnect is automatic inside the realtime runtime (the builder / `AudioAgent` wires nothing).
109
+
110
+ - Provider `go_away` (planned rotation): reconnect immediately, no backoff.
111
+ - Transient drop / receive error: exponential backoff `min(base_delay * 2**(n-1), max_delay)`, up to
112
+ `max_attempts`, then a fatal `ErrorEvent` (`code="reconnect_failed"`) ends the session.
113
+ - Tune per session via `RealtimeConfig.reconnect`:
114
+ ```python
115
+ from tenxgraph.core.realtime import RealtimeConfig, ReconnectConfig
116
+ RealtimeConfig(model="...", reconnect=ReconnectConfig(base_delay=0.25, max_attempts=8))
117
+ ```
118
+ - Context across reconnects: Gemini streams a resumption handle (`session_update`) that is persisted
119
+ to checkpointer thread metadata; reconnect resumes provider-side context (requires
120
+ `session_resumption=True`, the default). With no handle (a fresh session on the same `thread_id`),
121
+ persisted transcript history is reseeded instead. Cross-session resume therefore needs a
122
+ checkpointer.
123
+
124
+ ## Session and turn lifecycle hooks
125
+
126
+ Realtime fires graph/turn hooks through the same `GraphLifecycleHook` used by turn-based graphs
127
+ (register via `CallbackManager.register_lifecycle_hook`, pass the manager to
128
+ `compile(callback_manager=...)`). These fire only in realtime (no-ops for `invoke` / `stream`):
129
+
130
+ - `on_graph_start(ctx, state)` / `on_graph_end(ctx, final_state, messages, total_steps)` — once per
131
+ session (the `LIVE` node *is* the graph). `total_steps` = number of turns.
132
+ - `on_turn_start(ctx, state, turn_index)` / `on_turn_end(ctx, state, turn_index)` — per model turn
133
+ (1-based; a turn spans one model generation, bounded by `turn_complete` or a barge-in). A turn cut
134
+ off by session end still gets a balanced `on_turn_end`.
135
+
136
+ All hooks may return a modified state to replace the current one. Tool/MCP `before/after/error`
137
+ callbacks fire as usual (tools run through `ToolNode`). There is no `AI`-invocation callback or
138
+ input-validator pass in realtime (no discrete LLM call); `on_turn_start` / `on_turn_end` are the
139
+ per-turn observability stand-in.
140
+
141
+ ## API server WebSocket bridge (`/v1/graph/live`)
142
+
143
+ `10xgraph api` exposes `ws://<host>/v1/graph/live` when the configured graph is rooted at a
144
+ `LiveAgent`.
145
+
146
+ - First frame: a JSON control frame (e.g. `{"model": "...", "thread_id": "abc", "voice": "Puck"}`);
147
+ present fields override the agent's build-time config for that session.
148
+ - Upstream: binary frame = PCM16 input audio; JSON control frame =
149
+ `{"type": "text" | "activity_start" | "activity_end" | "close", ...}`. Image/video input is
150
+ currently SDK-only via `LiveInputQueue.send_image`; the WebSocket bridge does not forward image
151
+ frames yet.
152
+ - Downstream: binary frame = PCM16 model audio; JSON text frame = every other event (transcripts,
153
+ `turn_complete`, `interrupted`, `tool_call`, session / `go_away`, `error`).
154
+
155
+ ## Events / publisher additions
156
+
157
+ `Event.REALTIME` event and `ContentType.TRANSCRIPT` content type live in
158
+ `tenxgraph.runtime.publisher.events`.
159
+
160
+ ## Examples
161
+
162
+ `examples/realtime/`: headless WAV-in/WAV-out (`audio_agent_file.py`), live full-duplex microphone
163
+ with React-style tool calling (`audio_agent_mic.py`), and the API WebSocket setup
164
+ (`10xgraph.json` + `graph.py`). See `examples/realtime/README.md`.
165
+
166
+ ## Source Map
167
+
168
+ - Realtime package: https://github.com/10xGraph/10xGraph/tree/main/tenxgraph/core/realtime
169
+ - LiveAgent: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/realtime/live_agent.py
170
+ - AudioAgent: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/prebuilt/agent/audio.py
171
+ - Realtime drivers (`arealtime` / `realtime`): https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/graph/compiled_graph.py
172
+ - WebSocket bridge: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/src/app/routers/graph
@@ -0,0 +1,55 @@
1
+ # Remote Tools
2
+
3
+ Use remote tools for browser or client-owned capabilities while the Python graph runs on the API server.
4
+
5
+ ## Registration
6
+
7
+ Declare the trusted schema in `10xgraph.json`:
8
+
9
+ ```json
10
+ {
11
+ "remote_tools": [
12
+ {
13
+ "node": "TOOLS",
14
+ "name": "read_browser_state",
15
+ "description": "Read selected browser state.",
16
+ "parameters": {"type": "object", "properties": {}, "required": []}
17
+ }
18
+ ]
19
+ }
20
+ ```
21
+
22
+ The API validates and attaches these schemas during startup. `node_name` is accepted as an alias for `node`; other unknown keys fail validation.
23
+
24
+ Register only the implementation in TypeScript:
25
+
26
+ ```typescript
27
+ client.registerToolHandler("read_browser_state", async (args) => {
28
+ return readBrowserState(args);
29
+ });
30
+ ```
31
+
32
+ No setup endpoint exists. A request cannot add, rename, or replace graph tools.
33
+
34
+ ## Execution Flow
35
+
36
+ 1. Model requests a configured remote tool.
37
+ 2. `ToolNode` returns a `RemoteToolCallBlock` instead of executing locally.
38
+ 3. TypeScript `invoke` or `stream` runs the matching handler.
39
+ 4. Client sends a `ToolResultBlock`; graph execution continues.
40
+
41
+ ## Rules
42
+
43
+ - Schema name and client handler name must match exactly.
44
+ - `node` must identify a `ToolNode` in the graph.
45
+ - Remote tool names must be globally unique.
46
+ - Parameters must be an object JSON Schema.
47
+ - Handler results must be serializable.
48
+ - Use local Python or MCP tools for server-owned execution.
49
+
50
+ ## Source Map
51
+
52
+ - Config model: `tenxgraph_api/src/app/core/config/graph_config.py`
53
+ - Startup attachment: `tenxgraph_api/src/app/loader.py`
54
+ - Python remote handling: `tenxgraph/core/graph/tool_node/base.py`
55
+ - TypeScript executor: `agentflow-client/src/tools.ts`
@@ -0,0 +1,97 @@
1
+ # REST API and Errors
2
+
3
+ Use this when changing API routes, response envelopes, schemas, Swagger docs, or error handling.
4
+
5
+ ## Active Routers
6
+
7
+ Registered in https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/routers/setup_router.py:
8
+
9
+ - graph
10
+ - checkpointer / threads
11
+ - store
12
+ - ping
13
+ - media / files
14
+
15
+ ## Graph Routes
16
+
17
+ - `POST /v1/graph/invoke`
18
+ - `POST /v1/graph/stream`
19
+ - `GET /v1/graph`
20
+ - `GET /v1/graph:StateSchema`
21
+ - `POST /v1/graph/stop`
22
+ - `POST /v1/graph/fix`
23
+ - `WS /v1/graph/live` — realtime audio bridge, exposed only when the configured graph is rooted at a
24
+ `LiveAgent`. First frame is a JSON control frame (`model`, `thread_id`, `voice`, ... override
25
+ build-time config); upstream binary = PCM16 input audio, JSON control = text/activity/close;
26
+ downstream binary = PCM16 model audio, JSON = transcripts/turn_complete/interrupted/tool_call/
27
+ error. See `realtime.md`.
28
+
29
+ ## Thread / Checkpointer Routes
30
+
31
+ These expose thread state, messages, thread listing/details, message mutation, and deletion. Use the docs and router source for exact method/path names because client helpers map to these endpoints.
32
+
33
+ TypeScript client wrappers include:
34
+
35
+ - `threadState`
36
+ - `updateThreadState`
37
+ - `clearThreadState`
38
+ - `threadDetails`
39
+ - `threads`
40
+ - `threadMessages`
41
+ - `addThreadMessages`
42
+ - `singleMessage`
43
+ - `deleteMessage`
44
+ - `deleteThread`
45
+
46
+ ## Store Routes
47
+
48
+ - `POST /v1/store/memories`
49
+ - `POST /v1/store/search`
50
+ - `POST /v1/store/memories/{memory_id}`
51
+ - `POST /v1/store/memories/list`
52
+ - `PUT /v1/store/memories/{memory_id}`
53
+ - `DELETE /v1/store/memories/{memory_id}`
54
+ - `POST /v1/store/memories/forget`
55
+
56
+ ## File Routes
57
+
58
+ - `POST /v1/files/upload`
59
+ - `GET /v1/files/{file_id}`
60
+ - `GET /v1/files/{file_id}/info`
61
+ - `GET /v1/files/{file_id}/url`
62
+ - `GET /v1/config/multimodal`
63
+
64
+ ## Ping
65
+
66
+ Use the ping route for liveness/connectivity checks. The TypeScript client wraps this as `client.ping()`.
67
+
68
+ ## Response and Error Handling
69
+
70
+ API helpers wrap successful responses with metadata and request context. Error handlers normalize framework exceptions such as graph errors, node errors, recursion errors, storage errors, validation errors, auth errors, and generic exceptions.
71
+
72
+ Common status expectations:
73
+
74
+ - 400/422 for invalid input.
75
+ - 401 for unauthenticated requests.
76
+ - 403 for authorization failures.
77
+ - 404 for missing resources.
78
+ - 500 for unexpected graph/server failures.
79
+
80
+ ## Rules
81
+
82
+ - Keep Pydantic schemas, router docs, TypeScript endpoint types, and docs aligned.
83
+ - Use `success_response` helpers for consistent envelopes.
84
+ - Preserve SSE format for streaming responses.
85
+ - Sanitize error logs and avoid exposing secrets in details.
86
+ - Add Swagger response metadata for new routes.
87
+
88
+ ## Source Map
89
+
90
+ - Route setup: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/routers/setup_router.py
91
+ - Graph router/schema/service: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/src/app/routers/graph
92
+ - Checkpointer router: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/src/app/routers/checkpointer
93
+ - Store router: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/src/app/routers/store
94
+ - Media router: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/src/app/routers/media
95
+ - Error handlers: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/exceptions/handle_errors.py
96
+ - Response helper: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/utils/response_helper.py
97
+ - Docs: https://10xgraph.com/
@@ -0,0 +1,86 @@
1
+ # Security and Validators
2
+
3
+ Use this when adding prompt-injection protection, content validation, auth-sensitive tool behavior, or safety checks.
4
+
5
+ ## Validator API
6
+
7
+ Validators subclass `BaseValidator` and implement:
8
+
9
+ ```python
10
+ async def validate(self, messages: list[Message]) -> bool:
11
+ ...
12
+ ```
13
+
14
+ Register validators on `CallbackManager`:
15
+
16
+ ```python
17
+ callback_manager = CallbackManager()
18
+ callback_manager.register_input_validator(MyValidator())
19
+ app = graph.compile(callback_manager=callback_manager)
20
+ ```
21
+
22
+ ## Built-ins
23
+
24
+ Exports from `tenxgraph.utils.validators`:
25
+
26
+ - `PromptInjectionValidator`
27
+ - `MessageContentValidator`
28
+ - `ValidationError`
29
+ - `register_default_validators`
30
+
31
+ Use `register_default_validators(callback_manager, strict_mode=True)` to enable standard protections. Strict mode blocks by raising `ValidationError`; lenient behavior may sanitize/log depending on validator settings.
32
+
33
+ ## Callback-Based Safety
34
+
35
+ Use `register_before_invoke` for pre-model or pre-tool checks. Use `register_after_invoke` for output policy checks. Use `register_on_error` for controlled recovery values.
36
+
37
+ Common safety points:
38
+
39
+ - User input validation before AI invocation.
40
+ - Tool argument policy before tool execution.
41
+ - Model output validation before returning to API clients.
42
+ - Store/memory write validation.
43
+
44
+ ## Secret redaction for logs
45
+
46
+ Helpers in `tenxgraph.utils` strip credentials from log output:
47
+
48
+ - `mask_secrets(text)` — redacts API keys, `Bearer` tokens, `key=value` secrets, and signed-URL
49
+ credential query params from a string.
50
+ - `SecretRedactionFilter` — a `logging.Filter`; add it to a handler to cover all loggers that
51
+ propagate to it.
52
+ - `install_secret_redaction(logger_name="tenxgraph")` — convenience installer that attaches the
53
+ filter and returns it.
54
+
55
+ ```python
56
+ from tenxgraph.utils import mask_secrets, SecretRedactionFilter, install_secret_redaction
57
+
58
+ install_secret_redaction() # cover the tenxgraph logger tree
59
+ safe = mask_secrets(raw_text) # one-off redaction
60
+ ```
61
+
62
+ ## API Security Boundary
63
+
64
+ This reference covers graph-level validators. For HTTP auth, read `auth-and-authorization.md`.
65
+
66
+ For production:
67
+
68
+ - Enable API auth unless behind a trusted gateway.
69
+ - Restrict CORS origins.
70
+ - Keep docs endpoints off or protected if needed.
71
+ - Validate remote tool registrations if exposed beyond trusted clients.
72
+
73
+ ## Rules
74
+
75
+ - Keep validators deterministic and fast.
76
+ - Avoid calling LLMs inside validators on the hot path unless explicitly intended.
77
+ - Include the relevant invocation type when registering callbacks.
78
+ - Raise `ValidationError` for expected policy failures.
79
+ - Log safely; sanitize user/tool data before logs.
80
+
81
+ ## Source Map
82
+
83
+ - Callback system: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/utils/callbacks.py
84
+ - Validators: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/utils/validators.py
85
+ - API error handlers: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/exceptions/handle_errors.py
86
+ - Docs: https://10xgraph.com/
@@ -0,0 +1,68 @@
1
+ # State and Messages
2
+
3
+ Use this when changing state schemas, message serialization, multimodal blocks, tool call/result blocks, context trimming, or API/client message compatibility.
4
+
5
+ ## AgentState
6
+
7
+ Default state fields:
8
+
9
+ - `context`: list of `Message`, using the `add_messages` reducer.
10
+ - `context_summary`: optional summary for trimmed context.
11
+ - `execution_meta`: runtime metadata such as current node, step count, interrupt, error, and stop state.
12
+
13
+ Extend `AgentState` for app fields:
14
+
15
+ ```python
16
+ from tenxgraph.core.state import AgentState
17
+
18
+ class OrderState(AgentState):
19
+ order_id: str = ""
20
+ total: float = 0.0
21
+ ```
22
+
23
+ Only returned dict keys are merged. Returning a `Message` appends to `context`; it does not replace history.
24
+
25
+ ## Message
26
+
27
+ `Message` represents one conversation turn. Important fields:
28
+
29
+ - `message_id`
30
+ - `role`: `"user"`, `"assistant"`, `"system"`, or `"tool"`
31
+ - `content`: list of typed content blocks
32
+ - `delta`: true for partial/streaming messages
33
+ - `tools_calls`: provider-native tool call list
34
+ - `reasoning`, `timestamp`, `metadata`, `usages`, `raw`
35
+
36
+ Use `Message.text_message("...", role="user")` for plain text. Use `msg.text()` to concatenate `TextBlock` content.
37
+
38
+ ## Content Blocks
39
+
40
+ Supported block families:
41
+
42
+ - `TextBlock`: text and annotations.
43
+ - `ImageBlock`: image plus `MediaRef`.
44
+ - `AudioBlock`: audio plus transcript/hints.
45
+ - `VideoBlock`: video plus thumbnail.
46
+ - `DocumentBlock`: document media plus optional extracted text/pages/excerpt.
47
+ - `DataBlock`: generic binary data.
48
+ - `ToolCallBlock`: model-requested tool call.
49
+ - `ToolResultBlock`: tool output paired by call ID.
50
+ - `ReasoningBlock`: provider reasoning trace.
51
+ - `AnnotationBlock`: citations/references.
52
+ - `ErrorBlock`: structured error data.
53
+
54
+ ## ToolResult
55
+
56
+ Use `ToolResult(message=..., state={...})` when a tool must both return text to the model and mutate state. Only the named state fields are updated.
57
+
58
+ ## Context Trimming
59
+
60
+ `Agent(trim_context=True)` trims what is sent to the model and writes a summary to `context_summary`. The checkpointer should still preserve full history.
61
+
62
+ ## Source Map
63
+
64
+ - State models: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/state/agent_state.py
65
+ - Message model: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/state/message.py
66
+ - Content blocks: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/state/message_block.py
67
+ - Reducers: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/state/reducers.py
68
+ - TS message class: https://github.com/10xHub/agentflow-client/blob/main/src/message.ts