sectum-ai-adapters 0.1.1__tar.gz

sectum_ai_adapters-0.1.1/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+
+# Builds / distributions
+build/
+dist/
+*.whl
+
+# mkdocs build output
+site/
+
+# uv / virtual environments
+.venv/
+venv/
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Example run artifacts (generated by examples/*/run.sh, incl. the
+# out-residual/ workdir from the docs/samples regeneration recipe)
+examples/*/out/
+examples/*/out-residual/
+
+# Sectum CLI default workdir (generated by seed/probe/report; not source)
+.sectum-ai/
+examples/*/.sectum-ai/
+
+# Project-local engineering spec (not shared)
+CLAUDE.md

sectum_ai_adapters-0.1.1/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: sectum-ai-adapters
+Version: 0.1.1
+Summary: Sectum AI - adapters connecting the substrate and probes to real systems.
+Project-URL: Homepage, https://sectum.ai
+Project-URL: Repository, https://github.com/sectum-ai/sectum-ai
+Author: Sectum AI
+License-Expression: Apache-2.0
+Keywords: adapters,ai-security,multi-tenant,verification
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.9
+Requires-Dist: sectum-ai-spec
+Provides-Extra: anthropic-tooluse
+Requires-Dist: anthropic>=0.40; extra == 'anthropic-tooluse'
+Provides-Extra: autogen
+Requires-Dist: pyautogen<0.3,>=0.2; extra == 'autogen'
+Provides-Extra: azure-search
+Requires-Dist: azure-core>=1.30; extra == 'azure-search'
+Requires-Dist: azure-search-documents>=11.4; extra == 'azure-search'
+Provides-Extra: chroma
+Requires-Dist: chromadb-client>=0.5; extra == 'chroma'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.80; extra == 'crewai'
+Provides-Extra: huggingface
+Requires-Dist: accelerate>=1; extra == 'huggingface'
+Requires-Dist: peft>=0.13; extra == 'huggingface'
+Requires-Dist: torch>=2.4; extra == 'huggingface'
+Requires-Dist: transformers>=4.45; extra == 'huggingface'
+Provides-Extra: langfuse
+Requires-Dist: langfuse<4,>=3; extra == 'langfuse'
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=0.3; extra == 'langgraph'
+Requires-Dist: langgraph>=0.2; extra == 'langgraph'
+Provides-Extra: langsmith
+Requires-Dist: langsmith>=0.1; extra == 'langsmith'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1; extra == 'mcp'
+Provides-Extra: milvus
+Requires-Dist: pymilvus>=2.4; extra == 'milvus'
+Provides-Extra: openai-assistants
+Requires-Dist: openai>=1.50; extra == 'openai-assistants'
+Provides-Extra: opensearch
+Requires-Dist: opensearch-py>=2.4; extra == 'opensearch'
+Provides-Extra: pgvector
+Requires-Dist: psycopg[binary]>=3.3.4; extra == 'pgvector'
+Provides-Extra: phoenix
+Requires-Dist: arize-phoenix-client>=2; extra == 'phoenix'
+Requires-Dist: httpx>=0.27; extra == 'phoenix'
+Provides-Extra: pinecone
+Requires-Dist: pinecone>=5; extra == 'pinecone'
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.12; extra == 'qdrant'
+Provides-Extra: rag-langchain
+Requires-Dist: langchain-core>=0.3; extra == 'rag-langchain'
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == 'redis'
+Provides-Extra: weaviate
+Requires-Dist: weaviate-client>=4.9; extra == 'weaviate'
+Description-Content-Type: text/markdown
+
+# sectum-ai-adapters
+
+The adapter SDK for [Sectum AI](https://github.com/sectum-ai/sectum-ai) —
+the connectors that point the marker substrate and the attack catalog at real
+systems.
+
+Every adapter family ships a deterministic in-memory `fake` (used by the unit
+suite and offline runs) plus live backends, each behind a capability-reporting
+interface so probes can declare what they require:
+
+- **Vector stores** — pgvector, Chroma, Weaviate, Qdrant, Pinecone, Milvus, OpenSearch, Azure AI Search
+- **RAG pipelines** — generic HTTP, LangChain
+- **Observability** — Langfuse, LangSmith, Phoenix, Helicone, Datadog APM, generic OpenTelemetry
+- **Agents** — LangGraph, AutoGen, CrewAI, OpenAI Assistants, Anthropic tool-use, generic HTTP
+- **MCP** — stdio + streamable-HTTP Model Context Protocol clients
+- **Cache** — Redis
+- **Model** — HuggingFace + PEFT LoRA
+
+```sh
+pip install sectum-ai-adapters
+# live backends are opt-in extras, e.g.:
+pip install "sectum-ai-adapters[pgvector]"   # or [redis], [langgraph], [anthropic-tooluse], ...
+```
+
+Most users install the umbrella package [`sectum-ai`](https://pypi.org/project/sectum-ai/)
+instead, which pulls this in automatically.
+
+- Adapter configuration reference: <https://docs.sectum.ai>
+- Source: <https://github.com/sectum-ai/sectum-ai>
+
+Apache-2.0.

sectum_ai_adapters-0.1.1/README.md

@@ -0,0 +1,31 @@
+# sectum-ai-adapters
+
+The adapter SDK for [Sectum AI](https://github.com/sectum-ai/sectum-ai) —
+the connectors that point the marker substrate and the attack catalog at real
+systems.
+
+Every adapter family ships a deterministic in-memory `fake` (used by the unit
+suite and offline runs) plus live backends, each behind a capability-reporting
+interface so probes can declare what they require:
+
+- **Vector stores** — pgvector, Chroma, Weaviate, Qdrant, Pinecone, Milvus, OpenSearch, Azure AI Search
+- **RAG pipelines** — generic HTTP, LangChain
+- **Observability** — Langfuse, LangSmith, Phoenix, Helicone, Datadog APM, generic OpenTelemetry
+- **Agents** — LangGraph, AutoGen, CrewAI, OpenAI Assistants, Anthropic tool-use, generic HTTP
+- **MCP** — stdio + streamable-HTTP Model Context Protocol clients
+- **Cache** — Redis
+- **Model** — HuggingFace + PEFT LoRA
+
+```sh
+pip install sectum-ai-adapters
+# live backends are opt-in extras, e.g.:
+pip install "sectum-ai-adapters[pgvector]"   # or [redis], [langgraph], [anthropic-tooluse], ...
+```
+
+Most users install the umbrella package [`sectum-ai`](https://pypi.org/project/sectum-ai/)
+instead, which pulls this in automatically.
+
+- Adapter configuration reference: <https://docs.sectum.ai>
+- Source: <https://github.com/sectum-ai/sectum-ai>
+
+Apache-2.0.

sectum_ai_adapters-0.1.1/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sectum-ai-adapters"
+version = "0.1.1"
+description = "Sectum AI - adapters connecting the substrate and probes to real systems."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+authors = [{ name = "Sectum AI" }]
+keywords = ["ai-security", "multi-tenant", "adapters", "verification"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+]
+dependencies = [
+    "sectum-ai-spec",
+    # base.py imports pydantic directly (adapter config models); declare it
+    # rather than relying on the transitive dependency via sectum-ai-spec (§13).
+    "pydantic>=2.9",
+]
+
+[project.optional-dependencies]
+pgvector = ["psycopg[binary]>=3.3.4"]
+chroma = ["chromadb-client>=0.5"]
+weaviate = ["weaviate-client>=4.9"]
+redis = ["redis>=5"]
+# the Phoenix adapter imports httpx directly (observability/phoenix.py); declare
+# it explicitly rather than relying on arize-phoenix-client to pull it in.
+phoenix = ["arize-phoenix-client>=2", "httpx>=0.27"]
+langfuse = ["langfuse>=3,<4"]
+langsmith = ["langsmith>=0.1"]
+mcp = ["mcp>=1"]
+pinecone = ["pinecone>=5"]
+qdrant = ["qdrant-client>=1.12"]
+milvus = ["pymilvus>=2.4"]
+opensearch = ["opensearch-py>=2.4"]
+azure-search = ["azure-search-documents>=11.4", "azure-core>=1.30"]
+langgraph = ["langgraph>=0.2", "langchain-core>=0.3"]
+autogen = ["pyautogen>=0.2,<0.3"]
+crewai = ["crewai>=0.80"]
+huggingface = ["transformers>=4.45", "peft>=0.13", "torch>=2.4", "accelerate>=1"]
+openai-assistants = ["openai>=1.50"]
+anthropic-tooluse = ["anthropic>=0.40"]
+rag-langchain = ["langchain-core>=0.3"]
+# helicone + datadog observability read over their REST APIs with the standard
+# library (no SDK), so they need no extras group; listed here for discoverability.
+
+[project.urls]
+Homepage = "https://sectum.ai"
+Repository = "https://github.com/sectum-ai/sectum-ai"
+
+[tool.uv.sources]
+sectum-ai-spec = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+only-include = ["src/sectum_ai"]
+sources = ["src"]

sectum_ai_adapters-0.1.1/src/sectum_ai/adapters/__init__.py

@@ -0,0 +1,92 @@
+"""Sectum AI adapters: connectors to vector stores, RAG, observability, agents, MCP, and caches.
+
+This is the ``sectum_ai.adapters`` namespace package (the engineering spec, section 11).
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+
+from sectum_ai.adapters.base import (
+    Adapter,
+    AdapterFamily,
+    AdapterRegistry,
+    AgentAdapter,
+    AgentResult,
+    BackupAdapter,
+    CacheAdapter,
+    Capability,
+    EvalSetAdapter,
+    MCPAdapter,
+    McpResult,
+    MemoryAdapter,
+    ModelAdapter,
+    ObservabilityAdapter,
+    RagAnswer,
+    RAGPipelineAdapter,
+    SearchIndexAdapter,
+    TraceHit,
+    VectorHit,
+    VectorStoreAdapter,
+)
+from sectum_ai.adapters.fakes import (
+    FakeAgent,
+    FakeBackup,
+    FakeCache,
+    FakeEvalSet,
+    FakeMCP,
+    FakeMemory,
+    FakeModel,
+    FakeObservability,
+    FakeRAGPipeline,
+    FakeSearchIndex,
+    FakeVectorStore,
+)
+
+__all__ = [
+    "Adapter",
+    "AdapterFamily",
+    "AdapterRegistry",
+    "AgentAdapter",
+    "AgentResult",
+    "BackupAdapter",
+    "CacheAdapter",
+    "Capability",
+    "EvalSetAdapter",
+    "FakeAgent",
+    "FakeBackup",
+    "FakeCache",
+    "FakeEvalSet",
+    "FakeMCP",
+    "FakeMemory",
+    "FakeModel",
+    "FakeObservability",
+    "FakeRAGPipeline",
+    "FakeSearchIndex",
+    "FakeVectorStore",
+    "MCPAdapter",
+    "McpResult",
+    "MemoryAdapter",
+    "ModelAdapter",
+    "ObservabilityAdapter",
+    "RAGPipelineAdapter",
+    "RagAnswer",
+    "SearchIndexAdapter",
+    "TraceHit",
+    "VectorHit",
+    "VectorStoreAdapter",
+    "version",
+]
+
+
+def version() -> str:
+    """Return the installed ``sectum-ai-adapters`` distribution version.
+
+    Stamped into ``RunResult.adapter_versions`` so an evidence pack attests the
+    version of the *adapters* distribution that produced it, not the core CLI's
+    (the engineering spec, section 8.2). Falls back to ``0.0.0+unknown`` in an
+    uninstalled / editable tree.
+    """
+    try:
+        return _dist_version("sectum-ai-adapters")
+    except PackageNotFoundError:  # pragma: no cover - only in an uninstalled tree
+        return "0.0.0+unknown"

sectum_ai_adapters-0.1.1/src/sectum_ai/adapters/agent/__init__.py

@@ -0,0 +1,10 @@
+"""Live agent adapters.
+
+Each module here connects to one real agent backend and is imported explicitly
+(for example ``from sectum_ai.adapters.agent.http import HttpAgent``,
+``from sectum_ai.adapters.agent.langgraph import LangGraphAgent``,
+``from sectum_ai.adapters.agent.autogen import AutoGenAgent``,
+``from sectum_ai.adapters.agent.crewai import CrewAIAgent``,
+``from sectum_ai.adapters.agent.openai_assistants import OpenAIAssistantsAgent``, or
+``from sectum_ai.adapters.agent.anthropic_tooluse import AnthropicToolUseAgent``).
+"""

sectum_ai_adapters-0.1.1/src/sectum_ai/adapters/agent/_anthropic_tooluse_live.py

@@ -0,0 +1,180 @@
+"""Live Anthropic Messages-API client backing the tool-use adapter.
+
+Imported lazily by ``AnthropicToolUseAgent.connect``. The module imports
+``anthropic`` at module load, so a downstream import of
+``sectum_ai.adapters.agent.anthropic_tooluse`` does NOT pull the SDK —
+only construction via ``connect`` does.
+
+Implements the ``_AnthropicClient`` protocol the adapter consumes:
+
+- ``run_turn`` — calls ``messages.create`` on the supplied conversation
+  history; for each ``tool_use`` block in the response, executes the
+  registered python callable, appends a ``tool_result`` user message,
+  and repeats until ``stop_reason: end_turn``. Returns the final
+  assistant text + the list of tool names that fired across the loop.
+
+Tool execution: the caller attaches a python callable to each tool
+spec via the ``__sectum_callable__`` attribute. The backend looks the
+callable up by the tool's ``name`` field.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from sectum_ai.spec import AdapterError
+
+_MAX_TOOL_USE_ITERATIONS = 16
+
+
+class LiveAnthropicClient:
+    """Live ``_AnthropicClient`` implementation backed by the Anthropic Python SDK.
+
+    Holds a single ``anthropic.Anthropic`` client plus a registry of
+    the python callables that back each registered tool by name.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        model: str,
+        tools: list[Any],
+        max_tokens: int,
+        system: str,
+    ) -> None:
+        try:
+            from anthropic import Anthropic
+        except ImportError as error:
+            raise AdapterError(
+                "anthropic-tooluse adapter requires the `anthropic` package; "
+                "install sectum-ai-adapters[anthropic-tooluse] to enable it"
+            ) from error
+        self._anthropic = Anthropic(api_key=api_key) if api_key else Anthropic()
+        self._model = model
+        self._max_tokens = max_tokens
+        self._system = system
+        # The Anthropic tool spec is a dict carrying name / description /
+        # input_schema. Strip the python-callable sidecar before passing
+        # it to the SDK (the SDK rejects unknown keys on tool specs).
+        self._tools: list[dict[str, Any]] = []
+        self._tool_targets: dict[str, Any] = {}
+        for tool in tools:
+            spec = getattr(tool, "__sectum_tool_spec__", None) or tool
+            if not isinstance(spec, dict) or "name" not in spec:
+                raise AdapterError(
+                    "each tool must be (or carry) an Anthropic tool-spec dict "
+                    "with at least a `name` field; got "
+                    f"{type(spec).__name__}"
+                )
+            self._tools.append(spec)
+            name = spec.get("name")
+            callable_target = getattr(tool, "__sectum_callable__", tool)
+            if isinstance(name, str) and name and callable(callable_target):
+                self._tool_targets[name] = callable_target
+
+    def run_turn(self, messages: list[dict[str, Any]]) -> tuple[str, tuple[str, ...]]:
+        """Drive the tool-use loop to completion; return (final_text, tool_names)."""
+        tool_names: list[str] = []
+        loop_messages = list(messages)
+        for _ in range(_MAX_TOOL_USE_ITERATIONS):
+            response = self._anthropic.messages.create(
+                model=self._model,
+                max_tokens=self._max_tokens,
+                system=self._system,
+                tools=self._tools,
+                messages=loop_messages,
+            )
+            content_blocks = getattr(response, "content", []) or []
+            tool_uses = [
+                block for block in content_blocks if getattr(block, "type", None) == "tool_use"
+            ]
+            if not tool_uses:
+                # No more tool calls; collect the final assistant text and stop.
+                final_text = _collect_text(content_blocks)
+                return final_text, tuple(tool_names)
+
+            # Append the assistant's tool_use turn to the loop history so the
+            # next messages.create call has the context.
+            loop_messages.append(
+                {
+                    "role": "assistant",
+                    "content": [_block_to_dict(block) for block in content_blocks],
+                }
+            )
+
+            # Execute each tool_use block and build the matching
+            # tool_result user message.
+            tool_results: list[dict[str, Any]] = []
+            for block in tool_uses:
+                name = getattr(block, "name", None)
+                if not isinstance(name, str) or not name:
+                    continue
+                tool_names.append(name)
+                tool_use_id = getattr(block, "id", "")
+                arguments = getattr(block, "input", None)
+                if not isinstance(arguments, dict):
+                    arguments = {}
+                target = self._tool_targets.get(name)
+                if target is None:
+                    result = ""
+                else:
+                    try:
+                        result = target(**arguments)
+                    except Exception as error:
+                        result = f"tool {name} raised {type(error).__name__}: {error}"
+                tool_results.append(
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": tool_use_id,
+                        "content": str(result),
+                    }
+                )
+            loop_messages.append({"role": "user", "content": tool_results})
+
+        raise AdapterError(
+            f"anthropic tool-use loop exceeded {_MAX_TOOL_USE_ITERATIONS} iterations"
+        )
+
+
+def _collect_text(content_blocks: list[Any]) -> str:
+    """Concatenate every ``text`` block's text into a single string."""
+    parts: list[str] = []
+    for block in content_blocks:
+        if getattr(block, "type", None) != "text":
+            continue
+        text = getattr(block, "text", "")
+        if isinstance(text, str):
+            parts.append(text)
+    return "".join(parts)
+
+
+def _block_to_dict(block: Any) -> dict[str, Any]:
+    """Convert an SDK content-block object back to its dict form.
+
+    Anthropic's SDK returns typed block objects on responses but expects
+    dict-shaped blocks when echoing them back as assistant history; the
+    serialisation has to round-trip without losing the type tag.
+    """
+    block_type = getattr(block, "type", None)
+    if block_type == "text":
+        return {"type": "text", "text": getattr(block, "text", "")}
+    if block_type == "tool_use":
+        input_value = getattr(block, "input", None)
+        if isinstance(input_value, str):
+            try:
+                input_value = json.loads(input_value)
+            except json.JSONDecodeError:
+                input_value = {}
+        if not isinstance(input_value, dict):
+            input_value = {}
+        return {
+            "type": "tool_use",
+            "id": getattr(block, "id", ""),
+            "name": getattr(block, "name", ""),
+            "input": input_value,
+        }
+    # Unknown block type; fall back to a string projection so the loop
+    # does not crash on a future SDK addition.
+    return {"type": block_type or "unknown", "text": str(block)}

sectum_ai_adapters-0.1.1/src/sectum_ai/adapters/agent/_openai_assistants_live.py

@@ -0,0 +1,149 @@
+"""Live OpenAI Assistants client implementation.
+
+Imported lazily by ``OpenAIAssistantsAgent.connect``. The module imports
+``openai`` at module load, so a downstream import of
+``sectum_ai.adapters.agent.openai_assistants`` does NOT pull the SDK —
+only construction via ``connect`` does.
+
+Implements the ``_AssistantsClient`` protocol the adapter consumes:
+
+- ``create_assistant`` — creates the persistent Assistant (model +
+  instructions + tools); returns its id
+- ``create_thread`` — creates a fresh conversation Thread; returns its
+  id (the adapter caches one per tenant)
+- ``add_user_message`` — posts a user message into the Thread
+- ``run_until_complete`` — starts a Run and drives it through the
+  tool-call resolution loop until ``completed`` (or a terminal
+  failure); returns ``(final_assistant_text, tool_call_names)``
+
+Tool execution: the live backend resolves each ``requires_action``
+event by reading the tool name + arguments off the run, calling the
+caller-supplied Python callable mapped under the same name, and
+posting the result back via ``submit_tool_outputs``. The caller
+attaches a python callable to each tool spec via the
+``__sectum_callable__`` attribute so the backend can find it.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+from sectum_ai.adapters.agent.openai_assistants import _poll_delay_ms
+from sectum_ai.spec import AdapterError
+
+
+class LiveAssistantsClient:
+    """Live ``_AssistantsClient`` implementation backed by the OpenAI Python SDK.
+
+    Holds a single ``openai.OpenAI`` client and a registry of the
+    Python callables that back each tool name on the configured
+    Assistant.
+    """
+
+    def __init__(self, api_key: str | None = None) -> None:
+        try:
+            from openai import OpenAI
+        except ImportError as error:
+            raise AdapterError(
+                "openai-assistants adapter requires the `openai` package; "
+                "install sectum-ai-adapters[openai-assistants] to enable it"
+            ) from error
+        self._openai = OpenAI(api_key=api_key) if api_key else OpenAI()
+        self._tools: dict[str, Any] = {}
+
+    def create_assistant(
+        self,
+        model: str,
+        tools: list[Any],
+        *,
+        name: str,
+        instructions: str,
+    ) -> str:
+        """Create a persistent Assistant + register the tool callables locally."""
+        tool_specs: list[dict[str, Any]] = []
+        for tool in tools:
+            spec = getattr(tool, "__sectum_tool_spec__", None) or tool
+            if not isinstance(spec, dict) or "function" not in spec:
+                raise AdapterError(
+                    "each tool must carry a `__sectum_tool_spec__` dict with the "
+                    "OpenAI function-tool schema, or be a tool-spec dict itself"
+                )
+            tool_specs.append(spec)
+            function_name = spec.get("function", {}).get("name")
+            callable_target = getattr(tool, "__sectum_callable__", tool)
+            if function_name and callable(callable_target):
+                self._tools[function_name] = callable_target
+        assistant = self._openai.beta.assistants.create(
+            model=model,
+            name=name,
+            instructions=instructions,
+            tools=tool_specs,
+        )
+        return str(assistant.id)
+
+    def create_thread(self) -> str:
+        thread = self._openai.beta.threads.create()
+        return str(thread.id)
+
+    def add_user_message(self, thread_id: str, content: str) -> None:
+        self._openai.beta.threads.messages.create(thread_id=thread_id, role="user", content=content)
+
+    def run_until_complete(self, thread_id: str, assistant_id: str) -> tuple[str, tuple[str, ...]]:
+        run = self._openai.beta.threads.runs.create(thread_id=thread_id, assistant_id=assistant_id)
+        tool_names: list[str] = []
+        attempt = 0
+        while True:
+            run = self._openai.beta.threads.runs.retrieve(thread_id=thread_id, run_id=run.id)
+            status = getattr(run, "status", None)
+            if status == "completed":
+                break
+            if status in ("failed", "cancelled", "expired"):
+                raise AdapterError(
+                    f"openai assistants run terminated in {status!r}: "
+                    f"{getattr(run, 'last_error', None)}"
+                )
+            if status == "requires_action":
+                outputs = []
+                required = getattr(run, "required_action", None)
+                tool_calls = (
+                    getattr(getattr(required, "submit_tool_outputs", None), "tool_calls", [])
+                    if required is not None
+                    else []
+                )
+                for call in tool_calls:
+                    function = getattr(call, "function", None)
+                    if function is None:
+                        continue
+                    name = getattr(function, "name", None)
+                    if not isinstance(name, str) or not name:
+                        continue
+                    tool_names.append(name)
+                    args_raw = getattr(function, "arguments", "") or "{}"
+                    try:
+                        args = json.loads(args_raw)
+                    except json.JSONDecodeError:
+                        args = {}
+                    target = self._tools.get(name)
+                    if target is None:
+                        result: Any = ""
+                    else:
+                        result = target(**args)
+                    outputs.append({"tool_call_id": getattr(call, "id", ""), "output": str(result)})
+                self._openai.beta.threads.runs.submit_tool_outputs(
+                    thread_id=thread_id, run_id=run.id, tool_outputs=outputs
+                )
+            time.sleep(_poll_delay_ms(attempt) / 1000.0)
+            attempt += 1
+
+        messages = self._openai.beta.threads.messages.list(thread_id=thread_id, order="desc")
+        for message in messages.data:
+            if getattr(message, "role", None) != "assistant":
+                continue
+            content_blocks = getattr(message, "content", []) or []
+            for block in content_blocks:
+                text = getattr(getattr(block, "text", None), "value", None)
+                if isinstance(text, str) and text:
+                    return text, tuple(tool_names)
+        return "", tuple(tool_names)