iagent-mesh 0.4.0__tar.gz

iagent_mesh-0.4.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.env
+.venv
+venv/
+.pytest_cache/
+.coverage
+build/
+dist/
+*.egg-info/

iagent_mesh-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edgy Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software χωρίς restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

iagent_mesh-0.4.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: iagent_mesh
+Version: 0.4.0
+Summary: Universal contracts and infrastructure wrapper for the iagent Mesh — typed predicate registration, transport auth, and per-caller identity for mesh tools
+Project-URL: Homepage, https://github.com/edgy-solutions/iagent-mesh-sdk
+Project-URL: Repository, https://github.com/edgy-solutions/iagent-mesh-sdk
+Project-URL: Issues, https://github.com/edgy-solutions/iagent-mesh-sdk/issues
+Author-email: Chris Nogradi <cnogradi@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai-mesh,datahub,fastapi,knowledge-graph,predicate-graph,topaz
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: acryl-datahub>=0.13.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: mcp<2,>=1.0.0
+Requires-Dist: nest-asyncio>=1.5.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn>=0.23.0
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-mock; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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](docs/architecture_manifesto.md) to understand why this framework is required for enterprise AI deployments.
+
+## 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.
+- **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`) for intelligent IDE-based agent creation.
+- **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.
+
+## Installation & Testing
+
+Data scientists can install the core SDK via:
+```bash
+uv pip install git+https://[your-repo-url]
+```
+
+To run the robust regression testing suite:
+```bash
+uv pip install -e ".[dev]"
+python -m pytest
+```

iagent_mesh-0.4.0/README.md

@@ -0,0 +1,45 @@
+# 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](docs/architecture_manifesto.md) to understand why this framework is required for enterprise AI deployments.
+
+## 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.
+- **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`) for intelligent IDE-based agent creation.
+- **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.
+
+## Installation & Testing
+
+Data scientists can install the core SDK via:
+```bash
+uv pip install git+https://[your-repo-url]
+```
+
+To run the robust regression testing suite:
+```bash
+uv pip install -e ".[dev]"
+python -m pytest
+```

iagent_mesh-0.4.0/app.py

@@ -0,0 +1,99 @@
+import os
+import uuid
+import subprocess
+from fastapi import FastAPI
+from pydantic import Field
+from iagent_mesh.models import ToolInput, ToolOutput
+from iagent_mesh.core import MeshTool
+from iagent_mesh.scaffold_core import generate_template_files, publish_workspace_to_git
+from iagent_mesh.config import settings
+
+# 1. Define Schemas
+class ScaffoldInput(ToolInput):
+    template_id: str = Field(...)
+    tool_name: str = Field(...)
+    is_mcp: bool = Field(False)
+
+class ScaffoldOutput(ToolOutput):
+    workspace_uuid: str
+    target_path: str
+
+class PublishInput(ToolInput):
+    workspace_uuid: str = Field(...)
+    tool_name: str = Field(...)
+    is_mcp: bool = Field(False)
+    target_git_group: str = Field(...)
+
+class PublishOutput(ToolOutput):
+    status: str
+    git_url: str
+
+# 2. Initialize MeshTools — these are platform tools (the DevEx Hub itself
+# exists only because the mesh exists), so they use the ``mesh:`` namespace
+# per ADR-0005. The predicate edges they create are:
+#
+#     (mesh:ScaffoldRequest) --[mesh:scaffoldWorkspace]--> (mesh:ScaffoldedWorkspace)
+#     (mesh:PublishRequest)  --[mesh:publishWorkspace]-->  (mesh:GitDeployment)
+scaffold_tool = MeshTool(
+    name="scaffold_generator",
+    description="Scaffolds a DevEx template into a fresh workspace directory.",
+    verb="mesh:scaffoldWorkspace",
+    input_uri="mesh:ScaffoldRequest",
+    output_uri="mesh:ScaffoldedWorkspace",
+    verb_synonyms=["scaffold", "generate workspace", "create from template"],
+    owner_persona="DATA_STEWARD",
+    cost_class="fast",
+)
+publish_tool = MeshTool(
+    name="mesh_publisher",
+    description="Publishes a scaffolded workspace to a managed git remote.",
+    verb="mesh:publishWorkspace",
+    input_uri="mesh:PublishRequest",
+    output_uri="mesh:GitDeployment",
+    verb_synonyms=["publish", "push to git", "deploy workspace"],
+    owner_persona="DATA_STEWARD",
+    cost_class="medium",
+)
+
+# 3. Define Tool Logic
+@scaffold_tool.execute()
+def run_scaffold(data: ScaffoldInput) -> ScaffoldOutput:
+    workspace_uuid = str(uuid.uuid4())
+    target_path = f"/tmp/{workspace_uuid}"
+    
+    # Enforce standardized URN based on type
+    if data.is_mcp:
+        tool_urn = f"urn:li:mcpServer:{data.tool_name}"
+    else:
+        tool_urn = f"urn:li:aitool:{data.tool_name}"
+    
+    generate_template_files(data.template_id, data.tool_name, tool_urn, target_path)
+    
+    return ScaffoldOutput(workspace_uuid=workspace_uuid, target_path=target_path)
+
+@publish_tool.execute()
+def run_publish(data: PublishInput) -> PublishOutput:
+    target_path = f"/tmp/{data.workspace_uuid}"
+    if not os.path.exists(target_path):
+        raise ValueError(f"Workspace not found at {target_path}")
+        
+    git_token = settings.require("PLATFORM_GIT_TOKEN")
+    git_host = settings.require("GIT_SERVER_HOST")
+    git_url = f"https://oauth2:{git_token}@{git_host}/{data.target_git_group}/{data.tool_name}.git"
+    
+    # Use centralized utility
+    try:
+        publish_workspace_to_git(target_path, git_url)
+    except RuntimeError as e:
+        raise ValueError(str(e))
+    
+    return PublishOutput(status="Success", git_url=git_url)
+
+# 4. Master App
+app = FastAPI(title="DevEx Hub Cloud Tools")
+app.mount("/scaffold", scaffold_tool.app)
+app.mount("/publish", publish_tool.app)
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

iagent_mesh-0.4.0/docs/HANDOFF-meshtool-execute.md

@@ -0,0 +1,238 @@
+> ## ✅ RESOLVED in v0.4.0 — both findings, landed together
+>
+> **Disposition: BOTH, in one change to `route_handler`** — the option this packet argued for.
+> They were not landed separately, so the `run_in_executor` composition hazard described below
+> never had a window to occur.
+>
+> * **Finding A** — a parameter annotated `CallerIdentity` (any name) now receives the invoker;
+>   `current_caller()` reads the same identity from a request-scoped `ContextVar` where no
+>   parameter can be threaded; `require_authz_id()` is the fail-closed read accessor.
+> * **Finding B** — sync handlers run via `anyio.to_thread.run_sync` under an explicit
+>   `contextvars.copy_context()`, so the contextvar survives into the worker thread. The
+>   quickstart's promise is now true rather than corrected away.
+> * **The silence** — the packet asked that not consuming the identity be *visible*. An
+>   undeclared unscoped handler now WARNS at registration; `@app.execute(caller_scoped=False)`
+>   records deliberate intent and silences it. All five shipped templates declare a posture.
+>
+> **Both rulings were answered by enumeration, not preference.** The census the packet demanded
+> found ZERO `MeshTool.execute()` handlers in invincible-agent (zero `MeshTool` call sites at
+> all), so the population holding retroactively-broken sync handlers was empty — fix the code,
+> no migration debt.
+>
+> **Version:** ADDITIVE for tool authors — the single-parameter form is unchanged and untouched
+> handlers keep working. Execution *semantics* change for sync handlers (they now run off the
+> event loop), and undeclared handlers gain a startup warning. The `!` on v0.4.0 is for
+> `MeshClient.ask()` and the `requires-python` bump, not for `execute()`.
+>
+> Seals: `tests/test_caller_identity_reaches_handler.py` (incl. an executable root-cause seal
+> pinning that FastAPI discards app-level dependency return values),
+> `tests/test_per_user_read_end_to_end.py` (three-caller discrimination),
+> `tests/test_sync_handlers_do_not_block.py` (incl. `test_THE_COORDINATION_TEST...`),
+> `tests/test_scoping_posture_is_declared.py`. Each was broken on purpose and shown red first.
+>
+> Original packet preserved below.
+
+# Handoff — two defects in `MeshTool.execute()`, and why they are one job
+
+> ## ✅ RESOLVED in 0.4.0 (2026-08-27)
+>
+> Both findings fixed together, in one change to `route_handler`, as this document required.
+>
+> * **Finding A** — a parameter annotated `CallerIdentity` receives the invoker;
+>   `current_caller()` reads the same identity from a request-scoped `ContextVar` with no
+>   parameter. `CallerIdentity.require_authz_id()` is the fail-closed read accessor: it raises
+>   rather than returning the `None` that silently becomes a service read.
+> * **Finding B** — sync handlers run via `anyio.to_thread.run_sync` under an explicit
+>   `contextvars.copy_context()`, so the doc's threading promise is now true *and* A's contextvar
+>   survives into the worker thread.
+>
+> **Both rulings were answered by enumeration, not preference.** The handler census the document
+> demanded returned **zero** `MeshTool.execute()` handlers in invincible-agent (and zero
+> `MeshTool` / `MeshClient` call sites at all) — so the population holding retroactively-broken
+> sync handlers was empty, and fixing the code carried no migration debt. Ruling 1 → fix the
+> code. Ruling 2 → the count is zero; the five in-repo templates all use the unchanged
+> single-parameter form.
+>
+> **The interaction this document predicted was reproduced, not assumed.** Implementing B with
+> `loop.run_in_executor` passes every threading test while `current_caller()` reads `None` inside
+> the recommended handler style. That is why the acceptance criterion below is a test named
+> `test_THE_COORDINATION_TEST_...` — it is the only one that fails in that configuration.
+>
+> Tests: `tests/test_caller_identity_reaches_handler.py`,
+> `tests/test_sync_handlers_do_not_block.py`, `tests/test_per_user_read_end_to_end.py`,
+> `tests/test_cortex_data_client_contract.py`. Each fix was broken on purpose, shown red for its
+> own reason, and restored.
+>
+> **Found while fixing these** (and fixed): `execute()` read the handler's annotation raw, so any
+> tool module using `from __future__ import annotations` 422'd on *every* request with
+> `'str' object is not callable` — see `tests/test_postponed_annotations.py`.
+>
+> Bridge to the data plane is `originator_email=caller.require_authz_id()` — dag-tools'
+> `CortexDataClient` takes a string subject, carried opaque, so employee-id deployments work
+> unchanged. `caller=` was not adopted because that parameter does not exist in dag-tools yet;
+> `test_cortex_data_client_contract.py` watches its real source and goes red when it appears.
+
+**To:** whoever owns `iagent-mesh-sdk`
+**From:** the ADR-0044 / mesh-read session, 2026-08-27
+**Both findings are in `iagent_mesh/core.py`, in the same function.**
+
+Plan items (invincible-agent `docs/plans/`, on `docs/BOARD.md`):
+`[[sdk-discards-caller-identity]]`, `[[sdk-blocking-sync-handlers]]`.
+
+---
+
+## Read this first: they touch the same seam, so sequence them
+
+Both fixes change `MeshTool.execute()`'s `route_handler`. **Two uncoordinated fixes to one
+function is how it grows a third defect**, and in this case they interact directly:
+
+- Fix A puts a `CallerIdentity` in a request-scoped `ContextVar`.
+- Fix B moves sync handlers off the event loop onto a thread.
+- **`asyncio.to_thread` copies the context. `loop.run_in_executor` does not.**
+
+Do B with `run_in_executor` and A's contextvar reads `None` inside **exactly the handler style
+the quickstart recommends** — and without A's fail-closed rule, that read lands on the service
+identity, silently, in the most common case. Two correct-looking fixes producing a
+cross-tenant read.
+
+Do them together, or A then B with B's mechanism chosen for A.
+
+---
+
+## Finding A — a tool cannot learn who invoked it
+
+**`core.py:180`** registers the auth dependency at APP level:
+
+```python
+dependencies=[Depends(make_transport_auth_dependency(component=name))],
+```
+
+`make_transport_auth_dependency` does the right thing — it returns a `CallerIdentity` whose
+`authz_id` is documented as *"the ONLY field an authorization decision may key on."* But
+**FastAPI discards an app-level dependency's return value.** It is not injectable into a route,
+never reaches `request.state`, and `route_handler` does not ask for it.
+
+Then **`core.py:440`**:
+
+```python
+return func(input_data)
+```
+
+The handler receives the validated input model and nothing else.
+
+**So the caller is computed, logged, and thrown away** — one frame before anyone could use it.
+
+### What that forces
+
+A tool author has nothing to put here:
+
+```python
+client = CortexDataClient(originator_email=???)
+```
+
+Their only working option is a bare constructor, which resolves to the **service identity**. So
+**every user of that agent reads with the service's entitlements** — the confused deputy the
+platform's own chart comment warns about on `CORTEX_CLIENT_ID`.
+
+**It fails invisibly.** An agent reading as the service *works*. Rows come back, nothing errors,
+no test fails. The only symptom is that every user sees data entitled to the service.
+
+**Existence proof:** Engine DA does not get the caller from the SDK. It pulls `user_email` off
+the request payload (`agent_fleet/data_analyst/main.py:271`) because the supervisor threads it
+manually. The one agent doing per-user reads correctly had to route around the SDK.
+
+### The target
+
+```python
+@app.execute()
+def detect_anomalies(data: AnomalyInput, caller: CallerIdentity) -> AnomalyOutput:
+    client = CortexDataClient(caller=caller)
+```
+
+…and better, with a contextvar, no parameter at all:
+
+```python
+client = CortexDataClient()          # notebook, pipeline, agent handler — identical
+```
+
+**The resolution order matters more than the mechanism, and it is the part to get right:**
+
+> 1. explicit `caller=` — override, for tests. Wins over everything.
+> 2. the request-scoped contextvar — the agent case.
+> 3. `CORTEX_USER_TOKEN` — per-process user identity (notebook).
+> 4. service identity — **opt-in only.**
+>
+> **Inside a request, failure to resolve RAISES.** It never falls through to 3 or 4.
+
+**Why 2 must outrank 3:** everyone writing this by hand reaches for
+
+```python
+return os.environ['CORTEX_USER_TOKEN'] if 'CORTEX_USER_TOKEN' in os.environ else caller
+```
+
+which works in all three contexts today — **only because that var happens to be unset on agent
+pods.** Set it once for debugging and every request silently reads as one user, with code that
+still looks correct. A confused deputy arriving via a *config* change, with nothing to review.
+
+Steps 1 and 2 ship together. The contextvar without the fail-closed rule just relocates the
+silent service-read from "author forgot `caller=`" to "contextvar was empty for a reason nobody
+noticed."
+
+---
+
+## Finding B — the quickstart promises a background thread that does not exist
+
+**`core.py:438`**:
+
+```python
+if inspect.iscoroutinefunction(func):
+    return await func(input_data)
+return func(input_data)          # no threadpool
+```
+
+**`docs/jupyter_guide.md`**:
+
+> **Use standard `def` (Recommended):** If you are crunching Polars DataFrames
+> (`df.collect()`), stick to standard `def`. **We will execute it safely in a background
+> thread.**
+
+`grep -rn "run_in_threadpool\|to_thread\|run_in_executor" iagent_mesh/*.py` → nothing.
+
+A recommended handler doing `df.collect()` holds the event loop for its duration. Every other
+request to that tool, including health probes, waits.
+
+**The doc recommended the failing path for the heaviest workload**, so authors who complied are
+worse off than authors who ignored it.
+
+### Two rulings, neither of them technical
+
+1. **Fix the code or fix the doc?** Threading makes every existing sync handler retroactively
+   correct — and changes execution semantics for handlers written assuming single-threaded
+   module state. Correcting the doc makes them retroactively wrong and obliges migration. The
+   choice decides **which population currently holds broken code.**
+2. **Who audits existing handlers, and how many are there?** Neither option can be sized
+   without a count. Enumerate before choosing — a remembered list of "the tools we know about"
+   is how the sixth one breaks.
+
+---
+
+## Acceptance for the pair
+
+- A tool handler can name its invoker; a read inside it authorizes as **that person**.
+- Two different users invoking the same agent against the same asset get **different rows**.
+- `CORTEX_USER_TOKEN` set on an agent pod changes nothing — the request's caller outranks it.
+- Reading as the service requires saying so.
+- A sync handler doing a multi-second `collect()` does not delay a concurrent request.
+- **If threaded: a `ContextVar` set by the auth dependency is readable inside a sync handler.**
+  This is the test that proves the two fixes were coordinated.
+
+## Context worth having
+
+The mesh's read path was hardened today (invincible-agent ADR-0044, dag-tools 0.3.2): routing
+tickets now carry only broker-minted credentials, scoped to the asset and expiring with the
+access window. That closed *what a caller is handed*. Finding A is *whether an agent can say
+who is asking* — and it is the blocker on the notebook→agent path, which is where the users
+are actually heading.
+
+Not filed by an agent unilaterally because both rulings are blast-radius questions, not
+technical preferences.

iagent_mesh-0.4.0/docs/architecture_manifesto.md

@@ -0,0 +1,162 @@
+# THE iagent MESH: LAUNCH DOMAIN NODES, NOT SCRIPTS
+### An Architectural Guide for Data Science and AI Engineering Teams
+
+Your team’s primary directive is to engineer state-of-the-art AI agents and custom user experiences. However, the path to production often forces data scientists to become part-time cloud infrastructure engineers. In an enterprise environment, AI cannot operate in the shadows; agents must be assigned to persons, and their actions must be entirely traceable, predictable, observable, grounded, and trustworthy. 
+
+This document outlines the architectural realities of deploying AI services in our enterprise ecosystem, comparing the traditional Do-It-Yourself (DIY) API deployment against adopting the native `MeshTool` framework.
+
+---
+
+## PART 1: THE DIY REALITY (THE HIDDEN COST OF CUSTOM INFRASTRUCTURE)
+
+If you choose to bypass the framework and deploy your agents as standalone APIs (e.g., raw FastAPI/Flask) to serve your custom UIs, you assume full responsibility for the enterprise plumbing. 
+
+Here is the infrastructure you are now required to build, maintain, and secure to meet enterprise standards:
+
+* **Identity & Policy Enforcement:** Enterprise agents must be definitively assigned to real persons. You must manually write middleware to intercept Keycloak JWTs, parse claims, and enforce complex data access policies on every single incoming request to prove authorization.
+* **Data Access & Grounding:** To be trustworthy, an agent must be firmly grounded in secure enterprise data. You cannot simply ask for a dataset; you must manage your own AWS STS token exchanges, handle credential rotation, and manually enforce Row-Level Security (RLS) and column masking to remain compliant.
+* **Distributed Tracing (The Black Hole):** An AI system must be completely observable. When your custom UI calls your agent, and your agent calls a vector DB or an LLM, the trace is easily broken. You must manually inject Langfuse observers, pass trace IDs through your thread pools, and manage the `contextvars` yourself. When a hallucination or failure occurs, your logging is siloed and untraceable.
+* **Concurrency & Predictability:** AI behavior must be predictable. If your agent uses `asyncio` mixed with synchronous data crunching (Pandas/Polars) or nested sub-agents (`smolagents`), you risk freezing your event loop and crashing your Kubernetes pods under load unless you manually patch and manage thread pools.
+* **Deployment Boilerplate:** You own the Dockerfiles, the Kubernetes YAMLs, the Helm charts, and the CI/CD pipeline definitions required to get your code into the cluster.
+
+**The Result:** Your team spends 80% of its velocity maintaining backend plumbing and proving compliance, and only 20% engineering the actual AI and the custom UI.
+
+---
+
+## PART 2: THE `MeshTool` ADVANTAGE
+
+The `MeshTool` framework is not a restriction; it is an exoskeleton. It provides a hardened, headless backend for your custom UI, absorbing all enterprise infrastructure and compliance complexity into three lines of code.
+
+### 1. Frictionless, Trustworthy Data Plane
+Never manage an AWS key, database password, or access policy again.
+* **Identity Passthrough:** Agents are inherently assigned to persons. The moment you use `CortexDataClient()`, the mesh invisibly routes your user's Keycloak JWT through the cluster, ensuring every action is tied to a verified human.
+* **Native Compliance & Grounding:** The platform automatically enforces central data access policies, RLS, and column masking before the data ever hits your agent. Your agent is guaranteed to be grounded in trustworthy, authorized enterprise data.
+* **High-Throughput Ready:** Seamless integration with `dag_tools` returns Polars LazyFrames for instant, massive-scale data crunching without crashing your LLM context windows.
+
+### 2. Complete Observability Out-of-the-Box
+Debugging a nested AI loop shouldn't require guesswork. 
+* **End-to-End Traceability:** The mesh generates a unified Trace ID from your custom UI's HTTP header and propagates it flawlessly across all network boundaries and asynchronous threads.
+* **Langfuse Native:** Every LLM call, tool use, and latency spike inside your agent is automatically tracked, made fully observable, and tied to the exact user session.
+
+### 3. Predictable Concurrency & DevOps
+You write the Python; the platform ensures predictable execution.
+* **Safe Asynchronous Execution:** The framework natively applies `nest_asyncio` and thread-pool routing. You can spin up heavy data operations or nested agent loops without ever freezing your API.
+* **One-Click Deployment:** Use the interactive `scaffold.sh` to generate a GitOps-ready repository. Push your code, and Jenkins automatically builds the container (via S2I) and deploys it. Zero Dockerfiles required.
+
+### 4. Headless Architecture (Bring Your Own UI)
+We do not force you into a centralized UI.
+* **Perfect Portability:** `MeshTool` exposes standard, OpenAPI-compliant endpoints. Your custom React, Vue, or Streamlit frontend can communicate with your agent exactly as it does today.
+* **Global Discoverability:** While you power your custom UI, the framework automatically registers your agent's OpenAPI schema to the DataHub Universal Registry. Engine A (the central mesh) can now discover and route relevant enterprise traffic to your endpoint, giving your domain expertise massive internal distribution for free.
+
+---
+
+## PART 3: SYSTEMS ARCHITECTURE (DoDAF VIEWS)
+
+### The OV-1: Operational Concept Graphic
+This diagram contrasts the high engineering burden of the DIY approach against the streamlined elegance of the Mesh ecosystem.
+
+```mermaid
+%%{init: {'theme': 'neutral'} }%%
+flowchart TD
+    classDef nightmare fill:#ffe6e6,stroke:#ff3333,stroke-width:2px,color:#990000;
+    classDef mesh fill:#e6f3ff,stroke:#3399ff,stroke-width:2px,color:#004c99;
+    classDef platform fill:#e6ffe6,stroke:#33cc33,stroke-width:2px,color:#006600;
+
+    subgraph DIY[The DIY Silo: High Engineering Burden]
+        DS1((Data Scientist)) --> API[Custom API Engine]
+        API --> Auth[Manual Token Middleware]:::nightmare
+        API --> Trace[Fragmented Local Logging]:::nightmare
+        API --> DBConn[Raw AWS/DB Connections]:::nightmare
+        Auth -.-> Risk[Compliance Violations]
+    end
+
+    subgraph MESH[The iagent Mesh Ecosystem]
+        DS2((Data Scientist)) --> Logic[AI Agent / Business Logic]
+        Logic --> MT[MeshTool Node Wrapper]:::mesh
+        
+        Orchestrator[Engine A: Central Orchestrator] == Authenticated Traffic ==> MT
+        
+        MT --> CDC[CortexDataClient]:::mesh
+        
+        Topaz[Zero-Trust Policies] -. Invisible Enforcement .-> MT:::platform
+        Langfuse[Distributed Tracing] -. Invisible Telemetry .-> MT:::platform
+    end
+
+    style DIY fill:#cccccc,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5
+    style MESH fill:#b8c8d8,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5
+```
+
+### The SV-1: Systems Interface Description
+How existing legacy architectures (LangChain/LlamaIndex) interface securely with the central orchestrator via structured passthrough.
+
+```mermaid
+%%{init: { 'sequence': { 'boxBorderColor': '#666', 'showSequenceNumbers': true } } }%%
+sequenceDiagram
+    autonumber
+    box rgba(0, 100, 255, 0.1) Platform Control Plane
+    participant U as Custom UI / User
+    participant EA as Engine A (Orchestrator)
+    end
+    
+    box rgba(0, 200, 0, 0.1) Domain Node (Data Science)
+    participant MT as MeshTool (Pydantic Ingress)
+    participant LR as Legacy Agent (LangChain/LlamaIndex)
+    end
+    
+    box rgba(255, 150, 0, 0.1) Platform Data Plane
+    participant DP as CortexDataClient
+    end
+
+    U->>EA: "Hey, check delays for supplier X and summarize"
+    Note over EA: Central LLM applies NLP Parsing<br/>& Intent Classification
+    EA->>MT: Validated Pydantic Object<br/>{intent: "delay_check", id: "X"}
+    MT->>LR: Clean Variables
+    Note over LR: Executes existing custom logic<br/>(No NLP parsing needed locally!)
+    LR->>DP: get_dataframe(urn:...)
+    DP-->>LR: RLS-Filtered Polars LazyFrame
+    LR-->>MT: Analysis Result
+    MT-->>EA: Standardized JSON Output
+    EA-->>U: Final Formatted Response
+```
+
+### The SV-4: Systems Functionality / Data Security Flow
+The invisible path of identity propagation ensuring every computation is grounded in verifiable enterprise access controls.
+
+```mermaid
+%%{init: {'theme': 'neutral'} }%%
+flowchart LR
+    classDef secure fill:#e8f4f8,stroke:#1b85b8,stroke-width:2px;
+    classDef compute fill:#f4e8f8,stroke:#851bb8,stroke-width:2px;
+    classDef data fill:#e8f8ec,stroke:#1bb845,stroke-width:2px;
+
+    User([User Session]) -- 1. Injects JWT --> Jupyter[Jupyter / UI]:::compute
+    Jupyter -- 2. mesh.ask() --> EngineA[Engine A]:::compute
+    EngineA -- 3. Forwards JWT Header --> MeshTool[MeshTool Node]:::compute
+    
+    subgraph Zero-Trust Perimeter
+        MeshTool -- 4. Request Asset --> Gateway[Central Data Gateway]:::secure
+        Gateway -- 5. Verify Token --> Keycloak[Keycloak IDP]:::secure
+        Gateway -- 6. Fetch Policies --> Topaz[AuthZ Engine]:::secure
+    end
+    
+    subgraph Enterprise Data Lake
+        Topaz -- 7. Apply RLS & Masking --> S3[(AWS S3 / Database)]:::data
+    end
+    
+    S3 -- 8. Mint STS & Stream Data --> MeshTool
+    
+    MeshTool --- Logic[Data Scientist safely computes<br/>on Polars LazyFrame]:::compute
+    
+    style Zero-Trust Perimeter fill:#c5d8e0,stroke:#1b85b8,stroke-dasharray: 5 5
+    style Enterprise Data Lake fill:#c5e0ca,stroke:#1bb845,stroke-dasharray: 5 5
+```
+
+---
+
+## THE VERDICT
+
+If you build your own orchestrator and API from scratch, you own the burden of distributed tracing, token rotation, data access policy enforcement, and proving your agents are trustworthy. 
+
+If you wrap your logic in `@app.execute()`, the Mesh handles 100% of the enterprise plumbing, ensuring your agents are traceable, predictable, observable, and grounded by default. 
+
+**Focus your talent on building superior agents and exceptional custom UIs. Let the Mesh handle the infrastructure.**