How meta-introspector/lang_agent works
Project type and purpose
• This is an open-source “language agent” toolkit written in OCaml.
• It provides a collection of command-line tools (under bin/) that orchestrate various prompt-based tasks (dungeon generation, poem writing, grammar parsing, etc.) by calling out to LLM back-ends (OpenAI, Huggingface, Ollama, local LlamaCpp).
• It also bundles Coq files (_CoqProject/) and grammar definitions (grammars/) for proof-oriented or parsing tasks.
High-level components
a. CLI Drivers (bin/)
• Each executable script (chunker.ml, generate_dungeon.ml, scanner.ml, …) is a thin “driver” that invokes core APIs.
b. Core Library (lib/)
• Domain modules (Lang_model, Model_type, Mythos, Embody, CoqOfOCaml, etc.)
• Parsers and grammar runners (Yojson, BNF definitions)
• File-IO and utility modules (folder.ml, unix_handling.ml, StdLib)
c. LLM Adapters
• openai_client.ml – HTTP to OpenAI
• llama_cpp.ml – local C bindings
• ollama.ml / ollama_lwt.ml – Docker or local Ollama interface
d. Data & Grammar Assets
• grammars/ – .gbnf, .mly definitions
• data/huggingface_lang_agent – model weights or snapshot data
e. Build & DevOps
• Dune files, opam (lang_agent.opam), flake.nix, shell.nix
• Dockerfile, Makefile, build scripts (build.sh, build_push.sh)
• CI workflows (.github/workflows/docker-image.yml)
f. Tests
• test/ – test_lang_agent.ml
• script wrappers (test.sh, run_example*.sh)
Relationships & data flows
• The CLI Drivers layer calls into the Core Library API.
• Core Library dispatches to one or more LLM Adapters based on configuration (env vars, flags).
• LLM Adapters communicate over HTTP or FFI to External Services (OpenAI, Huggingface Inference API, Ollama server, local LlamaCpp).
• Responses flow back to Core Library, which may pass them through Grammar Modules for parsing or Coq modules for proof verification.
• Results are then written to stdout or to files in the workspace.
• Build & DevOps components orchestrate compilation (Dune/Nix), packaging (Docker), and CI runs.
Architectural patterns & principles
• Hexagonal (“ports and adapters”) architecture: separate domain logic (lib/) from IO concerns (LLM adapters, file handling, CLI).
• Modular design: each bin/ script is a composition of reusable library functions and adapters.
• Extensibility: adding a new LLM back-end only requires writing a new adapter module and wiring it into the dispatch logic.
• Declarative build: Dune + Nix + Docker provide consistent environments for reproducible builds and CI.
Essential detail checklist
• Bin/ scripts as entry-points
• lib/ modules as core domain
• Adapters to each LLM back-end
• grammars/ and data/ as resource stores
• External LLM services vs. local libraries
• Build & CI (Dune, Nix, Docker, GitHub Actions)
• Testing harness and sample workflows (test/, run_example*.sh)