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.
- 10xgraph_api-0.7.0.dist-info/METADATA +618 -0
- 10xgraph_api-0.7.0.dist-info/RECORD +203 -0
- 10xgraph_api-0.7.0.dist-info/WHEEL +5 -0
- 10xgraph_api-0.7.0.dist-info/entry_points.txt +3 -0
- 10xgraph_api-0.7.0.dist-info/licenses/LICENSE +21 -0
- 10xgraph_api-0.7.0.dist-info/top_level.txt +2 -0
- agentflow_cli/__init__.py +69 -0
- tenxgraph_api/__init__.py +23 -0
- tenxgraph_api/cli/__init__.py +6 -0
- tenxgraph_api/cli/capabilities.py +127 -0
- tenxgraph_api/cli/commands/__init__.py +49 -0
- tenxgraph_api/cli/commands/api.py +262 -0
- tenxgraph_api/cli/commands/audit.py +213 -0
- tenxgraph_api/cli/commands/build.py +305 -0
- tenxgraph_api/cli/commands/config.py +71 -0
- tenxgraph_api/cli/commands/demo.py +93 -0
- tenxgraph_api/cli/commands/eval.py +909 -0
- tenxgraph_api/cli/commands/init.py +531 -0
- tenxgraph_api/cli/commands/skills.py +532 -0
- tenxgraph_api/cli/commands/test.py +113 -0
- tenxgraph_api/cli/commands/version.py +47 -0
- tenxgraph_api/cli/config_editor/__init__.py +15 -0
- tenxgraph_api/cli/config_editor/schema.py +566 -0
- tenxgraph_api/cli/config_editor/server.py +240 -0
- tenxgraph_api/cli/config_editor/static/app.css +2 -0
- tenxgraph_api/cli/config_editor/static/app.js +3 -0
- tenxgraph_api/cli/config_editor/static/favicon.svg +11 -0
- tenxgraph_api/cli/config_editor/static/index.html +20 -0
- tenxgraph_api/cli/config_editor/store.py +120 -0
- tenxgraph_api/cli/config_editor/validation.py +377 -0
- tenxgraph_api/cli/constants.py +112 -0
- tenxgraph_api/cli/context.py +46 -0
- tenxgraph_api/cli/core/__init__.py +0 -0
- tenxgraph_api/cli/core/animations.py +550 -0
- tenxgraph_api/cli/core/config.py +279 -0
- tenxgraph_api/cli/core/output.py +625 -0
- tenxgraph_api/cli/core/prompts.py +220 -0
- tenxgraph_api/cli/core/screen.py +287 -0
- tenxgraph_api/cli/core/steps.py +621 -0
- tenxgraph_api/cli/core/theme.py +242 -0
- tenxgraph_api/cli/core/validation.py +251 -0
- tenxgraph_api/cli/exceptions.py +129 -0
- tenxgraph_api/cli/logger.py +84 -0
- tenxgraph_api/cli/main.py +936 -0
- tenxgraph_api/cli/templates/__init__.py +0 -0
- tenxgraph_api/cli/templates/defaults.py +844 -0
- tenxgraph_api/cli/templates/dev/.env.example +1 -0
- tenxgraph_api/cli/templates/dev/10xgraph.json +16 -0
- tenxgraph_api/cli/templates/dev/graph/__init__.py +0 -0
- tenxgraph_api/cli/templates/dev/graph/agent.py +63 -0
- tenxgraph_api/cli/templates/prod/.env.example +75 -0
- tenxgraph_api/cli/templates/prod/.pre-commit-config.yaml +50 -0
- tenxgraph_api/cli/templates/prod/.python-version +1 -0
- tenxgraph_api/cli/templates/prod/10xgraph.json +42 -0
- tenxgraph_api/cli/templates/prod/auth/__init__.py +0 -0
- tenxgraph_api/cli/templates/prod/auth/agent_auth.py +46 -0
- tenxgraph_api/cli/templates/prod/evals/__init__.py +0 -0
- tenxgraph_api/cli/templates/prod/evals/user_simulator_eval.py +76 -0
- tenxgraph_api/cli/templates/prod/evals/weather_agents_eval.py +53 -0
- tenxgraph_api/cli/templates/prod/graph/__init__.py +0 -0
- tenxgraph_api/cli/templates/prod/graph/agent.py +50 -0
- tenxgraph_api/cli/templates/prod/graph/state.py +5 -0
- tenxgraph_api/cli/templates/prod/graph/thread_name_generator.py +7 -0
- tenxgraph_api/cli/templates/prod/graph/tools/__init__.py +0 -0
- tenxgraph_api/cli/templates/prod/graph/tools/weather_tool.py +43 -0
- tenxgraph_api/cli/templates/prod/graph/validators/__init__.py +0 -0
- tenxgraph_api/cli/templates/prod/graph/validators/lifecyle.py +107 -0
- tenxgraph_api/cli/templates/prod/graph/validators/manager.py +9 -0
- tenxgraph_api/cli/templates/prod/graph/validators/validators.py +21 -0
- tenxgraph_api/cli/templates/prod/pyproject.toml +79 -0
- tenxgraph_api/cli/templates/prod/tests/__init__.py +0 -0
- tenxgraph_api/cli/templates/prod/tests/conftest.py +6 -0
- tenxgraph_api/cli/templates/prod/tests/test_agent_eval.py +78 -0
- tenxgraph_api/cli/templates/prod/tests/test_catalog_tools.py +47 -0
- tenxgraph_api/cli/templates/prod/tests/test_graph_nodes.py +57 -0
- tenxgraph_api/cli/templates/skills/10xgraph/SKILL.md +92 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/agents-and-tools.md +389 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/api-client.md +61 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/api-configuration.md +75 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/api-settings-and-middleware.md +89 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/architecture.md +91 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/auth-and-authorization.md +149 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/callbacks-and-command.md +283 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/checkpointing-and-threads.md +63 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/cli-commands.md +73 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/client-auth-and-errors.md +94 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/client-messages-invoke-stream.md +115 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/client-threads-memory-files.md +80 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/context-id-background.md +80 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/dependency-injection.md +58 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/evaluation.md +500 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/id-and-thread-name-generators.md +69 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/media-and-files.md +66 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/memory-and-store.md +70 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/prebuilt-agents-and-tools.md +394 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/production-runtime.md +56 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/providers-and-adapters.md +89 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/publishers-and-runtime-protocols.md +84 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/rate-limiting.md +194 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/realtime.md +172 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/remote-tools.md +55 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/rest-api-and-errors.md +97 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/security-and-validators.md +86 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/state-and-messages.md +68 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/state-graph.md +232 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/stream-emitter.md +144 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/streaming.md +53 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/testing-and-evaluation.md +64 -0
- tenxgraph_api/cli/templates/skills/10xgraph/references/unit-testing.md +202 -0
- tenxgraph_api/cli/templates/skills/copilot/10xgraph.instructions.md +108 -0
- tenxgraph_api/py.typed +0 -0
- tenxgraph_api/src/__init__.py +0 -0
- tenxgraph_api/src/app/__init__.py +13 -0
- tenxgraph_api/src/app/core/__init__.py +15 -0
- tenxgraph_api/src/app/core/auth/__init__.py +0 -0
- tenxgraph_api/src/app/core/auth/auth_backend.py +38 -0
- tenxgraph_api/src/app/core/auth/authorization.py +379 -0
- tenxgraph_api/src/app/core/auth/base_auth.py +27 -0
- tenxgraph_api/src/app/core/auth/jwt_auth.py +122 -0
- tenxgraph_api/src/app/core/auth/ownership_resolver.py +170 -0
- tenxgraph_api/src/app/core/auth/permissions.py +354 -0
- tenxgraph_api/src/app/core/auth/request_config.py +130 -0
- tenxgraph_api/src/app/core/auth/route_guard.py +105 -0
- tenxgraph_api/src/app/core/config/__init__.py +0 -0
- tenxgraph_api/src/app/core/config/graph_config.py +532 -0
- tenxgraph_api/src/app/core/config/media_settings.py +72 -0
- tenxgraph_api/src/app/core/config/sentry_config.py +60 -0
- tenxgraph_api/src/app/core/config/settings.py +202 -0
- tenxgraph_api/src/app/core/config/setup_logs.py +65 -0
- tenxgraph_api/src/app/core/config/setup_middleware.py +483 -0
- tenxgraph_api/src/app/core/config/worker_middleware.py +99 -0
- tenxgraph_api/src/app/core/exceptions/__init__.py +17 -0
- tenxgraph_api/src/app/core/exceptions/general_exception.py +58 -0
- tenxgraph_api/src/app/core/exceptions/handle_errors.py +363 -0
- tenxgraph_api/src/app/core/exceptions/resources_exceptions.py +72 -0
- tenxgraph_api/src/app/core/exceptions/user_exception.py +58 -0
- tenxgraph_api/src/app/core/middleware/__init__.py +25 -0
- tenxgraph_api/src/app/core/middleware/rate_limit/__init__.py +15 -0
- tenxgraph_api/src/app/core/middleware/rate_limit/base.py +27 -0
- tenxgraph_api/src/app/core/middleware/rate_limit/factory.py +98 -0
- tenxgraph_api/src/app/core/middleware/rate_limit/keying.py +133 -0
- tenxgraph_api/src/app/core/middleware/rate_limit/memory.py +98 -0
- tenxgraph_api/src/app/core/middleware/rate_limit/middleware.py +90 -0
- tenxgraph_api/src/app/core/middleware/rate_limit/redis.py +115 -0
- tenxgraph_api/src/app/core/middleware/request_limits.py +154 -0
- tenxgraph_api/src/app/core/middleware/security_headers.py +239 -0
- tenxgraph_api/src/app/core/utils/__init__.py +14 -0
- tenxgraph_api/src/app/core/utils/log_sanitizer.py +216 -0
- tenxgraph_api/src/app/loader.py +516 -0
- tenxgraph_api/src/app/main.py +180 -0
- tenxgraph_api/src/app/routers/__init__.py +4 -0
- tenxgraph_api/src/app/routers/ag_ui/__init__.py +10 -0
- tenxgraph_api/src/app/routers/ag_ui/converter.py +195 -0
- tenxgraph_api/src/app/routers/ag_ui/event_mapper.py +353 -0
- tenxgraph_api/src/app/routers/ag_ui/router.py +90 -0
- tenxgraph_api/src/app/routers/ag_ui/service.py +193 -0
- tenxgraph_api/src/app/routers/checkpointer/__init__.py +1 -0
- tenxgraph_api/src/app/routers/checkpointer/router.py +482 -0
- tenxgraph_api/src/app/routers/checkpointer/schemas/__init__.py +1 -0
- tenxgraph_api/src/app/routers/checkpointer/schemas/checkpointer_schemas.py +121 -0
- tenxgraph_api/src/app/routers/checkpointer/services/__init__.py +1 -0
- tenxgraph_api/src/app/routers/checkpointer/services/checkpointer_service.py +300 -0
- tenxgraph_api/src/app/routers/evals/__init__.py +6 -0
- tenxgraph_api/src/app/routers/evals/router.py +38 -0
- tenxgraph_api/src/app/routers/evals/services/__init__.py +1 -0
- tenxgraph_api/src/app/routers/evals/services/eval_report_service.py +354 -0
- tenxgraph_api/src/app/routers/graph/__init__.py +6 -0
- tenxgraph_api/src/app/routers/graph/realtime_guard.py +161 -0
- tenxgraph_api/src/app/routers/graph/router.py +821 -0
- tenxgraph_api/src/app/routers/graph/schemas/__init__.py +1 -0
- tenxgraph_api/src/app/routers/graph/schemas/graph_schemas.py +386 -0
- tenxgraph_api/src/app/routers/graph/services/__init__.py +1 -0
- tenxgraph_api/src/app/routers/graph/services/graph_service.py +1219 -0
- tenxgraph_api/src/app/routers/graph/services/multimodal_preprocessor.py +164 -0
- tenxgraph_api/src/app/routers/media/__init__.py +506 -0
- tenxgraph_api/src/app/routers/media/router.py +242 -0
- tenxgraph_api/src/app/routers/media/schemas.py +39 -0
- tenxgraph_api/src/app/routers/ping/__init__.py +4 -0
- tenxgraph_api/src/app/routers/ping/router.py +28 -0
- tenxgraph_api/src/app/routers/setup_router.py +60 -0
- tenxgraph_api/src/app/routers/store/__init__.py +4 -0
- tenxgraph_api/src/app/routers/store/router.py +200 -0
- tenxgraph_api/src/app/routers/store/schemas/__init__.py +28 -0
- tenxgraph_api/src/app/routers/store/schemas/store_schemas.py +200 -0
- tenxgraph_api/src/app/routers/store/services/__init__.py +4 -0
- tenxgraph_api/src/app/routers/store/services/store_service.py +203 -0
- tenxgraph_api/src/app/tasks/__init__.py +0 -0
- tenxgraph_api/src/app/tasks/user_tasks.py +38 -0
- tenxgraph_api/src/app/utils/__init__.py +12 -0
- tenxgraph_api/src/app/utils/callable_helper.py +26 -0
- tenxgraph_api/src/app/utils/media/__init__.py +15 -0
- tenxgraph_api/src/app/utils/media/extractor.py +172 -0
- tenxgraph_api/src/app/utils/media/pipeline.py +83 -0
- tenxgraph_api/src/app/utils/parse_output.py +17 -0
- tenxgraph_api/src/app/utils/response_helper.py +129 -0
- tenxgraph_api/src/app/utils/schemas/__init__.py +11 -0
- tenxgraph_api/src/app/utils/schemas/output_schemas.py +28 -0
- tenxgraph_api/src/app/utils/schemas/user_schemas.py +13 -0
- tenxgraph_api/src/app/utils/snowflake_id_generator.py +90 -0
- tenxgraph_api/src/app/utils/swagger_helper.py +160 -0
- tenxgraph_api/src/app/utils/telemetry_store.py +123 -0
- tenxgraph_api/src/app/utils/thread_name_generator.py +304 -0
- 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
|