73 lines
3.3 KiB
Markdown
73 lines
3.3 KiB
Markdown
|
# R - Autonomous Terminal AI Agent
|
||
|
|
|
||
|
|
## Project Overview
|
||
|
|
**R** is a command-line autonomous AI agent written in C. It implements the ReAct (Reasoning + Acting) pattern to perform complex tasks by iteratively executing tools (shell, file I/O, web search, database) and analyzing their output.
|
||
|
|
|
||
|
|
### Key Features
|
||
|
|
* **Agentic Loop:** Autonomous reasoning and execution cycle (up to 300 iterations).
|
||
|
|
* **Multi-Provider:** Supports OpenAI, Anthropic, Ollama, Grok, etc.
|
||
|
|
* **Tool Ecosystem:** Native C implementations for file operations, system commands, HTTP requests, and SQLite storage.
|
||
|
|
* **Persistence:** Local SQLite database (`~/.r.db`) and session history.
|
||
|
|
* **Shell Integration:** Functions as a fallback handler for `bash` "command not found" errors.
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
The project follows a standard C project structure with separated interface and implementation.
|
||
|
|
|
||
|
|
### Directory Structure
|
||
|
|
* **`src/`**: Core implementation files.
|
||
|
|
* `main.c`: Entry point, REPL loop, and argument parsing.
|
||
|
|
* `agent.c`: Core ReAct loop logic.
|
||
|
|
* `tools/`: Individual tool implementations (e.g., `tool_file.c`, `tool_http.c`).
|
||
|
|
* **`include/`**: Header files defining the public API for modules (e.g., `agent.h`, `tool.h`).
|
||
|
|
* **`testit/`**: Python-based integration testing framework.
|
||
|
|
* **`Makefile`**: Build configuration.
|
||
|
|
|
||
|
|
### Data Storage
|
||
|
|
* **Database:** `~/.r.db` (SQLite) stores key-value pairs and other persistent data.
|
||
|
|
* **History:** `~/.r_history` stores REPL command history.
|
||
|
|
* **Context:** `.rcontext.txt` (local) and `~/.rcontext.txt` (global) provide persistent context to the agent.
|
||
|
|
|
||
|
|
## Building and Running
|
||
|
|
|
||
|
|
### Dependencies
|
||
|
|
Requires: `libcurl`, `json-c`, `readline`, `ncurses`, `sqlite3`, `gnutls`, `gmp`, `openssl`.
|
||
|
|
|
||
|
|
**Debian/Ubuntu:**
|
||
|
|
```bash
|
||
|
|
sudo apt install libcurl4-openssl-dev libjson-c-dev libreadline-dev libncurses-dev libsqlite3-dev libgnutls28-dev libgmp-dev libssl-dev
|
||
|
|
```
|
||
|
|
|
||
|
|
### Build Commands
|
||
|
|
* **Build:** `make build` (Outputs binary to `bin/r` and copies to `./r`)
|
||
|
|
* **Clean:** `make clean`
|
||
|
|
* **Install:** `make install` (Installs to `/usr/local/bin/r`)
|
||
|
|
|
||
|
|
### Usage
|
||
|
|
* **Interactive REPL:** `./r`
|
||
|
|
* **One-shot Command:** `./r "Create a hello world file in python"`
|
||
|
|
* **Piped Input:** `cat logs.txt | ./r --stdin "Analyze these logs"`
|
||
|
|
|
||
|
|
## Testing
|
||
|
|
The project uses a custom Python-based testing framework located in `testit/`.
|
||
|
|
|
||
|
|
**WARNING:** The test script (`testit/test.py`) performs aggressive directory cleanup. **ALWAYS** run tests in a dedicated, isolated directory (e.g., inside `testit/test_dir/`), never in the project root.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Example safe test execution
|
||
|
|
cd testit/test_dir
|
||
|
|
python3 ../test.py
|
||
|
|
```
|
||
|
|
|
||
|
|
## Development Conventions
|
||
|
|
* **Language:** C (Standard C99/C11).
|
||
|
|
* **Style:** `snake_case` for functions and variables.
|
||
|
|
* **Error Handling:** Extensive use of return codes and error checking (see `r_error.c`).
|
||
|
|
* **Memory Management:** Explicit `malloc`/`free`. Tools must manage their own memory.
|
||
|
|
* **Tool Definition:** Tools are registered in `src/tool_registry.c` and implemented in `src/tools/`. New tools must return a JSON string output.
|
||
|
|
|
||
|
|
## Configuration
|
||
|
|
Configuration is handled via environment variables and runtime flags:
|
||
|
|
* `R_KEY` / `OPENAI_API_KEY`: API authentication.
|
||
|
|
* `R_MODEL`: Target model (e.g., `gpt-4`, `claude-3-opus`).
|
||
|
|
* `R_SESSION`: Session identifier for context continuity.
|