pal-e-docs

Domain Model: pal-e-pac

arch-domain-pal-e-pac Architecture

architecture
Project

Domain Model

The system entities and their relationships. Answers: what are the components of the sovereign development experience and how do they compose?

Key relationships

  • StateGraph (LangGraph) is the orchestration engine. Replaces Goose. The graph defines a deterministic flow: route → select tool → correct params → safety check → call MCP → respond. The model fills in slots, it does not decide the path. pac CLI (typer + rich + prompt_toolkit) wraps the graph.
  • Router classifies user intent into an MCP domain (Forgejo, pal-e-docs, Woodpecker). Reduces the tool search space from 60+ to 5-8 per domain. Addresses Qwen3-4B's cross-server confusion.
  • ParamCorrector fixes known hallucination patterns before MCP calls. E.g. owner=pal-e → owner=forgejo_admin, pal_e_docs__search → search_notes. Data-driven corrections from Phase 3 baseline failures.
  • MCPAdapter (langchain-mcp-adapters) bridges existing MCP servers to LangChain tools. Our MCP servers are unchanged — same forgejo-mcp, pal-e-docs-mcp, woodpecker-mcp used by Claude Code.
  • ModelBackend (Ollama) serves LLM inference on local GPU. Connected via port-forward from localhost:11434 to the k8s Ollama service.
  • Model is the actual LLM. Three tiers: Qwen3-4B (always fits in 8GB VRAM), Qwen3-8B (fits when embedding model paused), Claude API (external fallback).
  • PromptLibrary holds per-role system prompts and role-specific tool subsets (YAML configs). Derived from existing agent .md files in claude-custom.
  • BenchmarkSuite (promptfoo) evaluates prompts against models. 29 test cases across 8 categories. Claude Opus scored 97, Qwen3-4B scored 28. Drives prompt iteration.
  • SafetyNode is a graph node that gates tool calls using permissions.yaml (reused from Phase 2). Every tool call passes through before MCP execution.