Repository navigation
docs, examples: add Private DIY Enterprise Stack example and embedded live workbench - #804
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces the Private DIY Enterprise Stack example, which demonstrates an air-gapped, zero-trust AI workforce using self-hosted reasoning models, an agent harness, and Agent Mesh sidecars. The feedback highlights several reliability and robustness issues across the newly added scripts: resource leaks (unclosed files in dashboard.py and unclosed SQLite connections), potential crashes (an IndexError on empty catalog lines and a sqlite3.OperationalError during database initialization), a violation of Section 6.3 of the style guide regarding swallowed exceptions in backends.py, and a lack of error handling in run.sh if peer discovery fails.
| for raw_line in open(p, errors="replace"): | ||
| line = raw_line.rstrip("\n") | ||
| m = audit_re.search(line) | ||
| if m: | ||
| try: | ||
| d = json.loads(m.group(1)) | ||
| except json.JSONDecodeError: | ||
| continue | ||
| who = f"{d.get('role') or '-'} ({d.get('peer_id', '')[:12]}…)" | ||
| what = " ".join(x for x in (d.get("method"), d.get("path")) if x) or d.get("protocol", "-") | ||
| events.append( | ||
| { | ||
| "decision": d.get("decision", "?").upper(), | ||
| "caller": who, | ||
| "method": what, | ||
| "service": d.get("target", "-"), | ||
| } | ||
| ) | ||
| continue | ||
| tm = tar_re.search(line) | ||
| if tm: | ||
| events.append( | ||
| { | ||
| "decision": "DENY", | ||
| "caller": f"tar_block ({tm.group(2)})", | ||
| "method": f"tools/call {tm.group(1)}", | ||
| "service": "mcp://erp-db", | ||
| } | ||
| ) |
There was a problem hiding this comment.
In parse_audit_events, the log files are opened using open(p, errors="replace") inside a loop without being explicitly closed or wrapped in a with statement. Since parse_audit_events is called on every /api/state request (which is polled frequently), this will quickly leak file descriptors and can lead to resource exhaustion (e.g., "Too many open files" error).
with open(p, errors="replace") as f:\n for raw_line in f:\n line = raw_line.rstrip("\\n")\n m = audit_re.search(line)\n if m:\n try:\n d = json.loads(m.group(1))\n except json.JSONDecodeError:\n continue\n who = f"{d.get('role') or '-'} ({d.get('peer_id', '')[:12]}…)"\n what = " ".join(x for x in (d.get("method"), d.get("path")) if x) or d.get("protocol", "-")\n events.append(\n {\n "decision": d.get("decision", "?").upper(),\n "caller": who,\n "method": what,\n "service": d.get("target", "-"),\n }\n )\n continue\n tm = tar_re.search(line)\n if tm:\n events.append(\n {\n "decision": "DENY",\n "caller": f"tar_block ({tm.group(2)})",\n "method": f"tools/call {tm.group(1)}",\n "service": "mcp://erp-db",\n }\n )| with urllib.request.urlopen(req, timeout=8) as resp: | ||
| return resp.read() | ||
| except Exception: | ||
| return None |
There was a problem hiding this comment.
According to the Repository Style Guide Section 6.3, errors should not be silently swallowed. In _try_upstream, any exception raised during the connection to the upstream Ollama server is caught and silently ignored by returning None. This makes it extremely difficult for operators to diagnose connection or configuration issues. Please log or print the exception before returning None.
with urllib.request.urlopen(req, timeout=8) as resp:\n return resp.read()\n except Exception as e:\n print(f"Upstream request failed: {e}", flush=True)\n return NoneReferences
- Section 6.3: Errors are not swallowed. Any exception caught during runtime operations should be logged or printed to ensure auditability.
| raw_catalog = sidecar.call_sidecar_tool("find_remote_tools", {"service_name": "erp-db"}) | ||
| catalog = json.loads(raw_catalog.splitlines()[-1]) |
There was a problem hiding this comment.
If raw_catalog is empty (e.g., if the tool call returns no content or fails), raw_catalog.splitlines() will be an empty list, and accessing [-1] will raise an IndexError, crashing the dashboard server. Please check if the list is non-empty before accessing the last element.
raw_catalog = sidecar.call_sidecar_tool("find_remote_tools", {"service_name": "erp-db"})\n lines = raw_catalog.splitlines()\n if not lines:\n return self._send_json({"error": "No tools discovered"}, status=500)\n catalog = json.loads(lines[-1])| if not os.path.exists(self.db_path): | ||
| return {"invoices_count": 0, "wire_transfers_count": 0} | ||
| conn = sqlite3.connect(self.db_path) | ||
| inv = conn.execute("SELECT COUNT(*) FROM invoices").fetchone()[0] | ||
| wires = conn.execute("SELECT COUNT(*) FROM wire_transfers").fetchone()[0] | ||
| conn.close() | ||
| return {"invoices_count": inv, "wire_transfers_count": wires} |
There was a problem hiding this comment.
If the SQLite database file exists but the tables (invoices or wire_transfers) have not been fully initialized yet by backends.py, conn.execute will raise a sqlite3.OperationalError. Since this method is called on every /api/state request, it can crash the dashboard. Additionally, if an exception is raised, conn.close() is bypassed, leaking the connection. Please wrap the execution in a try...except block and ensure the connection is closed.
if not os.path.exists(self.db_path):\n return {"invoices_count": 0, "wire_transfers_count": 0}\n conn = None\n try:\n conn = sqlite3.connect(self.db_path)\n inv = conn.execute("SELECT COUNT(*) FROM invoices").fetchone()[0]\n wires = conn.execute("SELECT COUNT(*) FROM wire_transfers").fetchone()[0]\n return {"invoices_count": inv, "wire_transfers_count": wires}\n except sqlite3.Error:\n return {"invoices_count": 0, "wire_transfers_count": 0}\n finally:\n if conn:\n conn.close()| if [[ -n "${VAULT_PEER}" && -n "${GPU_PEER}" ]]; then | ||
| break | ||
| fi | ||
| sleep 0.5 | ||
| done |
There was a problem hiding this comment.
If the discovery loop finishes without successfully finding VAULT_PEER or GPU_PEER, the script will continue with empty variables, leading to silent failures or cryptic errors in subsequent acts. Please verify that both peer IDs were successfully discovered and exit with an error if they are empty.
| if [[ -n "${VAULT_PEER}" && -n "${GPU_PEER}" ]]; then | |
| break | |
| fi | |
| sleep 0.5 | |
| done | |
| if [[ -n "${VAULT_PEER}" && -n "${GPU_PEER}" ]]; then\n break\n fi\n sleep 0.5\ndone\n\nif [[ -z "${VAULT_PEER}" || -z "${GPU_PEER}" ]]; then\n echo "Error: Failed to discover Vault Peer or GPU Peer within timeout." >&2\n exit 1\nfi |
870a0e1 to
0afecec
Compare
…mple and 3D live-execution walkthrough
0afecec to
f4f85e9
Compare
Summary
Adds a runnable end-to-end Private DIY Enterprise Stack (Safely On-Premises & in Cloud) example (
development/examples/private-diy-stack/), a 1080p 3D Live-Execution Architectural Walkthrough video (site/static/demo-private-diy-stack.mp4) rendered from a live run of the Agent Mesh Go binaries (render_3d_video.py), and a use-case guide (site/content/docs/use-cases/private-diy-stack.md) demonstrating how enterprises can run a zero-trust AI workforce safely across on-premises infrastructure and cloud (Cloud Run, GKE, or local servers) without site-to-site VPNs, inbound firewall holes, or raw credentials inside agent containers:inference://private-llm):Gemma 3/deepseek-r1:1.5bserved via Ollama, vLLM (on Cloud Run GPU, GKE, or on-prem GPUs), or the built-in OpenAI-compatible engine (backends.py).agent_harness.py): A zero-dependency Python ReAct harness that holds zero database credentials, zero API keys, and zero network routing logic—communicating strictly with its localagentmesh-nodesidecar over127.0.0.1:19101/mcpand127.0.0.1:19101/v1.agentmesh-one+agentmesh-node):node-tools.yaml(On-Prem Vault zone),node-inference.yaml(Cloud / On-Prem GPU zone), andnode-agent.yaml(Cloud Run / Workstation zone) and discoversmcp://erp-db,egress://compliance.internal, andinference://private-llmover Kademlia DHT / GossipSub.agent_harness.pyto audit an ERP invoice (INV-2026-089), check warehouse stock (SKU-GPU-H200), and verify vendor compliance (ACME-01) with node-side secret brokering (secrets/compliance-api-key) so on-prem secrets never leave the vault node.mcp://payroll-vault) hosted on the same Vault node (biscuit: denied by no matching policies).POST /v1/vendors/ACME-01->HTTP 403).check if label("residency", "on-prem");andcheck if label("dept", "finance");), rejecting callers fromdept=external.tar_block) via RFC 8693POST /oauth/tokennarrowed to read-only tools (lookup_invoice,check_inventory), blocking prompt-injectedexecute_wire_transfercalls before they reach SQLite.ALLOW/DENYdecisions across sidecars (audit.py) and revokes the unauthorized external peer mesh-wide viaagentmesh-one admin ban.3D Live-Execution Walkthrough & Local Browser Workbench
site/static/demo-private-diy-stack.mp4): Embedded at the top of/docs/use-cases/private-diy-stack/. Generated byrender_3d_video.py(make -C development/examples/private-diy-stack record), which boots the realagentmesh-onecontrol plane and fouragentmesh-nodesidecars, executes all 4 acts against the live Go binaries, and renders a 1920x1080 30fps 3D perspective architectural animation synchronized with the real Peer IDs, SQLite outputs, Biscuit Datalog denials, and audit logs.dashboard.py): Launchingmake -C development/examples/private-diy-stack uistarts a live local web workbench onhttp://127.0.0.1:18899backed directly by the runningagentmesh-oneandagentmesh-nodeprocesses.Verification
make -C development/examples/private-diy-stack run(runs all 4 acts headlessly in ~12s)make -C development/examples/private-diy-stack ui(launches the live local browser workbench onhttp://127.0.0.1:18899)make -C development/examples/private-diy-stack record(re-records the 1080p 3D live-execution walkthroughsite/static/demo-private-diy-stack.mp4)