How chain-ml/council works
Main Components
• LLM Interface Module – Represented by the “council/llm” directory and its subdirectories. This includes the base classes, configurations, message formatting, and integrations with provider-specific implementations (e.g., OpenAI, Anthropic, Gemini, Groq, Ollama).
• Agents and Agent Tests – Under “council/agents” and “council/agent_tests”. These represent the autonomous agents that carry out tasks using LLM interactions.
• Chains – In “council/chains”. This module relates to constructing multi-step workflows (chains) that the agents execute.
• Contexts – In “council/contexts”. This manages runtime contexts such as conversation histories, budgets, logging, and execution contexts. It’s critical for maintaining state and enforcing controls.
• Controllers – Under “council/controllers”. They orchestrate how agents and chains are executed and provide control flow capabilities.
• Evaluators & Scorers – Found in “council/evaluators” and “council/scorers”. These components are responsible for evaluating LLM outputs, scoring responses, and ensuring quality.
• Filters – In “council/filters”. They perform pre- and post-processing to clean or filter out unwanted content.
• Skills – Under “council/skills”. This directory encapsulates additional functionalities (like Google search integration, Python coding skills, Wikipedia queries, etc.) that extend the core agent capabilities.
• Runners – Located in “council/runners”. They execute different control flow logic, such as loop runners, conditional and parallel execution strategies.
• Prompts – In “council/prompt”. This module handles prompt building, dataset management, and configuration of LLM prompt templates.
• Auxiliary Modules – “council/utils” for helper utilities and “council/mocks” for testing support.
Establish Relationships and Interactions
• That Controllers drive the overall execution by managing both agents and chains, connecting to both.
• That Filters wrap around LLM responses or agent outputs before final delivery.
• For Skills, show that they extend agents’ capabilities, with connections both toward the Agents module and the external service integrations.
• The Prompts module should be presented as the preparatory layer that feeds into the LLM interface when constructing requests.
Architectural Patterns and Design Principles
• Clearly separate concerns by grouping similar modules together (for example, all control-flow related components – controllers, runners, contexts – on one side and the LLM/provider abstractions on the other).
• Modular design, illustrating the Strategy pattern used for choosing the appropriate LLM provider dynamically.
• Use dependency inversion concepts where core modules (like Agents and Controllers) depend on abstract interfaces (as seen in the base classes in many packages) rather than concrete implementations.
• Elements of enterprise-grade monitoring and error handling, as indicated by the built-in retry mechanisms and monitoring modules.
Relevant Technologies and Frameworks
• That it’s a Python-based project.
• That integrations with external LLM providers (OpenAI, Anthropic, etc.) are performed through dedicated provider modules.
• Mention the use of configuration files (YAML in docs/data/configs) that help in parameterizing the LLM calls.
• Testing frameworks and CI/CD integration (GitHub Workflows like linting, testing, docs build) as ancillary but important for overall system integrity.
Additional Elements
• Use callout annotations to indicate how configuration, error handling, and retry mechanisms operate within modules.