Local Deployment

Running Cleo locally is ideal for development, agent design, tool testing, and iterative prototyping. This guide covers everything needed to clone the project, configure your environment, and start building with agents on your own machine.

---

Prerequisites

Before deploying Cleo locally, ensure the following:

• Python 3.10 or later is installed

• pip and virtualenv are available

• Git is installed and available in your terminal

• You're working on a Unix-based system (macOS, Linux, or WSL for Windows)

Optional but recommended:

• Poetry or pipenv for dependency management

• direnv for .env scoping

---

Step-by-Step Setup

1. Clone the Repository

bashCopyEditgit clone https://github.com/HUADA999/Cleo.git
cd Cleo

2. Create a Virtual Environment

Using venv:

bashCopyEditpython -m venv venv
source venv/bin/activate

Or with Poetry:

bashCopyEditpoetry install
poetry shell

3. Install Dependencies

bashCopyEditpip install -r requirements.txt

If you're using GPU-based libraries (like PyTorch or FAISS with CUDA), install those manually based on your setup.

---

Environment Configuration

Copy and modify the default environment config:

bashCopyEditcp .env.example .env

Then configure your .env file with:

iniCopyEditCLEO_AGENT=lex
CLEO_MEMORY_BACKEND=faiss
CLEO_MEMORY_PATH=data/lex.index
CLEO_LOG_LEVEL=debug

You can change the default agent here without modifying code.

---

Launching Cleo

Default Mode

bashCopyEditpython main.py

This will load the agent specified in .env and enter an interactive loop.

Example session:

bashCopyEdit>>> Task: Summarize the latest research on quantum encryption.
[Lex]: Searching online...
[Lex]: Reading results...
[Lex]: Here's a 3-point summary from IEEE and ArXiv sources.

Load Any Agent Manually

bashCopyEditfrom agents import load_agent

lex = load_agent("lex")
lex.run_loop()

You can also run tasks programmatically:

pythonCopyEditoutput = lex.run_task("Extract top climate legislation trends from the past year.")
print(output)

---

Development Tips

• Use logging.debug() calls inside tools or memory layers to monitor behavior.

• Add breakpoints in core/agent.py to trace agent state transitions.

• Use the tools/ directory to add or modify custom tools and test them in isolation.

---

Cleanup & Reset

To reset memory or agent state during dev:

bashCopyEditrm data/*.index logs/*.json

Or clear memory in-code:

pythonCopyEditagent.memory.clear()

---

Summary

Local deployment is the recommended way to experiment with agent behavior, create new personas, test tools, and evaluate workflows before deploying remotely. Once your setup is stable, you can move into containerized or server deployments, which are covered in the next section.