product-architecture-qa.txt

AIGuardian: Product Architecture and Direction Q&A
Date: 2026-03-08

============================================================
PART 1: UNDERSTANDING BEFORE THE Q&A
============================================================

What AIGuardian is:
- A C++17 runtime guard for AI agent tool calls.
- It intercepts every tool call an AI agent wants to make,
  checks it against a policy graph, optionally sandboxes
  the execution, logs everything, and returns approved/blocked.

Four components (from product-positioning-and-use-cases.txt):
1) Policy control plane    — author and version policy JSON files
2) Enforcement SDK/gateway — the C++ core: intercept, validate, audit
3) Sandbox runner          — WasmEdge-first, container fallback on roadmap
4) Audit/incident UI       — replay, explainability, compliance export
                             (the missing piece today)

What is built and solid:
- PolicyGraph: directed graph loaded from JSON, nodes = tools,
  edges = permitted transitions
- PolicyValidator: transition check, cycle detection, exfiltration
  detection, LRU result cache
- SessionManager: per-session call history that feeds each decision
- SandboxManager: WasmEdge runtime + MockRuntime for testing
- ToolInterceptor: coordinates validate → sandbox → log → session update
- Logger: level filtering, in-memory store, JSON export, file output
- VisualizationEngine: DOT graph, ASCII graph, ASCII sequence with
  APPROVED/BLOCKED summary

How a call flows today:
1) create_session() once
2) For each tool call: intercept(session_id, tool_name, params)
3) Reads prior session history
4) Policy decision (transition + cycle + exfiltration checks)
5) If approved: sandbox executes (Wasm or mock)
6) Session updated, result returned
7) Next call uses updated session history

Known bug noted before Q&A:
- Approved calls are appended to session even if sandbox execution
  fails. This means next decision treats a failed execution as valid
  progression. Fix: append only on sandbox success, or store
  call status (approved/executed/failed) and validate against
  executed calls only.


============================================================
PART 2: Q&A — PRODUCT DIRECTION AND ARCHITECTURE
============================================================

Q1: Is this a library that users include while writing AI models?
    And who codes models in C++?

A: Technically yes, that is what it is today — a C++ library you
   link against. But almost nobody writes AI agents in C++.
   The agent development world is Python (LangChain, LlamaIndex,
   AutoGen, CrewAI, OpenAI function calling) and TypeScript.

   So a raw C++ library has a very narrow direct audience.
   The missing layer is a usable surface for Python/HTTP users:
   - REST/gRPC gateway (language-agnostic, any agent calls an
     HTTP endpoint before executing a tool)
   - Python bindings via pybind11 (so LangChain agents call
     guardian.intercept() directly in-process)
   - Sidecar proxy (Guardian sits between the agent runtime and
     its tools, calls are impossible to bypass)

   The C++ core is the right foundation for performance and
   correctness. It just needs a wrapper layer that doesn't exist yet.


Q2: What is compiled to Wasm? Is it C++ or Python or anything?

A: Wasm is a compilation target, not a language. It is a binary
   instruction format. Languages that compile to it:
   - C/C++ via wasi-sdk or Emscripten
   - Rust (best-in-class support, primary real-world use case)
   - AssemblyScript (TypeScript-like, designed for Wasm)
   - Go (experimental/limited)
   - Python: NO — Pyodide bundles the full CPython interpreter
     (~30MB), not usable for per-call sandboxing

   In Guardian's context: Guardian itself stays native C++.
   Only the TOOL IMPLEMENTATIONS are compiled to .wasm.
   Whoever writes "generate_report" writes it in C, C++, or Rust,
   compiles it to generate_report.wasm, and hands Guardian the binary.
   Guardian loads and executes it inside WasmEdge with the configured
   memory cap, timeout, path restrictions, and network flag.

   Python cannot be practically compiled to Wasm for real tool
   workloads. HTTP calls (socket operations) cannot be meaningfully
   sandboxed inside Wasm either — you get allow-all or deny-all
   network access per module, not per-URL control.


Q3: Which integration option is best — SDK, gateway, or sidecar?

A: Summary of all three:

   Option A — REST Gateway (language-agnostic):
   Guardian runs as an HTTP service. Python/TS agents POST to
   /intercept before calling any tool. Guardian returns
   approved or blocked.
   Best for: enterprise deployment, security team owns Guardian
   independently of the app team.
   Downside: network hop on every call, latency budget matters.

   Option B — Python bindings (pybind11):
   Guardian C++ core is wrapped so Python calls it in-process.
   No network hop, microsecond overhead vs millisecond HTTP.
   Best for: Python-first teams, lowest integration friction,
   works directly inside LangChain/AutoGen tools.
   Downside: requires building and distributing Python wheel
   packages per Python version and OS.

   Option C — Sidecar proxy:
   Guardian runs next to the agent. Agent cannot call tools
   directly at all — all calls go through Guardian which calls
   the tool on the agent's behalf.
   Best for: production deployments where bypass must be
   architecturally impossible. Security owns the sidecar.
   Downside: most complex to deploy and operate.

   Best next step for this project:
   Option B (Python bindings) is the most impactful immediate move.
   The C++ core is done, Python is where agent frameworks live,
   pybind11 is a proven pattern (numpy, PyTorch, OpenCV use it),
   and it enables demos inside real LangChain/AutoGen agents.

   Longer term for enterprise sales: Option A (REST gateway) is
   what security teams want to deploy independently.


Q4: Is the sandbox useless because .wasm tools are rare?
    Will a call fail and error if the tool can't be sandboxed?

A: The sandbox is limited in real-world coverage today — yes.
   But it is not what makes the product valuable.

   Current behavior from the code:
   - If SandboxManager is not attached at all: policy validation
     still works, call proceeds if policy approves it.
     Sandbox is optional.
   - If SandboxManager is attached but tool has no .wasm loaded:
     execute_tool() returns success=false with error
     "module not loaded: <tool_name>". The call then fails.
     This is a real gap for non-Wasm tools.

   The actual value of Guardian is in the POLICY VALIDATION LAYER:
   blocking exfiltration paths, detecting call loops, enforcing
   permitted call sequences. That is entirely independent of Wasm.
   Strip the sandbox and you still have a meaningful product —
   you lose runtime isolation but keep all the policy enforcement.

   Fix needed: when a tool has no .wasm registered, the behavior
   should be configurable:
   - WARN_AND_ALLOW: log warning, proceed (for gradual rollout)
   - DENY: block the call if no sandbox is registered (strict mode)
   Not a hard error.

   Realistic sandbox coverage by tool type:
   - C/C++/Rust deterministic utility tools → WasmEdge (current)
   - Python functions and LLM calls        → Docker container (roadmap)
   - HTTP API calls                        → Policy-graph allow/deny (current)
                                             + network policy
   - Shell commands                        → seccomp/AppArmor (future)


Q5: Who builds a C++ library? That makes it impossible to use.

A: Nobody coding AI agents does. That is correct.

   But the C++ core is not meant to be used directly by AI
   developers. It is infrastructure — like MySQL (C core,
   Python drivers on top) or OpenSSL (C library, ssl/cryptography
   Python wrappers on top).

   Reasons the engine is C++:
   - Sub-millisecond policy validation (graph traversal, LRU cache)
   - Thread-safe session management without GIL constraints
   - WasmEdge integration (itself a C++ runtime)
   - Predictable memory and latency characteristics

   These are legitimate reasons. The problem is that the wrapper
   layer that Python/TypeScript developers would actually touch does
   not exist yet. That is the most important missing piece for
   real-world adoption.

   The product is not useless — it is incomplete at the integration
   layer. The core is solid.


============================================================
PART 3: WHAT NEEDS TO BE BUILT NEXT (PRIORITY ORDER)
============================================================

Immediate (low cost, high value):
1. Fix session-append-on-success bug in tool_interceptor.cpp
2. Add sandbox fallback config (WARN_AND_ALLOW vs DENY when
   no .wasm is registered for a tool)
3. Add developer-assistant approval-workflow policy example:
   read_code → approval_request → deploy_production

Medium term (highest adoption impact):
4. Python bindings via pybind11 wrapping Guardian::intercept(),
   covering the create_session / intercept / get_audit_log surface
5. Minimal HTTP API layer (cpp-httplib or Crow) so any language
   can use Guardian as a gateway

Longer term:
6. Docker/K8s container runner fallback (Phase B sandbox)
7. Audit/incident web UI: live agent timeline, animated graph
   traversal, session replay, explainability panel
8. NeMo Guardrails integration (NeMo handles LLM flow,
   Guardian handles tool execution — complementary layers)
9. Policy control plane UI (author/version policies, not raw JSON)

Positioning (from product-positioning-and-use-cases.txt):
- "Guardian secures agent tool execution with policy validation
  and sandboxed runtime controls."
- Wasm-first for tools that support it; container fallback on roadmap.
- Do NOT claim universal OS syscall sandboxing.
- OS-specific behavior depends on host runner.
- Lead demos with enterprise exfiltration and approval workflows,
  not toy scenarios.