How lucasdoreac/ludoc works
1. Repository shape
- This repo is centered on a single Python agent service under src/agent, plus Kubernetes packaging under deploy/ and a small companion mock API under src/mock_records.
- The root kustomization.yaml and deploy/overlays/default indicate the project is meant to be deployed as a clusterized local-first service, not just run as a library.
2. Primary runtime: Ludoc agent
- src/agent/server.py is the main entrypoint and orchestration boundary. It exposes the agent over HTTP and serves the tool/protocol endpoints described in the README.
- The service is built around FastMCP/Starlette/Uvicorn-style hosting, with endpoints for health, skill discovery, MCP tool listing/calls, chat execution, and ACP-style agent communication.
3. Agent execution model
- The core behavior is an Actor-Critic loop: the “Actor” performs task execution, while the “Critic” validates risky changes, especially Python edits.
- This split is important architecturally because validation is not embedded inside each skill; it is a cross-cutting gate around code mutation and execution.
4. Model integration
- src/agent/llm.py is the model-adapter layer, connecting the agent to local Ollama-hosted models.
- The README shows two distinct model roles: a reasoning/planning model (“Thinker”) and a coding/execution model (“Actor”), so the service likely routes different prompts to different models depending on task phase.
5. Context and relevance filtering
- src/agent/cleaner.py suggests a pre-prompt context reduction step that trims or prioritizes workspace/project content before sending it to the model.
- This is a separate boundary from execution: the cleaner shapes what the model sees, while the executor handles the actual tool use.
6. Dynamic tool system
- src/agent/skills/ is the main capability catalog. Each skill is defined as a Markdown file, which makes tools dynamically discoverable rather than hardcoded.
- The skills cover file I/O, shell execution, Python execution, validation, memory, search, git, web fetch/search, analysis, and document generation. This means the agent is effectively a tool router over a runtime-loaded skill registry.
7. Security and guardrails
- The architecture includes explicit security boundaries: path traversal protection, HITL approval for dangerous shell commands, and non-root execution in deployment.
- The practical implication for diagrams is that shell/file skills are not free-form; they pass through validation gates before they can touch the workspace or host environment.
8. Workspace and persistence
- The README describes a sandboxed working area at /tmp/workspace, which is the main mutable execution boundary for the agent.
- Semantic memory is file-based in repo-root docs like SKILL.md and CONTEXT.md, while episodic/learning state is described as distilled into additional markdown artifacts. This makes the repo itself part of the agent’s memory model.
9. External/local dependencies
- The agent is designed for local-only inference via Ollama, so the model backend is an internal service dependency rather than a cloud API.
- The src/mock_records service is a separate mock backend used for development/testing; it likely supplies synthetic records data for skills or workflows that need an external data source.
10. Deployment packaging
- deploy/base contains Kubernetes resources for the agent, config, and persistent storage, while deploy/overlays/default provides environment-specific composition via Kustomize.
- The presence of a PVC and config maps means the deployment expects both stateful storage and runtime configuration to be injected at cluster startup.
11. Validation and operational workflow
- grounding-check.ps1 and scripts/deploy-client.sh indicate the repo includes operational validation and deployment helpers, not just source code.
- The validation flow is likely: deploy agent, verify health/skills/tool endpoints, and exercise tool execution paths to ensure the service and its skill catalog are correctly wired.
12. How to draw the architecture
- A good diagram should show: user/client requests entering ludoc-agent; the server dispatching to MCP/ACP/chat handlers; the handler selecting a skill; the skill operating in the workspace; and guardrails/critic validation wrapping mutations.
- Separately, show the model backend (Ollama) as an internal dependency, the mock records API as an optional local external service, and Kubernetes config/PVC as the deployment substrate.
Main entry points: skills Skill registry · server.py Agent server · kustomization.yaml Default overlay · llm.py LLM adapter
Components 26
Agent runtime
HTTP entrypoint, model/context handling, execution loop, and workspace boundary.
- Agent server · Main service boundary exposing health, MCP/ACP, chat, and tool dispatch.
src/agent/server.py - Protocol API · Request handling for health, discovery, tool calls, chat, and agent messaging.
- Actor loop · Task execution path that selects and runs skills against the workspace.
- Critic gate · Cross-cutting review path that blocks risky or invalid code mutations.
- Context cleaner · Reduces and prioritizes workspace context before model prompts.
src/agent/cleaner.py - LLM adapter · Connects the agent to local Ollama-hosted reasoning and coding models.
src/agent/llm.py
Skill system
Dynamic capability catalog loaded from Markdown skill definitions.
- Skill registry · Loads skills from Markdown definitions and exposes them to the agent.
src/agent/skills - Read file · Reads repository and workspace files safely.
src/agent/skills/fs_read/skill.md - Edit file · Mutates files inside the sandboxed workspace.
src/agent/skills/fs_edit/skill.md - Shell exec · Runs shell commands with approval and guardrails for dangerous actions.
src/agent/skills/execute_shell/skill.md - Python exec · Executes Python for agent-side scripting and transformations.
src/agent/skills/python_interpreter/skill.md - Code validate · Validates code changes before mutation or release of risky actions.
src/agent/skills/validate_code/skill.md - Memory I/O · Reads and writes persistent markdown-based agent memory and notes.
src/agent/skills/memory_get/skill.md - Web IO · Searches and fetches web content when the task needs outside information.
src/agent/skills/web_search/skill.md - Git ops · Interacts with repository history and diffs as part of agent work.
src/agent/skills/git/skill.md - Analysis tools · Performs dependency and security analysis over repository structure and code.
src/agent/skills/analyze_dependency_graph/skill.md - Docs tools · Produces distilled notes, plans, and brand or task documents.
src/agent/skills/distill_experience/skill.md
Kubernetes deployment
Cluster packaging, storage, and environment composition.
- Root kustomize · Top-level Kustomize entry that assembles the deployment.
kustomization.yaml - Default overlay · Environment-specific Kustomize overlay for the default deployment.
deploy/overlays/default/kustomization.yaml - Agent manifest · Kubernetes workload definition for the Ludoc agent service.
deploy/base/ludoc-agent.yaml - Workspace PVC · Persistent volume claim backing the agent workspace and state.
deploy/base/ludoc-pvc.yaml
Local services
Internal or companion services the agent depends on at runtime.
- Workspace · Mutable execution boundary for files, edits, and generated artifacts.
- Ollama · Local inference backend used by the agent for reasoning and code work.
- Mock records API · Companion synthetic records service for local development and workflows.
src/mock_records/api.py
Ops tooling
Scripts and checks used to deploy and validate the stack.
- Deploy client · Helper script for deploying or exercising the client-side workflow.
scripts/deploy-client.sh - Grounding check · Operational validation script for deployment and endpoint wiring.
grounding-check.ps1
Connections 30
- Root kustomize → Default overlay: composes · Top-level deployment assembly flows into the default overlay.
- Default overlay → Agent manifest: includes · Overlay pulls in the agent workload and base resources.
- Default overlay → Workspace PVC: binds storage · Deployment composition attaches workspace persistence.
- Agent server → Protocol API: exposes · Server presents health, discovery, tool, chat, and agent endpoints.
- Protocol API → Skill registry: dispatches · Handlers resolve tool names and route requests to registered skills.
- Agent server → Context cleaner: prepares context · Requests are trimmed before prompt assembly and execution.
- Agent server → LLM adapter: calls models · Server hands planning and coding phases to the model adapter.
- LLM adapter → Ollama: uses · Model adapter sends prompts to the local inference backend.
- Agent server → Actor loop: runs · Execution requests enter the actor side of the loop.
- Actor loop → Critic gate: checks · Risky actions and mutations are routed through critic validation.
- Critic gate → Code validate: invokes · Critic relies on validation skill for code and change review.
- Actor loop → Skill registry: selects skills · The executor chooses capabilities from the dynamic skill catalog.
- Skill registry → Read file: includes · Registry exposes file reading as a core workspace capability.
- Skill registry → Edit file: includes · Registry exposes file editing for controlled mutations.
- Skill registry → Shell exec: includes · Registry exposes shell execution with approval controls.
- Skill registry → Python exec: includes · Registry exposes Python execution for agent-side logic.
- Skill registry → Memory I/O: includes · Registry exposes persistent memory read/write operations.
- Skill registry → Web IO: includes · Registry exposes search and fetch for outside information.
- Skill registry → Git ops: includes · Registry exposes repository history and diff operations.
- Skill registry → Analysis tools: includes · Registry exposes dependency and security analysis tools.
- Skill registry → Docs tools: includes · Registry exposes markdown note and document generation skills.
- Read file → Workspace: reads · File access is constrained to the sandboxed workspace.
- Edit file → Workspace: writes · Edits are applied inside the mutable workspace boundary.
- Shell exec → Workspace: operates in · Shell commands act on the workspace and approved paths.
- Python exec → Workspace: operates in · Python execution is used to inspect or transform workspace state.
- Git ops → Workspace: tracks · Version-control operations reflect changes in the workspace.
- Memory I/O → Workspace: persists to · Memory artifacts are stored alongside repo-based state.
- Mock records API → Agent server: feeds dev data · Companion backend can be exercised by the agent during local workflows.
- Deploy client → Root kustomize: deploys · Helper script uses the Kustomize stack for local deployment.
- Grounding check → Agent server: verifies · Validation checks target health and tool wiring on the running service.