# 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.