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

tenxgraph_api/cli/templates/prod/graph/validators/validators.py

@@ -0,0 +1,21 @@
+from tenxgraph.utils.validators import PromptInjectionValidator
+
+
+prompt_validator = PromptInjectionValidator(
+    strict_mode=True,
+    max_length=1000,
+    blocked_patterns=[],
+    suspicious_keywords=[
+        "ignore previous",
+        "forget previous",
+        "disregard previous",
+        "bypass",
+        "circumvent",
+        "override",
+        "disable",
+        "remove restrictions",
+        "token",
+        "coupon",
+        "free",
+    ],
+)

tenxgraph_api/cli/templates/prod/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "$agent_name_slug"
+version = "0.1.0"
+description = "$agent_name — an AI agent built with 10xGraph."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.12"
+authors = []
+dependencies = [
+    "10xgraph",
+    "10xgraph-api",
+    "google-genai",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "pytest-env",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+lint.fixable = ["ALL"]
+lint.select = [
+    "E", "W", "F", "PL", "I", "B", "A", "S", "ISC", "ICN", "PIE", "Q",
+    "RET", "SIM", "TID", "RUF", "YTT", "UP", "C4", "PTH", "G", "INP", "T20",
+]
+lint.ignore = [
+    "UP006", "UP007", "RUF012", "G004", "B904", "B008", "ISC001",
+]
+lint.dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+exclude = ["venv/*"]
+
+[tool.ruff.lint.per-file-ignores]
+"*/tests/*.py" = ["S101", "T201"]
+"*/__init__.py" = ["E402", "S101"]
+
+[tool.ruff.lint.isort]
+lines-after-imports = 2
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.bandit]
+skips = ["B101"]
+
+[tool.pytest.ini_options]
+env = ["ENVIRONMENT=pytest"]
+testpaths = ["tests"]
+pythonpath = ["."]
+filterwarnings = ["ignore::DeprecationWarning"]
+addopts = [
+    "--cov=graph", "--cov-report=html", "--cov-report=term-missing",
+    "--cov-report=xml", "--cov-fail-under=0", "--strict-markers", "-v"
+]
+
+[tool.coverage.run]
+source = ["graph"]
+branch = true
+omit = [
+    "*/__init__.py", "*/tests/*", "*/venv/*", "*/.venv/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "if __name__ == '__main__':", "pragma: no cover", "@abstractmethod",
+    "raise NotImplementedError",
+]
+show_missing = true

tenxgraph_api/cli/templates/prod/tests/conftest.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+import os
+
+
+os.environ.setdefault("GEMINI_API_KEY", "test-key")

tenxgraph_api/cli/templates/prod/tests/test_agent_eval.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import asyncio
+
+from tenxgraph.qa import QuickTest
+from tenxgraph.qa.evaluation import (
+    CriterionResult,
+    EvalCaseResult,
+    EvalReport,
+    EvalSummary,
+    ReporterConfig,
+    ReporterManager,
+)
+
+from evals.weather_agents_eval import get_eval_set
+
+
+def test_eval_set_covers_core_weather_behaviors() -> None:
+    eval_set = get_eval_set()
+
+    case_ids = {case.eval_id for case in eval_set.eval_cases}
+    case_names = {case.name for case in eval_set.eval_cases}
+
+    assert eval_set.name == "weather-agent-regression"
+    assert len(eval_set.eval_cases) == 4
+    assert "greeting_response" in case_names
+    assert "weather_london" in case_ids
+    assert "weather_new_york" in case_ids
+    assert "weather_tokyo" in case_ids
+
+
+def test_reporter_writes_html_and_json_artifacts(tmp_path) -> None:
+    report = EvalReport(
+        eval_set_id="weather-agent-regression",
+        eval_set_name="weather-agent-regression",
+        results=[
+            EvalCaseResult(
+                eval_id="sample",
+                name="sample",
+                passed=True,
+                actual_response="The weather in London is sunny",
+                criterion_results=[
+                    CriterionResult(
+                        criterion="response",
+                        score=1.0,
+                        passed=True,
+                        threshold=0.6,
+                    )
+                ],
+            )
+        ],
+        summary=EvalSummary(
+            total_cases=1,
+            passed_cases=1,
+            failed_cases=0,
+            error_cases=0,
+            pass_rate=1.0,
+        ),
+    )
+
+    output = ReporterManager(
+        ReporterConfig(output_dir=str(tmp_path), html=True, json_report=True, console=False)
+    ).run_all(report, output_dir=str(tmp_path))
+
+    assert output.json_path is not None
+    assert output.html_path is not None
+    assert "weather-agent-regression" in tmp_path.joinpath(output.json_path).read_text(
+        encoding="utf-8"
+    )
+
+
+def test_quick_test_smoke_for_expected_weather_greeting() -> None:
+    result = QuickTest.single_turn(
+        agent_response="Hello! I can help you check the weather anywhere. What location are you interested in?",
+        user_message="Hi",
+    )
+
+    asyncio.run(result).assert_contains("weather").assert_no_errors()

tenxgraph_api/cli/templates/prod/tests/test_catalog_tools.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from graph.state import WeatherState
+from graph.tools.weather_tool import get_weather
+
+
+def test_get_weather_returns_sunny_message_for_location() -> None:
+    with patch(
+        "graph.tools.weather_tool.call_weather_api", return_value="The weather in London is sunny"
+    ):
+        result = get_weather(location="London")
+
+    assert "London" in result
+    assert "sunny" in result
+
+
+def test_get_weather_retries_on_failure_and_returns_error_after_max_attempts() -> None:
+    with patch("graph.tools.weather_tool.call_weather_api", side_effect=Exception("API error")):
+        result = get_weather(location="Paris")
+
+    assert "Paris" in result
+    assert "sorry" in result.lower()
+
+
+def test_get_weather_emits_progress_events_when_emitter_is_provided() -> None:
+    emit = MagicMock()
+
+    with patch(
+        "graph.tools.weather_tool.call_weather_api", return_value="The weather in Tokyo is sunny"
+    ):
+        result = get_weather(location="Tokyo", emit=emit)
+
+    emit.progress.assert_called()
+    assert "Tokyo" in result
+
+
+def test_get_weather_accepts_injected_tool_call_id_and_state() -> None:
+    state = WeatherState()
+
+    with patch(
+        "graph.tools.weather_tool.call_weather_api", return_value="The weather in Berlin is sunny"
+    ):
+        result = get_weather(location="Berlin", tool_call_id="call_1", state=state)
+
+    assert "Berlin" in result

tenxgraph_api/cli/templates/prod/tests/test_graph_nodes.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from tenxgraph.core.state.message import Message
+from tenxgraph.utils.constants import END
+
+from graph.nodes.main_node import agent
+from graph.utils.tool_decision import should_use_tools
+
+
+def test_main_agent_is_configured_for_weather_assistant() -> None:
+    assert agent.model == "gemini-3-flash-preview"
+    assert agent.provider == "google"
+    assert agent.trim_context is True
+    assert agent.tool_node == "TOOL"
+
+    system_prompt_text = " ".join(
+        block["content"] for block in agent.system_prompt if "content" in block
+    )
+    assert "helpful assistant" in system_prompt_text.lower()
+
+
+def test_should_end_when_no_context_exists() -> None:
+    assert should_use_tools(SimpleNamespace(context=[])) == END
+
+
+def test_should_route_assistant_tool_calls_to_tool_node() -> None:
+    state = SimpleNamespace(
+        context=[
+            Message(
+                role="assistant",
+                content=[],
+                tools_calls=[
+                    {
+                        "id": "call_1",
+                        "name": "get_weather",
+                        "args": {"location": "London"},
+                    }
+                ],
+            )
+        ]
+    )
+
+    assert should_use_tools(state) == "TOOL"
+
+
+def test_should_route_tool_result_back_to_main_agent() -> None:
+    state = SimpleNamespace(context=[Message(role="tool", content=[])])
+
+    assert should_use_tools(state) == "MAIN"
+
+
+def test_should_end_after_regular_assistant_response() -> None:
+    state = SimpleNamespace(context=[Message(role="assistant", content=[])])
+
+    assert should_use_tools(state) == END

tenxgraph_api/cli/templates/skills/10xgraph/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: 10xgraph
+description: >-
+  Expert guidance for building, debugging, and extending applications with 10xGraph
+  (10xgraph). Use when code imports from tenxgraph or the legacy agentflow name (e.g. `from tenxgraph import`,
+  `StateGraph`, `Agent`, `ToolNode`, `AgentState`); when the user references `10xgraph.json`
+  or CLI commands (`10xgraph init`, `10xgraph api`, `10xgraph play`, `10xgraph build`,
+  `10xgraph skills`); or when the user is building graph-based multi-agent workflows, tools,
+  memory, checkpointing, or streaming with this framework. Skip generic Python or multi-agent
+  questions that do not reference 10xGraph, and other frameworks (LangGraph, CrewAI, AutoGen)
+  unless comparing.
+license: MIT
+---
+
+# 10xGraph Project Skill
+
+Use this skill when working in a 10xGraph project. 10xGraph is a multi-agent framework that wraps official OpenAI and Google SDK capabilities behind a unified graph, agent, tool, state, storage, API, CLI, and TypeScript client interface.
+
+Treat https://10xgraph.com/ as the first source of truth for public package names, install commands, and user-facing behavior. Use implementation source after the docs establish the intended API.
+
+## Workflow
+
+1. Identify the published package or docs surface involved:
+   - PyPI core Python SDK: `10xgraph` (`pip install 10xgraph`), source at https://github.com/10xGraph/10xGraph/tree/main/tenxgraph
+   - PyPI API/CLI SDK: `10xgraph-api` (`pip install 10xgraph-api`), source at https://github.com/10xGraph/10xgraph-api/tree/main/tenxgraph_api
+   - npm TypeScript SDK: `@10xscale/agentflow-client` (`npm install @10xscale/agentflow-client`), source at https://github.com/10xHub/Agentflow/tree/main/agentflow-client/src
+   - Main docs: https://10xgraph.com/
+   - Playground/UI: `10xgraph play` command after installed cli
+
+2. Read the matching reference file before changing behavior. Paths are relative to this skill's directory:
+
+   ### Core Python SDK
+   - Architecture and package flow: `references/architecture.md`
+   - Agent constructor, provider, reasoning, retry, fallback, output_schema: `references/agents-and-tools.md`
+   - Graph construction, nodes, edges, compile, interrupts, config keys: `references/state-graph.md`
+   - State, messages, and content blocks: `references/state-and-messages.md`
+   - Threads and checkpointing: `references/checkpointing-and-threads.md`
+   - Dependency injection (InjectQ): `references/dependency-injection.md`
+   - Multimodal files and media stores: `references/media-and-files.md`
+   - Long-term memory stores (MemoryConfig, QdrantStore, Mem0Store): `references/memory-and-store.md`
+   - Streaming, StreamChunk, SSE, ResponseGranularity: `references/streaming.md`
+   - Stream emitter for tool progress updates: `references/stream-emitter.md`
+   - Observability hooks, validators, and runtime jumps: `references/callbacks-and-command.md`
+   - Prebuilt agents (ReactAgent, PlanActReflectAgent, StructuredOutputAgent, SupervisorTeamAgent, SwarmAgent, RAGAgent) and tools: `references/prebuilt-agents-and-tools.md`
+   - Event publishers and A2A/ACP runtime protocols: `references/publishers-and-runtime-protocols.md`
+   - Context management, ID generation, and background tasks: `references/context-id-background.md`
+   - Provider internals and adapters: `references/providers-and-adapters.md`
+   - Prompt-injection and validation safety: `references/security-and-validators.md`
+   - Realtime audio-to-audio voice agents (AudioAgent, Gemini Live, `arealtime`, WebSocket bridge): `references/realtime.md`
+
+   ### API/CLI SDK
+   - CLI commands and generated project files: `references/cli-commands.md`
+   - `10xgraph.json` and dependency loading: `references/api-configuration.md`
+   - API auth and authorization: `references/auth-and-authorization.md`
+   - API environment, settings, and middleware: `references/api-settings-and-middleware.md`
+   - Rate limiting (config, backends, headers, custom backend): `references/rate-limiting.md`
+   - REST routes and error behavior: `references/rest-api-and-errors.md`
+   - API Snowflake IDs and thread naming: `references/id-and-thread-name-generators.md`
+   - API server and deployment runtime: `references/production-runtime.md`
+
+   ### TypeScript client SDK
+   - REST and TypeScript client surface: `references/api-client.md`
+   - Browser/client-side tool execution: `references/remote-tools.md`
+   - TypeScript auth helpers and structured errors: `references/client-auth-and-errors.md`
+   - TypeScript messages, invoke, and stream details: `references/client-messages-invoke-stream.md`
+   - TypeScript thread, memory, and file APIs: `references/client-threads-memory-files.md`
+
+   ### Testing and QA
+   - Unit testing without LLM calls (TestAgent, QuickTest, MockToolRegistry, `10xgraph test`): `references/unit-testing.md`
+   - Evaluation framework (EvalSet, criteria, AgentEvaluator, QuickEval, UserSimulator, `10xgraph eval`): `references/evaluation.md`
+   - Testing helpers overview: `references/testing-and-evaluation.md`
+
+3. Prefer existing 10xGraph abstractions over new custom wiring:
+   - Build workflows with `StateGraph`, `Agent`, `ToolNode`, `AgentState`, and `Message`.
+   - Use prebuilt agents (`ReactAgent`, `PlanActReflectAgent`, `StructuredOutputAgent`, `SupervisorTeamAgent`, `SwarmAgent`, `RAGAgent`) for common patterns before hand-writing graph loops.
+   - Persist conversation state with checkpointers; use stores only for cross-thread memory.
+   - Put business services in `InjectQ` instead of global variables.
+   - Keep API/CLI graph modules storage-agnostic and wire dependencies through `10xgraph.json`.
+
+4. Verify against source when implementation details matter. Public names and expected behavior should match https://10xgraph.com/; source under https://github.com/10xGraph/10xGraph (core), https://github.com/10xGraph/10xgraph-api (API/CLI), and https://github.com/10xHub/agentflow-client (TypeScript) explains how that behavior is implemented.
+
+## Local Conventions
+
+- A compiled graph is normally loaded once by the API server and reused per request.
+- Public package naming matters: use `10xgraph`, `10xgraph-api`, and `@10xscale/agentflow-client` in user-facing docs and examples, not repository folder names.
+- Every persisted interaction should include `config.thread_id`.
+- Tools need docstrings and type annotations so model-facing schemas are useful.
+- Injectable tool and node parameters (`state`, `config`, `tool_call_id`) are hidden from the model schema.
+- For production, avoid process-local storage for shared state; use durable checkpointer/store backends.
+- Add observability or audit side effects by registering a `GraphLifecycleHook` on `CallbackManager` — do not wrap `ainvoke()` / `astream()` calls in application code to achieve the same result.
+- `reasoning_config` is on by default at medium effort; disable explicitly with `reasoning_config=None` when not needed.
+- Provider is auto-detected from the model name; use `base_url` for third-party OpenAI-compatible APIs (Ollama, DeepSeek, OpenRouter).