ai-agent CLI & TUI

Modern, animated CLI for the ai-agent library with streaming chat, tool-calling, and a beautiful Textual TUI.

Install

1. Create a virtual environment (recommended)
2. Install dependencies:

pip install -r requirements.txt

3. Set your OpenAI API key:

# PowerShell on Windows
$env:OPENAI_API_KEY = "sk-..."

Optionally configure ~/.ai-agent-config.yaml to define agents and tools. It will be created on first run with sensible defaults.

Run

• List agents from config:

python -m cli agents

• List tools for an agent:

python -m cli tools --agent default

• Ask a one-off question with streaming output:

python -m cli ask "Écris un haïku sur le terminal moderne"

• Launch Textual chat (modern TUI with animations):

python -m cli chat

Notes

• Streaming in ask shows live updates with a smooth animation.
• The TUI shows a typing indicator and live markdown rendering.
• Tool-calling is supported in non-streaming execute() inside the agent; the TUI uses streaming for a real-time experience.

Roadmap

• API server to expose the agent via HTTP (FastAPI)
• Persistent conversations and session management
• Better tool discovery and dynamic enable/disable from the UI

---

Full Guide (Beginner → Advanced)

What is this project?

ai-agent is a Python library and CLI/TUI that lets you chat with an AI agent capable of:

• Using tools (function calling) to perform actions (read/write files, create PDFs, etc.)
• Creating new tools dynamically when a needed capability is missing (optional and gated)
• Streaming or non-streaming interaction modes
• Self-correction and validation loops to retry when actions fail

It is designed for local use (not yet published on PyPI) and easy customization.

Features

• Tool calling with a registry and auto-discovery under core/tools/
• Built-in tools: echo, calculator, datetime_now, file_read, file_write, pdf_create
• Dynamic tool creation with tool_create under core/tools/generated/
• Modern Textual TUI with a mode toggle (Streaming vs Tools)
• CLI commands for quick one-off questions
• Self-correction and final validation passes in the agent

Installation

1. Create and activate a virtual environment

python -m venv venv
# Windows PowerShell
./venv/Scripts/Activate.ps1

2. Install dependencies

pip install -r requirements.txt

3. Set your OpenAI API key

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-..."

If you use generated tools that require extra packages (e.g., Pillow for image manipulation), install them separately:

pip install pillow

Configuration

• On first run, a config file may be created at ~/.ai-agent-config.yaml.
• You can define agents, models, temperatures, and pre-enabled tools there.
• Even without config, the agent will enable a sensible default set of tools at runtime.

Note on python -m cli tools: this command reflects tools defined in the config file. The agent itself may still have default tools active at runtime even if the config is empty.

Usage

CLI

• Streaming (tools disabled during stream):

python -m cli ask "Écris un haïku sur le terminal moderne"

• Non-streaming with tool-calling enabled:

python -m cli ask --no-stream "Crée un fichier out/notes.txt avec 'Bonjour' puis lis le contenu"

TUI (Textual)

python -m cli chat

• Toggle modes with Ctrl+M:
  • Streaming: real-time response, tools disabled
  • Tools: non-streaming, tool-calling enabled; a summary of executed tools is shown after each response

Dynamic Tool Creation (Advanced)

The agent can create a new tool on the fly via the meta-tool tool_create. This writes a module under core/tools/generated/ and registers it.

Security is enforced: dynamic code execution is disabled by default. To proceed, the tool creation call must include allow_code=True. You can authorize it in your prompt when you trust the action:

« Tu as la permission d’utiliser tool_create (allow_code=true) pour accomplir cette tâche. »

If a tool already exists, tool_create will error unless you set overwrite=True.

Programmatic API

from core.agent import AIAgent

agent = AIAgent.from_config("default")  # or create via AgentManager

# Streaming (no tools in streaming)
for chunk in agent.stream("Raconte une blague courte sur les terminaux."):
    print(chunk, end="")

# Non-streaming with tool-calling and self-correction
resp = agent.execute(
    "Crée un fichier out/demo.txt avec 'Hello' puis lis-le",
    stream=False,
    use_tools=True,
    self_correct=True,
)
print("\n---\n", resp.content)
print("Tools:", resp.metadata.get("executed_tools"))

Architecture Overview

• core/agent.py: Main AIAgent with conversation management, tool orchestration, self-correction
• core/base_tool.py: Tool base class, @tool decorator, tool_registry
• core/tool_manager.py: Executes tools, timeouts, metrics, and OpenAI functions mapping
• core/tools/: Built-in tools and generated/ for dynamic tools
• cli/: Typer CLI and Textual TUI (cli.py, tui.py)
• requirements.txt: Python dependencies (includes fpdf2 for PDFs)

Default system flow (built into the agent):

1. Lire le message utilisateur
2. Lister les outils disponibles
3. Si un outil convient, l’appeler avec des paramètres précis
4. Sinon, si possible, créer un outil via tool_create
5. Exécuter l’action et renvoyer un résultat concis

Safety & Security

• Dynamic tool creation executes code you generate; it is disabled unless allow_code=True is provided explicitly.
• Review generated modules under core/tools/generated/ before committing.
• Prefer audited, static tools in production.

Troubleshooting

• “Tool X is already registered”: harmless auto-discovery message; can be ignored.
• No tools available in python -m cli tools: likely means your YAML config doesn’t list tools; the agent still has defaults at runtime.
• ModuleNotFoundError: No module named 'core' when running a generated tool directly: generated tools are packages loaded by the agent; don’t execute them as standalone scripts.
• Tool failures: the agent now performs self-correction and validation. If persistent, check parameters, file paths, and whether required third-party packages (e.g., pillow) are installed.

Contributing

1. Fork the repo and create a feature branch
2. Add or update tools under core/tools/ (or propose new built-ins)
3. Add examples and docs
4. Open a PR

License

MIT (or project’s chosen license) — see LICENSE if present.

Installation

To install the ai-agent library locally and use it anywhere on your computer, follow these steps:

1. Clone the repository:

git clone https://github.com/thib-crypt/ai-agent.git
cd ai-agent

2. Create and activate a Python virtual environment (recommended):

python -m venv venv
# On Windows PowerShell
.\venv\Scripts\Activate.ps1
# On Unix or Windows CMD
source venv/bin/activate

3. Install the library in editable mode with dependencies:

pip install -e .

This will make the ai-agent library available system-wide in your environment.

CLI Usage

The ai-agent library provides a CLI interface accessible via the cli command after installation.

Example usage:

cli agents
cli tools --agent default
cli ask "Write a haiku about modern terminals"
cli chat

Using the Coding Assistant CLI

The coding-assistant-cli is a separate package located in the coding-assistant-cli directory. To install it globally or in your environment for CLI access:

1. Navigate to the coding-assistant-cli directory:

cd coding-assistant-cli

2. Install the package in editable mode:

pip install -e .

3. Use the CLI command codeai:

codeai --help

This will allow you to access the coding assistant CLI from anywhere on your system.