Federated BiDi Execution

ContextRouter introduces Manifest-Driven Federated Tool Execution—an Inversion of Control pattern that transforms the Router from a monolith into a pure Cognition Orchestrator.

Instead of passing sensitive credentials (like database DSNs) directly into the Router for hardcoded local execution, projects declare their execution capabilities and handle the workloads securely on their own side of the network boundary.

How It Works

1. Manifest Registration: Your project’s SDK parses its local contextunity.project.yaml file, compiles the execution: federated tool signatures, and negotiates with the Router. No credentials ever leave your infrastructure.
2. BiDi Stream Creation: The projectSDK automatically establishes a long-lived bidirectional gRPC stream with the Router. It announces itself as ready to handle execution requests.
3. Intent Dispatch: When the cognitive engine (LLM) decides to use a federated tool (such as running a SQL query against your internal database), the Router delegates the payload down the BiDi stream.
4. Local Execution: The project SDK intercepts this payload, executes it within its protected boundary using its native credentials, and streams the result back natively through the protocol.

Why use BiDi Execution?

• Zero-Knowledge Architecture: ContextUnity never touches your database. Passwords never traverse the internet.
• Blast Radius Control: Validation and execution happen natively within your process. If necessary, you can establish fallback read-only database connections or human-in-the-loop manual approval gates.
• Enterprise On-Premise: Deploy lightweight local containers into strict corporate networks that open outbound gRPC streams to ContextRouter without fighting complex inbound firewall exceptions.

Federated Toolkits (v2)

To manage growing numbers of federated tools cleanly, projects use Federated Toolkits, a class-based approach grouping state and logic under strict Pydantic execution bounds.

Instead of writing dozens of standalone functions, toolkits provide modularity:

from contextunity.core.sdk.toolkit import FederatedToolkit, tool
import aiosqlite

class DatabaseToolkit(FederatedToolkit, stateful=True):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.db = aiosqlite.connect("file.db")

    @tool(timeout=120, retries=3)
    async def run_query(self, query: str):
        # self.ctx Contains the FederatedToolCallContext!
        return await self.db.execute(query)

Toolkits are bound at configuration time in the consumer project’s manifest (contextunity.project.yaml):

router:
  toolkits:
    - name: GlobalDefaultsToolkit  # Applies to all graphs
  graph:
    commerce_pipeline:
      toolkits:
        - name: DatabaseToolkit
          exclude: ["destructive_query"]
          overrides:
            run_query:
              timeout: 600

ContextUnity SDK manages singleton sharing (when stateful=True), transparent context injection, runtime retries via the BiDi loop, and graph-specific inclusion parameters automatically.