iagent-mesh-sdk (DevEx Hub)

This repository serves as the Data-Driven Developer Experience (DevEx) Hub and provides the iagent_mesh SDK core library, which includes universal contracts and an infrastructure wrapper for the iagent Mesh platform.

📖 Architectural Guide: Read Launch Domain Nodes, Not Scripts to understand why this framework is required for enterprise AI deployments.

🔌 Substrate Interfaces: Read Substrate Interfaces for MeshGraph / MeshOntology / MeshVectors — the named reads an engine uses instead of a driver or a query language, the MeshResult type every one of them returns, and the conformance suite that admits an implementation.

Architecture & Features

This Hub leverages the Inception Pattern to dynamically scaffold new agent tools.

• iagent_mesh Core Library: Contains MeshTool for routing, FastAPI execution, and Topaz Zero-Trust security.
• Substrate Interfaces (iagent_mesh.interfaces): Three Protocols — MeshGraph, MeshOntology, MeshVectors — giving an engine named reads over the property graph, the RDF store and the vector store instead of a driver handle or a query-language slot. Every operation carries the Initiator (who is asking) and returns a MeshResult that distinguishes answered / empty / failed / unreachable. Implementations are admitted by passing iagent_mesh.conformance, never by being named in the SDK. See docs/interfaces.md.
• The write half (MeshGraphWriter / MeshVectorsWriter / MeshOntologyWriter, plus iagent_mesh.writers.jena.JenaOntologyWriter as the reference implementation): sibling Protocols to the read interfaces above, never new methods on them. Ruled 2026-09-27 — shipped on lane/ca, pending v0.9.5, no release without explicit sign-off. See §4a of docs/interfaces.md.
• Templates: Standardized data scientist environments (Pure Math, Instructor + Polars, BAML + Pandas).
• Interactive Scaffolding: Use scripts/scaffold.sh to locally generate a new agent from a template.
• MCP Server: The mcp_server/server.py exposes tools (scaffold_local_workspace, publish_local_to_mesh, mesh_explain) for intelligent IDE-based agent creation. mesh_explain is the SDK's first outside consumer of a mesh read (engine-docs /explain): it connects as a delegate Initiator — never a person, and refused by Initiator.require_person like any other non-person identity — and returns the full MeshResult outcome rather than a bare success/failure string. Registration in .mcp.json is a proposal, not yet enabled — see sessions/ for the reachability report a lane worktree needs before turning it on.
• Cloud Endpoints: app.py exposes REST APIs (scaffold_generator, mesh_publisher) for the central orchestrator to provision workspaces dynamically.

Environment Configuration

This SDK relies on centralized environment variables for all integrations to ensure no hardcoded enterprise strings are checked in. See the .env.example file in the root directory for a full list.

Required URLs:

• GIT_PROVISION_API_URL: The platform provisioning API for repositories.
• GIT_SERVER_HOST: The core Git server hostname.
• ARTIFACTORY_BASE_URL: The enterprise artifact repository.

Optional URLs / tokens (only needed if MESH_REGISTER_ON_STARTUP=true):

• DATAHUB_GMS_URL: The DataHub GMS endpoint the SDK pushes registrations to.
• DATAHUB_TOKEN: Bearer token for the GMS emitter.

Required Tokens (Depending on deployment):

• PLATFORM_GIT_TOKEN: Used by the cloud pod (app.py) for live git publishing.
• MESH_DEV_TOKEN: Used by the local mcp_server to authenticate against provisioning APIs.

mesh_explain (mcp_server only):

• ENGINE_DOCS_URL: Base URL of the engine-docs deployment mesh_explain calls /explain on. Required at call time; unset raises naming it, rather than a request to https://None/explain.
• MESH_EXPLAIN_ON_BEHALF_OF: Who this tool's delegate Initiator is accountable to. Required, no default — a delegate with nobody accountable is a service under another name, and mesh_explain refuses to invent one.
• MESH_EXPLAIN_SUBJECT: Optional; defaults to mcp:mesh_explain. The delegate's own opaque subject — not yet a minted credential (no kind="delegate" mint path exists), so it travels as an informational header, never an Authorization bearer token.

Installation & Testing

Data scientists can install the core SDK via:

uv pip install git+https://[your-repo-url]

To run the robust regression testing suite:

uv pip install -e ".[dev]"
python -m pytest