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

tenxgraph_api/cli/templates/skills/10xgraph/references/agents-and-tools.md

@@ -0,0 +1,389 @@
+# Agents and Tools
+
+Use this when adding model behavior, tools, tool routing, provider options, retries, fallbacks, memory, skills, or structured output to an agent.
+
+---
+
+## Agent
+
+`Agent` is a graph node that calls an LLM provider and appends the response to state. It supports OpenAI, Google GenAI, and any OpenAI-compatible API behind a unified interface.
+
+### Constructor reference
+
+```python
+Agent(
+    model: str,                                          # required
+    output_type: str = "text",                           # "text" | "image" | "video" | "audio"
+    system_prompt: list[dict] | None = None,
+    tool_node: str | ToolNode | None = None,
+    extra_messages: list[Message] | None = None,
+    trim_context: bool = False,
+    tools_tags: set[str] | None = None,
+    reasoning_config: dict | bool | None = {"effort": "medium"},
+    skills: SkillConfig | None = None,
+    memory: MemoryConfig | None = None,
+    retry_config: RetryConfig | bool | None = True,
+    fallback_models: list[str | tuple[str, str]] | None = None,
+    multimodal_config: MultimodalConfig | None = None,
+    output_schema: type[BaseModel] | None = None,
+    # extra kwargs forwarded to provider SDK:
+    provider: str | None = None,       # "openai" | "google"; auto-detected if omitted
+    base_url: str | None = None,
+    api_style: str = "chat",           # "chat" | "responses" (OpenAI only)
+    use_vertex_ai: bool = False,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    # ...any other provider kwargs
+)
+```
+
+### Model and provider
+
+Provider is auto-detected from the model name. Three ways to set it:
+
+```python
+agent = Agent(model="gpt-4o")                     # auto → openai
+agent = Agent(model="gemini-2.5-flash")            # auto → google
+agent = Agent(model="openai/gpt-4o")              # prefix syntax
+agent = Agent(model="gpt-4o", provider="openai")  # explicit kwarg
+```
+
+Third-party OpenAI-compatible APIs use `provider="openai"` + `base_url`:
+
+```python
+# Ollama (local)
+Agent(model="llama3.2", provider="openai", base_url="http://localhost:11434/v1")
+
+# DeepSeek
+Agent(model="deepseek-chat", provider="openai", base_url="https://api.deepseek.com/v1")
+
+# OpenRouter
+Agent(model="anthropic/claude-3-5-sonnet", provider="openai", base_url="https://openrouter.ai/api/v1")
+```
+
+### System prompt
+
+Pass a list of message dicts. `{field_name}` placeholders are replaced at runtime with values from `AgentState`:
+
+```python
+class MyState(AgentState):
+    user_name: str = "Guest"
+    language: str = "English"
+
+agent = Agent(
+    model="gpt-4o",
+    system_prompt=[{"role": "system", "content": "Help {user_name}. Reply in {language}."}],
+)
+```
+
+### Reasoning config
+
+Reasoning is **on by default** at medium effort. Applies to both OpenAI and Google models.
+
+```python
+agent = Agent(model="gpt-4o")                                          # on, medium effort
+agent = Agent(model="gpt-4o", reasoning_config={"effort": "high"})
+agent = Agent(model="gpt-4o", reasoning_config=None)                   # off
+agent = Agent(model="o4-mini", reasoning_config={"effort": "low", "summary": "auto"})  # OpenAI
+agent = Agent(model="gemini-2.5-flash", reasoning_config={"thinking_budget": 5000})    # Google exact
+```
+
+Google effort → thinking_budget mapping:
+
+| `effort` | `thinking_budget` |
+|---|---|
+| `"low"` | 512 |
+| `"medium"` (default) | 8192 |
+| `"high"` | 24576 |
+
+### Retry config
+
+Default: 3 retries, 1 s initial delay, 2x back-off, 30 s cap. Retries on HTTP 429, 500, 502, 503, 529.
+
+```python
+from tenxgraph.core.graph.agent_internal.constants import RetryConfig
+
+agent = Agent(model="gpt-4o", retry_config=False)   # disable
+
+agent = Agent(
+    model="gpt-4o",
+    retry_config=RetryConfig(max_retries=5, initial_delay=2.0, max_delay=60.0, backoff_factor=2.0),
+)
+```
+
+`RetryConfig` fields: `max_retries` (3), `initial_delay` (1.0 s), `max_delay` (30.0 s), `backoff_factor` (2.0).
+
+### Circuit breaker (opt-in)
+
+Complements retry + `fallback_models`. Once a `(provider, model)` target fails
+`circuit_breaker_threshold` times in a row, its circuit opens and that target is skipped (straight
+to the next fallback) for `circuit_breaker_reset_timeout` seconds, instead of being retried on every
+call. Configure on `RetryConfig`:
+
+- `circuit_breaker_enabled: bool = False`
+- `circuit_breaker_threshold: int = 5`
+- `circuit_breaker_reset_timeout: float = 30.0`
+
+```python
+RetryConfig(circuit_breaker_enabled=True, circuit_breaker_threshold=3, circuit_breaker_reset_timeout=60.0)
+```
+
+### Fallback models
+
+When the primary model exhausts all retries, 10xGraph tries each fallback in order:
+
+```python
+agent = Agent(
+    model="gemini-2.5-flash",
+    provider="google",
+    fallback_models=[
+        "gemini-2.0-flash",                 # inherit provider
+        ("gpt-4o-mini", "openai"),          # explicit (model, provider) tuple
+    ],
+)
+```
+
+### LLM call timeout
+
+All LLM clients apply a default request timeout (600 s) so a stalled provider cannot hang a run
+indefinitely. Override globally via the `AGENTFLOW_LLM_TIMEOUT` env var (seconds), or
+programmatically:
+
+```python
+from tenxgraph.core.llm import (
+    set_default_llm_timeout, get_default_llm_timeout, DEFAULT_LLM_TIMEOUT_SECONDS,
+)
+
+set_default_llm_timeout(120.0)   # set
+set_default_llm_timeout(None)    # reset to default
+```
+
+An explicit per-client `timeout=` still takes precedence.
+
+### Structured output
+
+`output_schema` with a Pydantic model forces JSON output. Requires `output_type="text"` (default).
+
+```python
+from pydantic import BaseModel
+
+class ReviewAnalysis(BaseModel):
+    sentiment: str
+    score: float
+    summary: str
+
+agent = Agent(model="gpt-4o", output_schema=ReviewAnalysis)
+```
+
+### Extra messages
+
+`extra_messages` are injected into every LLM call after the system prompt and before the context window. Use for few-shot examples or static instructions:
+
+```python
+agent = Agent(
+    model="gpt-4o",
+    extra_messages=[
+        Message.text_message("Q: What is 2+2?", role="user"),
+        Message.text_message("A: 4", role="assistant"),
+    ],
+)
+```
+
+### API style (OpenAI)
+
+```python
+agent = Agent(model="gpt-4o",  api_style="chat")       # default — Chat Completions
+agent = Agent(model="o4-mini", api_style="responses")  # Responses API
+```
+
+---
+
+## ToolNode
+
+`ToolNode` registers and executes callable tools. It supports local Python functions, MCP tools, Composio integrations, and dynamically added tools.
+
+```python
+from tenxgraph.core.graph import ToolNode
+
+tool_node = ToolNode([get_weather, safe_calculator])
+
+# Add a tool after creation
+tool_node.add_tool(search_db)
+```
+
+### Tool authoring rules
+
+- Docstring → model-facing tool description. Required for useful behavior.
+- Type annotations → parameter schema. Required for correct tool calls.
+- Return a plain value for a normal tool result.
+- Return `ToolResult` to update state fields and return a message to the model.
+- Keep model-visible parameters separate from injected parameters.
+
+### Injectable parameters
+
+These are invisible to the model schema — `ToolNode` injects them automatically:
+
+| Parameter | Type | What is injected |
+|---|---|---|
+| `state` | `AgentState \| None` | Current graph state |
+| `tool_call_id` | `str \| None` | ID of this specific tool call |
+| `config` | `dict` | Execution config (`thread_id`, `user_id`, `run_id`, …) |
+
+```python
+def get_weather(
+    location: str,                         # from model
+    state: AgentState | None = None,       # injected, hidden from schema
+    config: dict | None = None,            # injected, hidden from schema
+) -> str:
+    """Get weather for a location."""
+    user = config.get("user_id", "anon") if config else "anon"
+    return f"Sunny in {location} (user: {user})"
+```
+
+### Returning state updates
+
+Use `ToolResult` when a tool needs to update state fields and return a message:
+
+```python
+from tenxgraph.core.state.tool_result import ToolResult
+
+class MyState(AgentState):
+    selected_city: str = ""
+
+def select_city(city: str) -> ToolResult:
+    """Set the currently selected city."""
+    return ToolResult(message=f"City set to '{city}'.", state={"selected_city": city})
+```
+
+### Filter tools by tag
+
+`tools_tags` on `Agent` exposes only matching tools to the LLM:
+
+```python
+@tool(tags=["safe"])
+def safe_search(query: str) -> str: ...
+
+@tool(tags=["admin"])
+def admin_action(cmd: str) -> str: ...
+
+tool_node = ToolNode([safe_search, admin_action])
+agent = Agent(model="gpt-4o", tool_node=tool_node, tools_tags={"safe"})
+# admin_action is hidden from this agent's model schema
+```
+
+### MCP tools
+
+```bash
+pip install "10xgraph[mcp]"
+```
+
+```python
+tool_node = ToolNode(
+    [local_fn],
+    client=mcp_client,               # fastmcp Client
+    pass_user_info_to_mcp=True,      # forward config["user"] to MCP context
+)
+```
+
+---
+
+## The `@tool` decorator
+
+Attaches metadata to any function. Does not change injection behavior — enriches the model schema:
+
+```python
+from tenxgraph.utils import tool
+
+@tool(
+    name="web_search",
+    description="Search the web for up-to-date information.",
+    tags=["search", "web"],
+    provider="custom",
+    capabilities=["network_access"],
+    metadata={"rate_limit": 100},
+)
+async def search_web(query: str, max_results: int = 5) -> list[str]:
+    """Search the web."""
+    ...
+```
+
+Without arguments: function name and docstring are used as defaults.
+
+---
+
+## ReAct loop
+
+Standard routing pattern. The routing function inspects the last message:
+
+```python
+from tenxgraph.utils import END
+
+def route(state: AgentState) -> str:
+    if not state.context:
+        return END
+    last = state.context[-1]
+    if hasattr(last, "tools_calls") and last.tools_calls and last.role == "assistant":
+        return "TOOL"
+    if last.role == "tool":
+        return "MAIN"
+    return END
+
+graph.add_conditional_edges("MAIN", route, {"TOOL": "TOOL", END: END})
+graph.add_edge("TOOL", "MAIN")
+```
+
+### Passing tool_node by name
+
+Pass a string to share one `ToolNode` across multiple agents:
+
+```python
+agent = Agent(model="gpt-4o", tool_node="TOOL")
+graph.add_node("MAIN", agent)
+graph.add_node("TOOL", tool_node)
+```
+
+---
+
+## Skills (Agent Skills specification)
+
+`skills=SkillConfig(...)` loads skills that follow https://agentskills.io/specification: one
+directory per skill with a `SKILL.md` (YAML frontmatter `name` + `description`, optional
+`license`, `compatibility`, `allowed-tools`, `metadata`) and optional `scripts/`, `references/`,
+`assets/`.
+
+```python
+from tenxgraph.core.skills import SkillConfig
+
+agent = Agent(
+    model="gpt-4o",
+    tool_node=ToolNode([]),
+    skills=SkillConfig(skills_dir=["./.agents/skills", "./shared-skills"]),
+)
+```
+
+- On-demand mode (default) adds an `<available_skills>` catalog (name + description) to the
+  system prompt and registers `activate_skill(skill_name)`. The result is the SKILL.md body in
+  `<skill_content name="...">` tags plus a `<skill_resources>` file list.
+- `read_skill_resource(skill_name, path)` is registered when any skill bundles files. It reads any
+  file in the skill directory as text (markdown, `.py`, `.sh`, JSON, ...); nothing is executed.
+- `mode="session", preload_from="FIELD"` injects the skill named by `state.FIELD` every call.
+- Activated skills are recorded in `state.execution_meta.internal_data["active_skills"]` and are
+  re-injected if context trimming drops their tool result.
+- 10xGraph extensions live in `metadata` as strings: `triggers: "a; b"`, `tags: "x, y"`,
+  `priority: "10"`.
+- `SkillConfig` options: `skills_dir` (path or ordered list; earlier wins on name clashes),
+  `inject_catalog`, `hot_reload`, `max_resource_bytes`, `include_skill_path`, `mode`,
+  `preload_from`.
+- Validate with `10xgraph skills --validate PATH` or `tenxgraph.core.skills.validate_skill`.
+
+---
+
+## Source map
+
+- Agent: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/graph/agent.py
+- ToolNode: https://github.com/10xGraph/10xGraph/tree/main/tenxgraph/core/graph
+- ToolResult: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/state/tool_result.py
+- RetryConfig: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/core/graph/agent_internal/constants.py
+- `@tool` decorator: https://github.com/10xGraph/10xGraph/blob/main/tenxgraph/utils/decorators.py
+- Skills: https://github.com/10xGraph/10xGraph/tree/main/tenxgraph/core/skills
+- How-to (configure Agent): https://10xgraph.com/how-to/python/configure-agent

tenxgraph_api/cli/templates/skills/10xgraph/references/api-client.md

@@ -0,0 +1,61 @@
+# API and TypeScript Client
+
+Use this when aligning REST routes, schemas, generated docs, or the TypeScript npm SDK. The public npm package is `@10xscale/agentflow-client`; install it with `npm install @10xscale/agentflow-client`.
+
+Check current docs first: https://10xgraph.com/
+
+## API Routers
+
+Active routers are included from https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/routers/setup_router.py:
+
+- Graph router
+- Checkpointer/thread router
+- Store router
+- Ping router
+- Media/files router
+
+Graph routes include:
+
+- `POST /v1/graph/invoke`
+- `POST /v1/graph/stream`
+- `GET /v1/graph`
+- `GET /v1/graph:StateSchema`
+- `POST /v1/graph/stop`
+- `POST /v1/graph/fix`
+
+Memory/file routes are summarized in their topic references.
+
+## TypeScript SDK Facade
+
+`AgentFlowClient` is exported by `@10xscale/agentflow-client`. Its source facade is https://github.com/10xHub/agentflow-client/blob/main/src/client.ts, and it wraps:
+
+- Connectivity and metadata: `ping`, `graph`, `graphStateSchema`
+- Execution: `invoke`, `stream`, `stopGraph`, `fixGraph`
+- Threads/messages: `threadState`, `updateThreadState`, `clearThreadState`, `threadDetails`, `threads`, `threadMessages`, `addThreadMessages`, `singleMessage`, `deleteMessage`, `deleteThread`
+- Memory: `storeMemory`, `searchMemory`, `getMemory`, `updateMemory`, `deleteMemory`, `listMemories`, `forgetMemories`
+- Files: `uploadFile`, `getFile`, `getFileInfo`, `getFileAccessUrl`, `getMultimodalConfig`
+- Remote tools: schemas in server `10xgraph.json`, handlers via `registerToolHandler`
+
+For remote tools, read `remote-tools.md`; that flow has a client-managed execution loop around `remote_tool_call` blocks.
+
+## Request Conventions
+
+- The client serializes `Message` instances to plain API payloads.
+- Server expects message content as an array of content blocks.
+- `message_id` is sent as a string; `"0"` lets the server generate/normalize where applicable.
+- `recursion_limit` defaults to `25`.
+- Streaming defaults to low response granularity in the client.
+
+## Rules
+
+- Use `@10xscale/agentflow-client` in user-facing examples and docs.
+- The TypeScript SDK calls a running 10xGraph API server. It does not import or execute Python graph code.
+- Keep endpoint schema changes mirrored in the client endpoints directory.
+- Test both endpoint helpers and the `AgentFlowClient` facade for client-visible changes.
+
+## Source Map
+
+- Client facade: https://github.com/10xHub/agentflow-client/blob/main/src/client.ts
+- Client endpoints: https://github.com/10xHub/agentflow-client/tree/main/src/endpoints
+- Client message model: https://github.com/10xHub/agentflow-client/blob/main/src/message.ts
+- API schemas/services: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/src/app/routers

tenxgraph_api/cli/templates/skills/10xgraph/references/api-configuration.md

@@ -0,0 +1,75 @@
+# API Configuration
+
+Use this when changing `10xgraph.json`, dependency loading, app startup, or graph import behavior.
+
+## `10xgraph.json`
+
+Minimal:
+
+```json
+{
+  "agent": "graph.react:app"
+}
+```
+
+Common full shape:
+
+```json
+{
+  "agent": "graph.react:app",
+  "checkpointer": "graph.dependencies:my_checkpointer",
+  "store": "graph.dependencies:my_store",
+  "injectq": "graph.dependencies:container",
+  "thread_name_generator": "graph.thread_name_generator:MyNameGenerator",
+  "authorization": "graph.auth:my_authorization_backend",
+  "env": ".env",
+  "auth": "jwt",
+  "remote_tools": [],
+  "rate_limit": {
+    "enabled": true,
+    "backend": "memory",
+    "requests": 100,
+    "window": 60,
+    "by": "ip",
+    "exclude_paths": ["/ping", "/docs", "/redoc", "/openapi.json"]
+  }
+}
+```
+
+## Fields
+
+- `agent`: required import path to a compiled graph variable, in `module.path:attribute` format.
+- `checkpointer`: optional import path to a `BaseCheckpointer` instance.
+- `store`: optional import path to a `BaseStore` instance; required for store endpoints.
+- `injectq`: optional import path to an `InjectQ` container.
+- `thread_name_generator`: optional import path to a thread-name generator class/instance.
+- `authorization`: `null` (mode default: `ownership` in production, `allow_all` in dev), a built-in name (`"ownership"` | `"allow_all"`/`"default"`/`"none"`), an RBAC config object (`{"backend": "rbac", "roles": {...}, "default_scopes": [...], "isolation": "owner"}`), or a `module:attr` import path to a custom `AuthorizationBackend`. See `references/auth-and-authorization.md`.
+- `env`: optional `.env` path loaded before graph import.
+- `auth`: `null`, `"jwt"`, or `{"method": "custom", "path": "module:backend"}`.
+- `remote_tools`: validated client-executed tool schemas, attached once at startup.
+- `rate_limit`: optional sliding-window rate limiter config object; omit or set to `null` to disable. See `references/rate-limiting.md` for the full field reference.
+
+## Loading Order
+
+1. Read `10xgraph.json`.
+2. Load `.env` when configured.
+3. Import the compiled graph from `agent`.
+4. Attach `remote_tools`, then import and bind `checkpointer`, `store`, `injectq`, `thread_name_generator`, and `authorization` when configured.
+5. Configure auth.
+6. Start FastAPI routes and services.
+
+## Rules
+
+- Keep graph modules importable from the project root.
+- Keep `agent` pointing to a compiled graph object, not an uncompiled `StateGraph`.
+- Keep dependency modules side-effect light.
+- Load secrets through `.env` or process environment, not committed config.
+- Validate import paths early and surface clear CLI/API errors.
+
+## Source Map
+
+- Graph config: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/config/graph_config.py
+- Loader: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/loader.py
+- App startup: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/main.py
+- Docs: https://10xgraph.com/
+- Rate limit config details: `references/rate-limiting.md`

tenxgraph_api/cli/templates/skills/10xgraph/references/api-settings-and-middleware.md

@@ -0,0 +1,89 @@
+# API Settings and Middleware
+
+Use this when changing environment variables, app settings, middleware, CORS, request limits, security headers, docs paths, or Sentry.
+
+## Settings
+
+`Settings` reads environment variables through Pydantic settings.
+
+Important variables:
+
+- `APP_NAME`
+- `APP_VERSION`
+- `MODE`
+- `LOG_LEVEL`
+- `IS_DEBUG`
+- `MAX_REQUEST_SIZE`
+- `ORIGINS`
+- `ALLOWED_HOST`
+- `ROOT_PATH`
+- `DOCS_PATH`
+- `REDOCS_PATH`
+- `REDIS_URL`
+- `SENTRY_DSN`
+- `JWT_SECRET_KEY`
+- `JWT_ALGORITHM`
+
+Security header variables:
+
+- `SECURITY_HEADERS_ENABLED`
+- `HSTS_ENABLED`
+- `HSTS_MAX_AGE`
+- `HSTS_INCLUDE_SUBDOMAINS`
+- `HSTS_PRELOAD`
+- `FRAME_OPTIONS`
+- `CONTENT_TYPE_OPTIONS`
+- `XSS_PROTECTION`
+- `REFERRER_POLICY`
+- `PERMISSIONS_POLICY`
+- `CSP_POLICY`
+
+## Middleware
+
+Active middleware areas:
+
+- CORS and host handling.
+- Request size limits.
+- Security headers.
+- Request ID assignment.
+- Selective gzip behavior; streaming endpoints should avoid gzip buffering when configured.
+- Worker middleware where used by deployment.
+- Rate limiting: sliding-window limiter controlled by the `rate_limit` block in `10xgraph.json`.
+  Uses an in-process `memory` backend by default; use the `redis` backend (requires
+  `pip install "10xgraph-api[redis]"`) for multi-worker or multi-instance deployments.
+  Excluded paths, identity mode (`ip` or `global`), and `fail_open` behavior are all configurable.
+  See `references/rate-limiting.md` for the full option reference.
+
+## Production Warnings
+
+Production mode warns about unsafe defaults such as:
+
+- `ORIGINS=*`
+- debug enabled
+- docs endpoints enabled
+- `ALLOWED_HOST=*`
+
+## Sentry
+
+`SENTRY_DSN` enables Sentry setup through the API config module. Keep error reporting optional and safe when unset.
+
+## Rules
+
+- Keep environment variable docs in sync with `Settings`.
+- Use `ROOT_PATH` when serving behind a reverse proxy subpath.
+- Disable or protect docs paths in production when needed.
+- Do not gzip SSE streams.
+- Sanitize logs for tokens, secrets, and large payloads.
+
+## Source Map
+
+- Settings: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/config/settings.py
+- Middleware setup: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/config/setup_middleware.py
+- Request limits: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/middleware/request_limits.py
+- Security headers: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/middleware/security_headers.py
+- Rate limit middleware: https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api/src/app/core/middleware/rate_limit
+- Rate limit base class: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/middleware/rate_limit/base.py
+- Sentry: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/config/sentry_config.py
+- Log sanitizer: https://github.com/10xGraph/10xgraph-api/blob/main/tenxgraph_api/src/app/core/utils/log_sanitizer.py
+- Docs: https://10xgraph.com/
+- Rate limiting docs: https://github.com/10xGraph/10xgraph-api/blob/main/docs/rate-limiting.md