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

tenxgraph_api/cli/templates/dev/.env.example

@@ -0,0 +1 @@
+GOOGLE_API_KEY=""

tenxgraph_api/cli/templates/dev/10xgraph.json

@@ -0,0 +1,16 @@
+{
+  "agent": "graph.agent:app",
+  "env": ".env",
+  "auth": null,
+  "remote_tools": [],
+  "ag_ui": {
+    "enabled": false
+  },
+  "thread_name_generator": null,
+  "evaluation": {
+    "directory": "evals",
+    "output_dir": "eval_reports",
+    "threshold": 0.75,
+    "timestamp_files": true
+  }
+}

tenxgraph_api/cli/templates/dev/graph/agent.py

@@ -0,0 +1,63 @@
+import logging
+from datetime import datetime
+
+from tenxgraph.core.state import AgentState, StreamEmitter
+from tenxgraph.prebuilt.agent import ReactAgent
+from tenxgraph.storage.checkpointer import InMemoryCheckpointer
+from dotenv import load_dotenv
+
+
+load_dotenv()
+
+checkpointer = InMemoryCheckpointer()
+
+logger = logging.getLogger(__name__)
+
+
+def call_weather_api(location: str) -> str:
+    return f"The weather in {location} is sunny"
+
+
+def get_weather(
+    location: str,
+    tool_call_id: str | None = None,
+    state: AgentState | None = None,
+    emit: StreamEmitter | None = None,
+) -> str:
+    """Get the current weather for a specific location."""
+    if tool_call_id:
+        logger.info(f"Tool call ID: {tool_call_id}")
+    if state and hasattr(state, "context"):
+        logger.info(f"Number of messages in context: {len(state.context)}")  # type: ignore
+
+    if emit:
+        emit.progress(f"Fetching weather for {location}")
+
+    return call_weather_api(location)
+
+
+react_agent = ReactAgent(
+    model="google/gemini-2.5-flash",
+    provider="google",
+    system_prompt=[
+        {
+            "role": "system",
+            "content": """
+                You are a helpful assistant.
+                Your task is to assist the user in finding information and answering questions.
+                Use tools when they help answer the user.
+            """,
+        },
+        {
+            "role": "user",
+            "content": f"Today Date is {datetime.now().strftime('%Y-%m-%d')}",
+        },  # Inject current date into system prompt
+    ],
+    trim_context=True,
+    tools=[get_weather],
+)
+
+
+app = react_agent.compile(
+    checkpointer=checkpointer,
+)

tenxgraph_api/cli/templates/prod/.env.example

@@ -0,0 +1,75 @@
+#################################
+###### App Config ###############
+#################################
+APP_NAME="$agent_name"
+APP_VERSION="0.1.0"
+MODE="production"
+LOG_LEVEL="INFO"
+IS_DEBUG="false"
+SUMMARY="$agent_name Backend"
+
+#################################
+###### CORS Config ##############
+#################################
+# TODO: In production, restrict origins and allowed hosts
+ORIGINS="*"
+ALLOWED_HOST="*"
+
+#################################
+###### Paths ####################
+#################################
+ROOT_PATH="/"
+# API docs (and /openapi.json) are served only when a path is set. Keep them off in
+# production; set e.g. DOCS_PATH="/docs" for a staging deployment.
+DOCS_PATH=""
+REDOCS_PATH=""
+
+#################################
+###### Request Limits ###########
+#################################
+MAX_REQUEST_SIZE=10485760  # 10MB
+
+#################################
+###### Security Headers #########
+#################################
+SECURITY_HEADERS_ENABLED="true"
+HSTS_ENABLED="true"
+HSTS_MAX_AGE=31536000
+HSTS_INCLUDE_SUBDOMAINS="true"
+HSTS_PRELOAD="false"
+FRAME_OPTIONS="DENY"
+CONTENT_TYPE_OPTIONS="nosniff"
+XSS_PROTECTION="1; mode=block"
+REFERRER_POLICY="strict-origin-when-cross-origin"
+
+#################################
+###### Snowflake ID Config ######
+#################################
+SNOWFLAKE_EPOCH=1609459200000
+SNOWFLAKE_NODE_ID=1
+SNOWFLAKE_WORKER_ID=2
+
+#################################
+###### Sentry Config ############
+#################################
+SENTRY_DSN=""
+
+##[IF_REDIS]##
+#################################
+###### Redis Config #############
+#################################
+REDIS_URL=""
+##[/IF_REDIS]##
+
+##[IF_JWT]##
+#################################
+###### JWT Config ###############
+#################################
+JWT_SECRET_KEY=""
+JWT_ALGORITHM="HS256"
+##[/IF_JWT]##
+
+#################################
+###### API Keys #################
+#################################
+GOOGLE_API_KEY=""

tenxgraph_api/cli/templates/prod/.pre-commit-config.yaml

@@ -0,0 +1,50 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v6.0.0
+  hooks:
+  - id: check-yaml
+    exclude: '^(tests|docs|examples)/'
+  - id: trailing-whitespace
+    exclude: '^(tests|docs|examples)/'
+  - id: check-added-large-files
+    args: ['--maxkb=100']
+    exclude: '^(tests|docs|examples)/'
+  - id: check-ast
+    exclude: '^(tests|docs|examples)/'
+  - id: check-builtin-literals
+    exclude: '^(tests|docs|examples)/'
+  - id: check-case-conflict
+    exclude: '^(tests|docs|examples)/'
+  - id: check-docstring-first
+    exclude: '^(tests|docs|examples)/'
+  - id: check-merge-conflict
+    exclude: '^(tests|docs|examples)/'
+  - id: debug-statements
+    exclude: '^(tests|docs|examples)/'
+  - id: detect-private-key
+    exclude: '^(tests|docs|examples)/'
+
+- repo: https://github.com/asottile/pyupgrade
+  rev: v3.17.0
+  hooks:
+  - id: pyupgrade
+    args: ['--py310-plus']
+    exclude: '^(tests|docs|examples)/'
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.5.7
+  hooks:
+  - id: ruff-format
+    exclude: '^(tests|docs|examples)/'
+  - id: ruff
+    args: ['--fix', '--exit-non-zero-on-fix']
+    exclude: '^(tests|docs|examples)/'
+
+- repo: https://github.com/PyCQA/bandit
+  rev: 1.7.9
+  hooks:
+  - id: bandit
+    args: ['-c', 'pyproject.toml']
+    additional_dependencies: ['bandit[toml]']
+    exclude: '^(tests|docs|examples)/'
+

tenxgraph_api/cli/templates/prod/.python-version

@@ -0,0 +1 @@
+3.13

tenxgraph_api/cli/templates/prod/10xgraph.json

@@ -0,0 +1,42 @@
+{
+  "agent": "graph.agent:app",
+  "env": ".env",
+  "auth": {
+    "method": "custom",
+    "path": "auth.agent_auth:AgentAuth"
+  },
+  "remote_tools": [],
+  "ag_ui": {
+    "enabled": false
+  },
+  "thread_name_generator": "graph.thread_name_generator:MyNameGenerator",
+  "injectq": "graph.agent:container",
+  "rate_limit": {
+    "enabled": true,
+    "backend": "redis",
+    "redis": {
+      "url": "${REDIS_URL}",
+      "prefix": "10xgraph:rate-limit"
+    },
+    "requests": 100,
+    "window": 60,
+    "by": "user",
+    "trusted_proxy_headers": true,
+    "trusted_proxy_hops": 1,
+    "fail_open": false,
+    "exclude_paths": ["/ping", "/docs", "/redoc", "/openapi.json"]
+  },
+  "test": {
+    "path": "tests",
+    "coverage": true,
+    "coverage_threshold": 70
+  },
+  "evaluation": {
+    "directory": "evals",
+    "output_dir": "eval_reports",
+    "threshold": 0.75,
+    "parallel": false,
+    "max_concurrency": 4,
+    "timestamp_files": true
+  }
+}

tenxgraph_api/cli/templates/prod/auth/agent_auth.py

@@ -0,0 +1,46 @@
+import logging
+from typing import Any
+
+from tenxgraph_api import BaseAuth
+from fastapi import HTTPException, Request, Response
+from fastapi.security import HTTPAuthorizationCredentials
+
+
+logger = logging.getLogger(__name__)
+
+
+class AgentAuth(BaseAuth):
+    """Verify the caller and return who they are.
+
+    Every request is denied with 401 until ``authenticate`` checks a real credential.
+
+    Contract:
+    - Return a dict with at least ``user_id``. It becomes the thread and memory owner, so it
+      must come from the verified credential, never from a header or body field the client
+      sets. Optional ``roles`` / ``scopes`` feed the authorization backend.
+    - Raise ``HTTPException(status_code=401)`` for a missing, invalid or expired credential.
+    """
+
+    def __init__(self) -> None:
+        logger.warning(
+            "AgentAuth.authenticate is not implemented yet: every request will get 401. "
+            "Implement it in auth/agent_auth.py."
+        )
+
+    def authenticate(
+        self,
+        request: Request,
+        response: Response,
+        credential: HTTPAuthorizationCredentials,
+    ) -> dict[str, Any] | None:
+        if credential is None:
+            raise HTTPException(status_code=401, detail="Missing credentials")
+
+        # Replace this with a real check, for example verifying the bearer token with your
+        # identity provider:
+        #
+        #     claims = verify_token(credential.credentials)  # raises on a bad token
+        #     return {"user_id": claims["sub"], "roles": claims.get("roles", [])}
+        #
+        # Remove the warning in __init__ once this is done.
+        raise HTTPException(status_code=401, detail="Authentication is not configured")

tenxgraph_api/cli/templates/prod/evals/user_simulator_eval.py

@@ -0,0 +1,76 @@
+"""
+User simulator evaluation example.
+
+The CLI detects get_scenarios() and handles everything:
+  - runs each scenario through UserSimulator
+  - scores goal achievement with an LLM judge
+  - produces the same HTML + JSON report as regular eval cases
+
+You only need to define your scenarios. No asyncio, no EvalSetBuilder, no boilerplate.
+
+Usage:
+    10xgraph eval evals/user_simulator_eval.py
+    10xgraph eval evals/user_simulator_eval.py --parallel --max-concurrency 4
+"""
+
+from tenxgraph.qa.evaluation import ConversationScenario, UserSimulatorConfig
+
+# ---------------------------------------------------------------------------
+# Agent — the CLI reads `app` from this module if present, otherwise it loads
+# the graph from 10xgraph.json ("agent": "graph.agent:app") automatically.
+# Uncomment and set this if you want to target a specific graph:
+#
+#   from graph.agent import app
+# ---------------------------------------------------------------------------
+
+
+# ---------------------------------------------------------------------------
+# Optional: override the simulator model and settings for this file.
+# If omitted, the CLI uses UserSimulatorConfig defaults (gemini-2.5-flash).
+# ---------------------------------------------------------------------------
+SIMULATOR_CONFIG = UserSimulatorConfig(
+    model="gemini/gemini-2.5-flash",
+    max_invocations=8,
+    temperature=0.7,
+)
+
+
+# ---------------------------------------------------------------------------
+# Scenarios — the only thing you need to write.
+# ---------------------------------------------------------------------------
+
+def get_scenarios() -> list[ConversationScenario]:
+    return [
+        ConversationScenario(
+            scenario_id="weather_travel_planning",
+            description="User planning a trip wants weather info and packing advice",
+            starting_prompt="Hi! I'm planning a trip to Paris this weekend.",
+            conversation_plan=(
+                "1. Ask about current weather in Paris\n"
+                "2. Ask whether to bring a jacket\n"
+                "3. Ask about the best time for outdoor sightseeing"
+            ),
+            goals=[
+                "User receives weather information for Paris",
+                "User gets clothing or packing advice",
+                "User learns about outdoor activity timing",
+            ],
+            max_turns=8,
+        ),
+        ConversationScenario(
+            scenario_id="flight_booking_assistance",
+            description="User wants help finding a flight from London to New York",
+            starting_prompt="I need to fly from London to New York next Friday. Can you help?",
+            conversation_plan=(
+                "1. Share travel dates and seat preferences\n"
+                "2. Ask about available flights and prices\n"
+                "3. Confirm booking details"
+            ),
+            goals=[
+                "User receives flight options for the requested route",
+                "User gets pricing information",
+                "Booking process is initiated or completed",
+            ],
+            max_turns=10,
+        ),
+    ]

tenxgraph_api/cli/templates/prod/evals/weather_agents_eval.py

@@ -0,0 +1,53 @@
+from tenxgraph.qa.evaluation import EvalConfig, EvalSet, EvalSetBuilder
+from tenxgraph.qa.evaluation.config.presets import EvalPresets
+
+
+def get_eval_config() -> EvalConfig:
+    """Evaluation config for this file.
+
+    EvalPresets provides ready-made criterion bundles.  Pick one that matches
+    what your agent does, or call EvalPresets.combine() to mix them.
+
+    Available presets:
+        EvalPresets.response_quality()   — LLM judge on response accuracy
+        EvalPresets.tool_usage()         — checks tool calls + response quality
+        EvalPresets.conversation_flow()  — multi-turn conversation evaluation
+        EvalPresets.comprehensive()      — all of the above combined
+        EvalPresets.quick_check()        — fast ROUGE-based check, no LLM cost
+    """
+    return EvalPresets.tool_usage(threshold=0.6)
+
+
+def get_eval_set() -> EvalSet:
+    return (
+        EvalSetBuilder(name="weather-agent-regression")
+        .add_case(
+            query="Hi",
+            expected="assistant",
+            expected_node_order=["MAIN"],
+            name="greeting_response",
+            description="The agent responds to a greeting.",
+        )
+        .add_tool_test(
+            query="What is the weather in London?",
+            tool_name="get_weather",
+            tool_args={"location": "London"},
+            expected_response="London",
+            case_id="weather_london",
+        )
+        .add_tool_test(
+            query="Tell me the current weather in New York",
+            tool_name="get_weather",
+            tool_args={"location": "New York"},
+            expected_response="New York",
+            case_id="weather_new_york",
+        )
+        .add_tool_test(
+            query="How is the weather in Tokyo today?",
+            tool_name="get_weather",
+            tool_args={"location": "Tokyo"},
+            expected_response="Tokyo",
+            case_id="weather_tokyo",
+        )
+        .build()
+    )

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

@@ -0,0 +1,50 @@
+from datetime import datetime
+
+from tenxgraph.core.state import MessageContextManager
+from tenxgraph.prebuilt.agent import ReactAgent
+from tenxgraph.storage.checkpointer import InMemoryCheckpointer
+from dotenv import load_dotenv
+
+from graph.state import WeatherState
+from graph.tools.weather_tool import get_weather
+from graph.validators.manager import callback_manager
+
+
+load_dotenv()
+
+checkpointer = InMemoryCheckpointer()
+
+context_manager = MessageContextManager(
+    max_messages=20,  # last 20 user messages will be kept in context
+    remove_tool_msgs=True,
+)
+
+react_agent = ReactAgent(
+    state=WeatherState(),
+    model="google/gemini-2.5-flash",
+    provider="google",
+    system_prompt=[
+        {
+            "role": "system",
+            "content": """
+                You are a helpful assistant.
+                Your task is to assist the user in finding information and answering questions.
+                User Current Location: {user_location}
+                If missing information, ask the user for clarification.
+                Use tools when they help answer the user.
+            """,
+        },
+        {
+            "role": "user",
+            "content": f"Today Date is {datetime.now().strftime('%Y-%m-%d')}",
+        },
+    ],
+    trim_context=True,
+    tools=[get_weather],
+    context_manager=context_manager,
+)
+
+app = react_agent.compile(
+    checkpointer=checkpointer,
+    callback_manager=callback_manager,
+)

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

@@ -0,0 +1,5 @@
+from tenxgraph.core import AgentState
+
+
+class WeatherState(AgentState):
+    user_location: str = ""

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

@@ -0,0 +1,7 @@
+from tenxgraph_api import ThreadNameGenerator
+
+
+class MyNameGenerator(ThreadNameGenerator):
+    async def generate_name(self, messages: list[str]) -> str:
+        # TODO: Implement logic to generate thread name based on messages
+        return "MyCustomThreadName"

tenxgraph_api/cli/templates/prod/graph/tools/weather_tool.py

@@ -0,0 +1,43 @@
+import logging
+import random
+
+from tenxgraph.core.state.stream_emitter import StreamEmitter
+
+from graph.state import WeatherState
+
+
+logger = logging.getLogger(__name__)
+
+MAX_RETRIES = 3
+
+
+def call_weather_api(location: str) -> str:
+    is_failed = random.choice([True, False])  # noqa: S311
+    if is_failed:
+        raise Exception("Failed to fetch weather data due to a simulated API error.")
+    return f"The weather in {location} is sunny"
+
+
+def get_weather(
+    location: str,
+    tool_call_id: str | None = None,
+    state: WeatherState | None = None,
+    emit: StreamEmitter | None = None,
+) -> str:
+    """Get the current weather for a specific location."""
+    if tool_call_id:
+        logger.info(f"Tool call ID: {tool_call_id}")
+    if state and hasattr(state, "context"):
+        logger.info(f"Number of messages in context: {len(state.context)}")  # type: ignore
+    if emit:
+        emit.progress("Fetching weather data...")
+
+    for i in range(MAX_RETRIES):
+        try:
+            return call_weather_api(location)
+        except Exception as e:
+            logger.error(f"Attempt {i + 1} failed: {e}")
+            if emit:
+                emit.progress(f"Attempt {i + 1} failed, retrying...")
+
+    return f"Sorry, I couldn't fetch the weather for {location} after multiple attempts."

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

@@ -0,0 +1,107 @@
+"""Lifecycle hooks for the weather agent graph."""
+
+import logging
+from typing import Any
+
+from tenxgraph.core.state.message import Message
+from tenxgraph.utils.callbacks import GraphLifecycleContext, GraphLifecycleHook
+
+from graph.state import WeatherState
+
+
+logger = logging.getLogger(__name__)
+
+
+class AgentLifecycleHook(GraphLifecycleHook[WeatherState]):
+    async def on_graph_start(
+        self,
+        context: GraphLifecycleContext,
+        state: WeatherState,
+    ) -> WeatherState | None:
+        """Hydrate ``WeatherState`` from the org config attached by AgentAuth."""
+        return state
+
+    async def on_graph_end(
+        self,
+        context: GraphLifecycleContext,
+        final_state: WeatherState,
+        messages: list[Message],
+        total_steps: int,
+    ) -> WeatherState | None:
+        """Called after successful graph completion, before final state sync.
+
+        Return a modified WeatherState to persist, or None to keep the current state.
+        """
+        return None
+
+    async def on_graph_error(  # noqa: PLR0913
+        self,
+        context: GraphLifecycleContext,
+        error: Exception,
+        partial_state: WeatherState,
+        messages: list[Message],
+        step: int,
+        node_name: str,
+    ) -> tuple[WeatherState, str] | None:
+        """Called when an unhandled error escapes the execution loop.
+
+        Return (modified_state, error_message) to change the persisted error snapshot,
+        or None to keep the current error state. The exception is always re-raised.
+        """
+        return None
+
+    async def on_interrupt(
+        self,
+        context: GraphLifecycleContext,
+        interrupted_node: str,
+        interrupt_type: str,
+        state: WeatherState,
+    ) -> WeatherState | None:
+        """Called when execution pauses at an interrupt point.
+
+        Return a modified WeatherState to persist at interrupt, or None to keep the current state.
+        In-place mutation of the passed state is also supported.
+        """
+        return None
+
+    async def on_resume(
+        self,
+        context: GraphLifecycleContext,
+        resumed_node: str,
+        state: WeatherState,
+        resume_data: dict[str, Any],
+    ) -> WeatherState | None:
+        """Called when a previously interrupted execution is about to resume.
+
+        Called before clear_interrupt(). Return a modified WeatherState to continue with,
+        or None to use the loaded state unchanged.
+        """
+        return None
+
+    async def on_checkpoint(
+        self,
+        context: GraphLifecycleContext,
+        state: WeatherState,
+        messages: list[Message],
+        is_context_trimmed: bool,
+    ) -> tuple[WeatherState, list[Message]] | WeatherState | None:
+        """Called before every durable checkpoint write.
+
+        Return (state, messages) to modify both, WeatherState to modify state only,
+        or None to persist without modification.
+        """
+        return None
+
+    async def on_state_update(
+        self,
+        context: GraphLifecycleContext,
+        node_name: str,
+        old_state: WeatherState,
+        new_state: WeatherState,
+        step: int,
+    ) -> WeatherState | None:
+        """Called after each node's result is merged into state.
+
+        Return a modified WeatherState to replace new_state, or None to use new_state unchanged.
+        """
+        return None

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

@@ -0,0 +1,9 @@
+from tenxgraph.utils.callbacks import CallbackManager
+
+from .lifecyle import AgentLifecycleHook
+from .validators import prompt_validator
+
+
+callback_manager = CallbackManager()
+callback_manager.register_input_validator(prompt_validator)
+callback_manager.register_lifecycle_hook(AgentLifecycleHook())