Skip to content

Latest commit

 

History

History
98 lines (68 loc) · 6.82 KB

core_components.md

File metadata and controls

98 lines (68 loc) · 6.82 KB

Core Components Guide

This document provides a detailed overview of the primary functional components that power the cli_engineer application. These components work together to form the agentic loop responsible for interpreting tasks, planning, execution, and review.

Table of Contents

  1. Interpreter (interpreter.rs)
  2. Planner (planner.rs)
  3. Executor (executor.rs)
  4. Reviewer (reviewer.rs)
  5. Agentic Loop (agentic_loop.rs)
  6. Context Manager (context.rs)
  7. Artifact Manager (artifact.rs)
  8. Event Bus (event_bus.rs)

1. Interpreter (interpreter.rs)

The Interpreter is the initial entry point for any user request. Its primary responsibility is to take a raw, unstructured text prompt from the user and convert it into a structured Task object.

  • Key Structs: Interpreter, Task
  • Core Logic: The interpret method analyzes the input string for keywords (e.g., "create", "fix", "test") to determine a high-level goal for the agent.
  • Functionality: It standardizes the user's request, providing a clear description and goal that the rest of the system can understand and act upon.
// src/interpreter.rs
pub struct Task {
    pub description: String,
    pub goal: String,
}

pub struct Interpreter;

impl Interpreter {
    pub fn interpret(&self, input: &str) -> Result<Task> {
        // ... logic to parse input and create a Task
    }
}

2. Planner (planner.rs)

The Planner acts as the "brain" or "architect" of the agent. It takes the structured Task from the Interpreter and formulates a detailed, step-by-step plan to achieve the task's goal.

  • Key Structs: Planner, Plan, Step
  • Core Logic: The plan method constructs a detailed prompt for an LLM, including the task goal and the current iteration's context (e.g., existing files, previous review feedback). It then parses the LLM's response into a Plan object, which is a list of categorized Steps.
  • Functionality: It breaks down a complex problem into a sequence of manageable, actionable steps. This structured plan guides the Executor and ensures the agent's actions are logical and progressive.

3. Executor (executor.rs)

The Executor is the "hands" of the agent. It is responsible for carrying out each step of the Plan generated by the Planner.

  • Key Structs: Executor, StepResult
  • Core Logic: The execute method iterates through the plan's steps. For each step, execute_step builds a specific prompt based on the step's category (e.g., CodeGeneration, FileOperation) and sends it to the LLM. It then uses the extract_code_artifacts helper to parse the LLM's response, find code blocks wrapped in <artifact> tags, and save them as files using the ArtifactManager.
  • Functionality: It translates the abstract plan into concrete actions, generating code, modifying files, and producing the tangible outputs of the agent's work.

4. Reviewer (reviewer.rs)

The Reviewer serves as the quality assurance (QA) component of the agent. After the Executor completes a plan, the Reviewer evaluates the results to determine if the task has been successfully completed.

  • Key Structs: Reviewer, ReviewResult, Issue
  • Core Logic: The review method gathers the results from the Executor, constructs a prompt asking an LLM to perform a code review, and parses the response into a ReviewResult. This result includes an overall quality assessment, a list of specific issues, and a determination of whether the code is "ready to deploy."
  • Functionality: It closes the agentic loop by providing critical feedback. If issues are found, this feedback is passed to the Planner for the next iteration, enabling the agent to self-correct and improve its work.

5. Agentic Loop (agentic_loop.rs)

The AgenticLoop orchestrates the entire process, controlling the iterative cycle of planning, execution, and review.

  • Core Logic: The run method is the main driver. It initializes the loop and continues to execute iterations until the task is complete (ready_to_deploy is true) or the maximum number of iterations is reached.
  • The Cycle:
    1. Plan: Calls the Planner to create a plan.
    2. Execute: Passes the plan to the Executor.
    3. Review: Sends the execution results to the Reviewer.
    4. Iterate: If the review finds issues, it feeds the results back into a new IterationContext and starts the loop again.

6. Context Manager (context.rs)

The ContextManager is responsible for managing the agent's memory, which is crucial for maintaining state across multiple LLM calls and iterations.

  • Key Structs: ContextManager, ConversationContext, Message
  • Core Logic: It stores a history of all interactions (prompts and responses) in a ConversationContext. Its most critical feature is compress_context, which is triggered when the token count approaches the LLM's limit. This function uses an LLM to summarize older parts of the conversation, preserving key information while freeing up tokens.
  • Functionality: It solves the problem of limited LLM context windows, enabling the agent to handle complex, multi-step tasks that require a long history of interactions.

7. Artifact Manager (artifact.rs)

The ArtifactManager handles all file system operations for the agent. It ensures that all generated files are created, tracked, and stored correctly.

  • Key Structs: ArtifactManager, Artifact, ArtifactManifest
  • Core Logic: The create_artifact method writes content to a file within the designated artifacts directory. It also maintains a manifest.json file, which keeps a record of all artifacts created during a session.
  • Functionality: It provides a safe and organized way for the agent to interact with the file system, abstracting away the details of file I/O and providing a clean record of all outputs.

8. Event Bus (event_bus.rs)

The EventBus is the central nervous system of the application, enabling decoupled communication between all the different components.

  • Key Structs: EventBus, Event (enum)
  • Core Logic: It uses a broadcast channel to send Events. Components don't call each other directly; instead, they emit events like TaskStarted, APICallCompleted, or ArtifactCreated. Other components, such as the UI, subscribe to the bus and listen for events to update their state.
  • Functionality: This event-driven architecture makes the system highly modular and extensible. New components can be added to listen or emit events without modifying existing components. It's what allows the dashboard UI to display real-time metrics and logs.