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

tenxgraph_api/cli/templates/skills/copilot/10xgraph.instructions.md

@@ -0,0 +1,108 @@
+---
+applyTo: "**"
+---
+
+# 10xGraph project instructions
+
+This repo uses **10xGraph** — a multi-agent framework that wraps the official OpenAI and Google SDKs behind a unified graph, agent, tool, state, storage, API, CLI, and TypeScript-client interface.
+
+When generating, refactoring, or debugging code in this repo, prefer 10xGraph's own abstractions over hand-rolled equivalents.
+
+## Public package names (use these in user-facing examples)
+
+- Python core SDK: `10xgraph` — `pip install 10xgraph` — source under `tenxgraph/` in https://github.com/10xGraph/10xGraph
+- Python API/CLI SDK: `10xgraph-api` — `pip install 10xgraph-api` — source under `tenxgraph_api/` in https://github.com/10xGraph/10xgraph-api
+- TypeScript SDK: `@10xscale/agentflow-client` — `npm install @10xscale/agentflow-client` — source under `agentflow-client/src`
+- Docs: https://10xgraph.com/ (source of truth for public API names)
+- Playground: `10xgraph play` (after the CLI is installed)
+
+Never use repository folder names (e.g. `10xgraph-api`) in install commands or user-facing docs — use the published package names above.
+
+## Architecture overview
+
+Three published packages, one request flow:
+
+1. `@10xscale/agentflow-client` or another HTTP caller sends messages with `config.thread_id`.
+2. FastAPI (`10xgraph-api`) receives the request through auth and routers.
+3. `GraphService` invokes or streams against the compiled graph loaded at startup.
+4. The compiled graph loads state through the checkpointer when a `thread_id` exists.
+5. Graph nodes run and update `AgentState`.
+6. Checkpointer saves state, messages, and thread metadata.
+7. API returns JSON or SSE chunks to the caller.
+
+Compile graphs once at startup. Keep graph code storage-agnostic; wire dependencies through compile arguments, `InjectQ`, or `10xgraph.json`.
+
+## Core abstractions to reach for
+
+- Build workflows with `StateGraph`, `Agent`, `ToolNode`, `AgentState`, and `Message`.
+- **Use prebuilt agents for common patterns before hand-writing graph loops:**
+  - `ReactAgent` — standard tool-calling loop (use by default)
+  - `PlanActReflectAgent` — plan → act → reflect loop for complex multi-step tasks
+  - `StructuredOutputAgent` — forces JSON output matching a Pydantic schema
+  - `SupervisorTeamAgent` — central supervisor routes to specialist worker agents
+  - `SwarmAgent` — peer-to-peer agent handoff without a central supervisor
+  - `RAGAgent` — retrieves documents from a vector store before each LLM call
+  - `AudioAgent` — realtime full-duplex voice agent (Gemini Live); needs the `[realtime]` extra and is driven by `arealtime()`, not `invoke`/`stream`
+- Persist conversation state with **checkpointers**. Use **stores** only for cross-thread memory.
+- Inject business services through **`InjectQ`**, not module-level globals.
+- Keep API/CLI graph modules storage-agnostic; wire dependencies via `10xgraph.json`.
+- Every persisted interaction must include `config.thread_id`.
+- Tools need docstrings and type annotations so model-facing schemas are useful.
+- Injectable 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, audit, or business-logic side effects by registering a `GraphLifecycleHook` on `CallbackManager` — do not wrap `ainvoke()` / `astream()` calls in application code to achieve the same result.
+
+## Agent configuration quick reference
+
+```python
+Agent(
+    model="gpt-4o",                             # required; provider auto-detected
+    provider="openai",                          # explicit or omit for auto-detect
+    base_url="http://localhost:11434/v1",       # for Ollama / DeepSeek / OpenRouter
+    output_type="text",                         # "text" | "image" | "video" | "audio"
+    output_schema=MyPydanticModel,              # force structured JSON output
+    system_prompt=[{"role": "system", "content": "Help {user_name}."}],  # state interpolation
+    tool_node=tool_node,                        # ToolNode instance or graph node name string
+    tools_tags={"search"},                      # expose only matching-tagged tools
+    extra_messages=[...],                       # injected after system_prompt every call
+    trim_context=True,                          # trim old messages to fit token limits
+    reasoning_config={"effort": "medium"},      # on by default; None to disable
+    retry_config=True,                          # default 3 retries with backoff
+    fallback_models=["gpt-4o-mini"],            # tried in order after retries exhausted
+    memory=MemoryConfig(...),                   # long-term memory store wiring
+    skills=SkillConfig(...),                    # skills discovery and exposure
+    api_style="chat",                           # "chat" | "responses" (OpenAI only)
+)
+```
+
+## Key configuration (`10xgraph.json`)
+
+```json
+{
+  "agent": "graph.agent:app",
+  "env": ".env",
+  "auth": null,
+  "checkpointer": null,
+  "injectq": null,
+  "store": null,
+  "redis": null,
+  "thread_name_generator": null
+}
+```
+
+Set `"auth": {"method": "jwt"}` and `JWT_SECRET_KEY` in `.env` to enable JWT authentication.
+
+## Important conventions
+
+- A compiled graph is loaded once at API startup and reused per request.
+- `thread_id` is the continuity key for conversation state — always pass it for persisted interactions.
+- Auth and request permissions belong in API middleware/routers, not inside graph nodes.
+- Long-term memory store records are cross-thread knowledge, not thread history.
+- Rate limiting config lives in `10xgraph.json` under `"rate_limit"`: backend options are `"memory"` or `"redis"`.
+- `reasoning_config` is on by default — disable explicitly with `reasoning_config=None` when not needed.
+
+## Verifying behavior
+
+Public names and behavior should match `agentflow-docs/docs` or https://10xgraph.com/. Implementation in the `10xgraph` and `10xgraph-api` repos and `agentflow-client/src/` shows *how* — only consult source after docs establish *what*.
+
+That file points Copilot at the installed skill bundle under `.github/skills/10xgraph/`.

tenxgraph_api/src/app/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2021 Shudipto Trafder
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

tenxgraph_api/src/app/core/__init__.py

@@ -0,0 +1,15 @@
+from .config.settings import LOGGER_NAME, Settings, get_settings, logger
+from .config.setup_logs import init_logger
+from .config.setup_middleware import setup_middleware
+from .exceptions.handle_errors import init_errors_handler
+
+
+__all__ = [
+    "LOGGER_NAME",
+    "Settings",
+    "get_settings",
+    "init_errors_handler",
+    "init_logger",
+    "logger",
+    "setup_middleware",
+]

tenxgraph_api/src/app/core/auth/auth_backend.py

@@ -0,0 +1,38 @@
+from typing import Any
+
+from fastapi import Depends, Request, Response
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from injectq.integrations import InjectAPI
+
+from tenxgraph_api.src.app.core import logger
+from tenxgraph_api.src.app.core.auth.base_auth import BaseAuth
+from tenxgraph_api.src.app.core.config.graph_config import GraphConfig
+
+
+def verify_current_user(
+    request: Request,
+    response: Response,
+    credential: HTTPAuthorizationCredentials = Depends(
+        HTTPBearer(auto_error=False),
+    ),
+    config: GraphConfig = InjectAPI(GraphConfig),
+    auth_backend: BaseAuth = InjectAPI(BaseAuth),
+) -> dict[str, Any]:
+    # check auth backend
+    user = {}
+    backend = config.auth_config()
+    if not backend:
+        return user
+
+    if not auth_backend:
+        logger.error("Auth backend is not configured")
+        return user
+
+    user: dict | None = auth_backend.authenticate(
+        request,
+        response,
+        credential,
+    )
+    if user and "user_id" not in user:
+        logger.error("Authentication failed: 'user_id' not found in user info")
+    return user or {}

tenxgraph_api/src/app/core/auth/authorization.py

@@ -0,0 +1,379 @@
+"""
+Authorization backend system for 10xGraph CLI.
+
+This module provides an authorization interface that developers can implement
+to add resource-level access control to their 10xGraph applications.
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+logger = logging.getLogger("tenxgraph_api.authorization")
+
+# The /v1/store routes require these. Core releases up to 0.9.1 named them "memory:*", so a
+# "*" role would never reach the memory routes; they are added here until core is bumped.
+STORE_SCOPES = frozenset({"store:read", "store:write", "store:delete"})
+LEGACY_MEMORY_SCOPES = frozenset({"memory:read", "memory:write", "memory:delete"})
+
+
+def all_scopes() -> frozenset[str]:
+    """Every scope the API can require, which is what a ``"*"`` role is granted."""
+    from tenxgraph.core.authz import ALL_SCOPES
+
+    return (frozenset(ALL_SCOPES) - LEGACY_MEMORY_SCOPES) | STORE_SCOPES
+
+
+class AuthorizationBackend(ABC):
+    """
+    Abstract base class for authorization backends.
+
+    Developers should implement this class to define custom authorization logic
+    for their 10xGraph applications. The authorize method is called before
+    any resource operation to check if the user has permission.
+
+    Example:
+        class MyAuthorizationBackend(AuthorizationBackend):
+            async def authorize(self, user, resource, action, resource_id=None, **context):
+                # Check if user has permission
+                if user.get("role") == "admin":
+                    return True
+                # Add custom logic here
+                return False
+    """
+
+    @abstractmethod
+    async def authorize(
+        self,
+        user: dict[str, Any],
+        resource: str,
+        action: str,
+        resource_id: str | None = None,
+        **context: Any,
+    ) -> bool:
+        """
+        Check if user can perform action on resource.
+
+        Args:
+            user: User information dictionary containing at least 'user_id'
+            resource: Resource type (e.g., 'graph', 'checkpointer', 'store')
+            action: Action to perform (e.g., 'invoke', 'stream', 'read', 'write', 'delete')
+            resource_id: Optional specific resource identifier (e.g., thread_id, namespace)
+            **context: Additional context for authorization decision
+
+        Returns:
+            bool: True if authorized, False otherwise
+
+        Raises:
+            Exception: Can raise exceptions for auth failures or errors
+        """
+
+    def isolation_scope(self) -> str:
+        """The data-isolation policy this backend implies, sent to storage per request.
+
+        The API stamps this (server-side, non-hijackable) into ``config["policy"]`` so the
+        checkpointer scopes storage the *same* way this backend decides access -- no
+        contradiction between "allow_all" authz and a data layer that still filters.
+
+        - ``"owner"`` -> storage is scoped to the caller's ``user_id`` (owner-only).
+        - ``"none"``  -> storage is not scoped (any authenticated user sees everything).
+
+        Defaults to ``"none"``. Override (or return ``"owner"``) to make a custom backend
+        drive per-user storage isolation too.
+        """
+        return "none"
+
+    def scopes_for(self, user: dict[str, Any]) -> list[str] | None:
+        """Return the scopes this identity is granted, or None for "unrestricted".
+
+        ``RequirePermission`` checks the required ``"<resource>:<action>"`` scope against
+        this list. Returning ``None`` means the identity is not scope-restricted
+        (permissive -- the default, so nothing breaks until scopes are issued).
+
+        The default passes through scopes the identity already carries
+        (``user["scopes"]``, e.g. from a JWT ``scope`` claim). A role-based backend
+        overrides this to map ``user["roles"]`` to scopes.
+        """
+        scopes = user.get("scopes") if isinstance(user, dict) else None
+        if isinstance(scopes, list | tuple | set | frozenset):
+            return list(scopes)
+        return None
+
+
+class DefaultAuthorizationBackend(AuthorizationBackend):
+    """
+    Default authorization backend that allows all authenticated users.
+
+    This implementation performs basic authentication check (user has user_id)
+    but allows all operations. Use this as a starting point or for development.
+
+    For production use, implement a custom AuthorizationBackend with proper
+    access control logic based on your application's requirements.
+    """
+
+    async def authorize(
+        self,
+        user: dict[str, Any],
+        resource: str,
+        action: str,
+        resource_id: str | None = None,
+        **context: Any,
+    ) -> bool:
+        """
+        Allow all authenticated users to perform any action.
+
+        Args:
+            user: User information dictionary
+            resource: Resource type (not used in default implementation)
+            action: Action to perform (not used in default implementation)
+            resource_id: Optional resource identifier (not used in default implementation)
+            **context: Additional context (not used in default implementation)
+
+        Returns:
+            bool: True if user has 'user_id', False otherwise
+        """
+        # Only check if user is authenticated (has user_id)
+        return bool(user.get("user_id"))
+
+
+class OwnershipAuthorizationBackend(AuthorizationBackend):
+    """Object-level authorization: a user may only touch threads they own.
+
+    This is the built-in "secure" backend. It enforces the rule most multi-tenant
+    apps want without the developer writing any code: *a thread can be read, mutated,
+    stopped or fixed only by the user who owns it.* Ownership is resolved from the
+    configured checkpointer, whose thread registry records the owning ``user_id``.
+
+    Decision table (for the thread-scoped resources ``graph`` and ``checkpointer``):
+
+    - No ``user_id`` on the request -> deny (must be authenticated).
+    - No ``resource_id`` (list / create-without-id, e.g. ``GET /v1/threads``, the graph
+      schema endpoint) -> allow; those paths are already user-scoped by the service.
+    - The thread does not exist yet -> allow (a brand-new session / empty read). For
+      ``invoke``/``stream`` this starts a new thread owned by the caller.
+    - The thread exists and the caller owns it -> allow.
+    - The thread exists and is owned by someone else -> **deny, for every action**
+      including ``invoke`` and ``stream``. This is the whole point: you cannot read,
+      continue, stop, fix, or run another user's thread.
+
+    Resources other than ``graph``/``checkpointer`` (store, files) are allowed through:
+    they enforce their own per-user scoping (the store keys on ``user_id``; media checks
+    file ownership in ``MediaService``).
+
+    Ownership is resolved through a :class:`ThreadOwnershipResolver` in front of
+    :meth:`BaseCheckpointer.aget_thread_owner`. Ownership is immutable, so the resolver
+    caches it (in-process, plus optional shared Redis) -- after the first lookup a check is
+    an in-memory hit, not a database round-trip per request. A checkpointer that cannot
+    resolve ownership (raises ``NotImplementedError``) or that is not configured leaves
+    nothing to enforce, so requests pass through with a warning. The in-memory checkpointer
+    only records a thread when one is explicitly written, which is why this backend is the
+    production default (Postgres) while development defaults to
+    :class:`DefaultAuthorizationBackend`.
+    """
+
+    # Resources whose ``resource_id`` is a thread_id and therefore ownership-checkable.
+    THREAD_RESOURCES = frozenset({"graph", "checkpointer"})
+
+    def isolation_scope(self) -> str:
+        # Owner-only access -> storage must be scoped to the caller too.
+        return "owner"
+
+    def __init__(
+        self,
+        checkpointer: Any | None = None,
+        *,
+        resolver: Any | None = None,
+        redis: object | None = None,
+    ) -> None:
+        self._checkpointer = checkpointer
+        self._resolver = resolver
+        self._redis = redis
+        self._resolver_built = resolver is not None
+
+    @property
+    def checkpointer(self) -> Any | None:
+        """Resolve the checkpointer lazily from the DI container if not injected."""
+        if self._checkpointer is None:
+            try:
+                from injectq import InjectQ
+                from tenxgraph.storage.checkpointer import BaseCheckpointer
+
+                self._checkpointer = InjectQ.get_instance().try_get(BaseCheckpointer)
+            except Exception:  # pragma: no cover - defensive
+                self._checkpointer = None
+        return self._checkpointer
+
+    def _get_resolver(self) -> Any | None:
+        """Return the cached ownership resolver, building it once from the checkpointer.
+
+        Returns None when no checkpointer is available (nothing to resolve).
+        """
+        if self._resolver_built:
+            return self._resolver
+        self._resolver_built = True
+        cp = self.checkpointer
+        if cp is None:
+            self._resolver = None
+        else:
+            from tenxgraph_api.src.app.core.auth.ownership_resolver import (
+                ThreadOwnershipResolver,
+            )
+
+            self._resolver = ThreadOwnershipResolver(cp.aget_thread_owner, redis=self._redis)
+        return self._resolver
+
+    def evict(self, thread_id: str | int) -> Any:
+        """Invalidate a thread's cached ownership (call on thread deletion).
+
+        Returns the resolver's ``evict`` coroutine when a resolver exists, so callers may
+        ``await`` it; returns None when there is nothing to evict.
+        """
+        resolver = self._get_resolver()
+        if resolver is None:
+            return None
+        return resolver.evict(thread_id)
+
+    async def aclose(self) -> None:
+        """Close the L2 Redis client this backend created (called on app shutdown)."""
+        client = self._redis
+        if client is not None and hasattr(client, "aclose"):
+            try:
+                await client.aclose()
+            except Exception as exc:  # pragma: no cover - best-effort shutdown
+                logger.debug("Ownership Redis client close failed: %s", exc)
+
+    async def authorize(
+        self,
+        user: dict[str, Any],
+        resource: str,
+        action: str,
+        resource_id: str | None = None,
+        **context: Any,
+    ) -> bool:
+        user_id = user.get("user_id") if user else None
+        if not user_id:
+            return False
+
+        # Only thread-scoped resources are ownership-checked here.
+        if resource not in self.THREAD_RESOURCES:
+            return True
+
+        # Endpoints without a specific thread (list/create) are user-scoped by the
+        # service layer; nothing to authorize at the object level.
+        if resource_id is None:
+            return True
+
+        resolver = self._get_resolver()
+        if resolver is None:
+            logger.warning(
+                "Ownership authorization is active but no checkpointer is configured; "
+                "allowing %s:%s (no persisted threads to protect).",
+                resource,
+                action,
+            )
+            return True
+
+        return await self._authorize_ownership(
+            resolver, str(resource_id), str(user_id), resource, action
+        )
+
+    async def _authorize_ownership(
+        self,
+        resolver: Any,
+        resource_id: str,
+        user_id: str,
+        resource: str,
+        action: str,
+    ) -> bool:
+        try:
+            owner = await resolver.owner_of(resource_id)
+        except NotImplementedError:
+            logger.warning(
+                "Checkpointer %s cannot resolve thread ownership; ownership "
+                "authorization is inactive for %s:%s. Use a checkpointer that "
+                "implements aget_thread_owner (e.g. PgCheckpointer) or configure a "
+                "custom AuthorizationBackend.",
+                type(self.checkpointer).__name__,
+                resource,
+                action,
+            )
+            return True
+        except Exception as exc:
+            # Fail closed: a resolution error must not silently grant access.
+            logger.warning(
+                "Ownership check failed for thread %s (user %s): %s; denying.",
+                resource_id,
+                user_id,
+                exc,
+            )
+            return False
+
+        # Unknown thread -> brand-new session (or an empty read); allow. Otherwise the
+        # caller must be the owner, for EVERY action (invoke/stream included).
+        if owner is None:
+            return True
+        return str(owner) == user_id
+
+
+class RoleBasedAuthorizationBackend(OwnershipAuthorizationBackend):
+    """RBAC: map a user's roles to scopes, on top of owner-only object isolation.
+
+    Combines two things in one backend:
+
+    - **Scopes** (what actions are allowed) -- ``scopes_for`` maps ``user["roles"]`` (or
+      ``user["role"]``) to a set of scopes via the ``role_scopes`` table. ``RequirePermission``
+      then enforces the required ``"<resource>:<action>"`` scope. A role granting ``"*"``
+      gets every scope in :func:`all_scopes`.
+    - **Isolation** (which rows are visible) -- inherited from
+      :class:`OwnershipAuthorizationBackend` (owner-only threads), configurable via
+      ``isolation``.
+
+    Example::
+
+        RoleBasedAuthorizationBackend(
+            role_scopes={
+                "admin": ["*"],
+                "member": ["graph:invoke", "graph:stream", "checkpointer:read"],
+            },
+            default_scopes=["graph:read"],  # granted to everyone, even with no role
+        )
+    """
+
+    def __init__(
+        self,
+        role_scopes: dict[str, Any] | None = None,
+        *,
+        default_scopes: Any = (),
+        isolation: str = "owner",
+        checkpointer: Any | None = None,
+        resolver: Any | None = None,
+        redis: object | None = None,
+    ) -> None:
+        super().__init__(checkpointer=checkpointer, resolver=resolver, redis=redis)
+        self._role_scopes = {str(r): list(s) for r, s in (role_scopes or {}).items()}
+        self._default_scopes = list(default_scopes)
+        self._isolation = isolation if isolation in ("owner", "none") else "owner"
+
+    def isolation_scope(self) -> str:
+        return self._isolation
+
+    @staticmethod
+    def _roles_of(user: dict[str, Any]) -> list[str]:
+        if not isinstance(user, dict):
+            return []
+        roles = user.get("roles")
+        if roles is None:
+            role = user.get("role")
+            roles = [role] if role else []
+        elif isinstance(roles, str):
+            roles = [roles]
+        return [str(r) for r in roles]
+
+    def scopes_for(self, user: dict[str, Any]) -> list[str]:
+        granted: set[str] = set(self._default_scopes)
+        for role in self._roles_of(user):
+            granted.update(self._role_scopes.get(role, []))
+        if "*" in granted:
+            return sorted(all_scopes())
+        return sorted(granted)

tenxgraph_api/src/app/core/auth/base_auth.py

@@ -0,0 +1,27 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from fastapi import Request, Response
+from fastapi.security import HTTPAuthorizationCredentials
+
+
+class BaseAuth(ABC):
+    @abstractmethod
+    def authenticate(
+        self,
+        request: Request,
+        response: Response,
+        credential: HTTPAuthorizationCredentials,
+    ) -> dict[str, Any] | None:
+        """Authenticate the user based on the provided credentials.
+        IT should return an empty dict if no authentication is required.
+        If authentication fails, it should raise an appropriate exception.
+        In case authentication is successful, it should return a dict with user information,
+        containing at least a 'user_id' key, and optionally other user details.
+        Example:
+            return {"user_id": "12345", "username": "johndoe", "email": "johndoe@example.com"}
+
+        What ever keys are returned that will be merged with config in the main graph app.
+        """
+
+        raise NotImplementedError