Project Structure & Key Components

Cleo is organized into a modular and scalable codebase that encourages clean separation of concerns, easy extensibility, and straightforward maintenance. This page outlines the primary components of the project and explains how they interact to deliver intelligent agent functionality.

---

Directory Overview

Below is the top-level directory structure of the project:

bashCopyEditCleo/
├── agents/               # Agent profiles and configuration
├── core/                 # Core logic: task engine, routing, memory
├── tools/                # Pluggable tools for agent capabilities
├── config/               # Environment and system configuration
├── tests/                # Unit and integration tests
├── .env.example          # Environment variable template
├── main.py               # Entry point to launch Cleo
├── requirements.txt      # Core dependencies
└── README.md

---

Core Modules

/core/

This is the heart of Cleo’s execution engine.

• engine.py: Manages agent task execution loop, event lifecycle, and recovery.

• router.py: Routes commands and tasks to the appropriate tool or function.

• memory.py: Handles storage and retrieval of long-term memory using vector stores.

• context.py: Builds runtime context based on recent interactions and external data.

Example:

pythonCopyEditfrom core.router import CommandRouter

router = CommandRouter()
response = router.route("Search recent papers on quantum error correction")

---

Agents

/agents/

Each agent is defined by a JSON or Python configuration file specifying its:

• Name and persona

• Capabilities (tools, access level)

• Memory preferences

• Default prompt behavior

Example:

jsonCopyEdit{
  "name": "Atlas",
  "persona": "Research Assistant",
  "tools": ["WebScraper", "Summarizer", "PDFReader"],
  "memory": true
}

Agents can be hot-loaded from this directory or initialized programmatically using the Agent class.

---

Tools

/tools/

The tools system is Cleo’s capability layer. Tools are self-contained classes or modules that perform defined actions such as scraping, summarizing, parsing, or interacting with APIs.

A tool must follow a standard structure:

pythonCopyEditclass WebScraper:
    def run(self, query: str) -> str:
        # Implementation
        return scraped_text

Tool discovery is dynamic. New tools added to the tools/ directory are registered automatically if they follow naming conventions.

---

Configuration

/config/

Stores runtime settings, agent presets, and custom routing logic. Future support includes plug-and-play modules for:

• API connectors

• Authentication layers

• Task chaining templates

This directory centralizes all non-code customization to simplify deployment and collaboration.

---

Entry Point

main.py

The project’s primary entry point. It initializes environment variables, loads default agents, and starts the main interaction loop.

pythonCopyEditif __name__ == "__main__":
    from agents import load_default_agent
    agent = load_default_agent()
    agent.run_loop()

In future releases, main.py will support CLI arguments for specifying agent names, task files, and runtime modes.

---

Testing

/tests/

This folder includes unit and integration tests, covering:

• Tool reliability

• Agent behavior

• Task execution pipeline

Run the full test suite with:

bashCopyEditpytest tests/

---

Extending Cleo

Cleo is built to evolve. You can:

• Add tools by creating new modules in tools/

• Define new agents in the agents/ folder

• Integrate APIs by writing handlers and registering them with the router

• Swap memory backends by extending core.memory.MemoryInterface

Following SOLID principles and a decoupled architecture, Cleo allows experimentation without introducing system-wide dependencies.