Metadata-Version: 2.4
Name: ainator
Version: 0.0.3
Project-URL: Documentation, https://yourlabs.io/oss/ainator#readme
Project-URL: Issues, https://yourlabs.io/oss/ainator/issues
Project-URL: Source, https://yourlabs.io/oss/ainator
Author-email: jpic <jpic@yourlabs.org>
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Requires-Dist: agno
Requires-Dist: cli2
Requires-Dist: ddgs
Requires-Dist: ebooklib
Requires-Dist: html2text
Requires-Dist: httpx
Requires-Dist: huggingface-hub
Requires-Dist: lancedb
Requires-Dist: llama-index-core
Requires-Dist: llama-index-embeddings-huggingface
Requires-Dist: llama-index-vector-stores-lancedb
Requires-Dist: pandas
Requires-Dist: parsel
Requires-Dist: pygments
Requires-Dist: pyyaml
Requires-Dist: sentence-transformers>=5.1.0
Requires-Dist: tree-sitter
Requires-Dist: tree-sitter-language-pack
Description-Content-Type: text/markdown

# Ainator

[![PyPI - Version](https://img.shields.io/pypi/v/ainator.svg)](https://pypi.org/project/ainator/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ainator.svg)](https://pypi.org/project/ainator/)
[![License](https://img.shields.io/pypi/license/ainator.svg)](https://github.com/yourlabs/ainator/blob/main/LICENSE.txt)

**Ainator** is a command-line interface (CLI) and API framework for running powerful AI agents. Built on top of the [agno](https://agno.yourlabs.io/) agent library, it provides persistent session management, Retrieval-Augmented Generation (RAG) over code repositories and websites, integrated tools (shell, files, DuckDuckGo search), knowledge plugins, and a FastAPI web server.

Perfect for developers seeking a local, configurable AI assistant for coding, debugging, documentation querying, and more.

## Features

- **Interactive Chat**: Real-time terminal conversations with streaming responses and tool usage visualization.
- **Persistent Sessions**: Auto-saved conversations with switchable contexts and auto-generated names.
- **Knowledge Bases (RAG)**:
  - Embed code repositories (AST-aware chunking, parallel processing, LanceDB storage).
  - Embed websites (scraping with Parsel + chunking).
  - Query with `search`, `think`, `analyze` tools.
- **Built-in Tools**:
  - Chunked shell execution for safety.
  - File read/write operations.
  - DuckDuckGo search.
  - Custom knowledge tools.
- **Configurable**: YAML config for models (e.g., xAI Grok, OpenAI), DB, tools, knowledge.
- **Web API**: FastAPI server for programmatic agent access.
- **Plugin System**: Extensible RAG knowledge via entry points (`ainator.knowledge`).

## Installation

```bash
pip install ainator
```

**Requirements**: Python ≥3.8. Dependencies: `agno`, `ddgs`, `chunkie`, `parsel`.

Runs in any directory; creates `.ainator/config.yml` on first use.

## Quickstart

### 1. Interactive Chat
```bash
ainator chat
```
Start a persistent chat session (default model: xAI Grok). Supports streaming, tools, history.

### 2. One-off Prompts
```bash
ainator prompt "Fix the bug in my Python script"
```
Creates/saves a new session. Continue in same session:
```bash
ainator but "Also add unit tests"
```

### 3. Session Management
```bash
ainator session list    # List sessions (ID, date, name)
ainator session switch <id>  # Switch to session
ainator session show    # Show messages in current session
```

### 4. Manage Knowledge (RAG)
**Add code repo** (embeds with code-aware splitting):
```bash
ainator rag code add ./path/to/repo python  # language=python, num_workers=12
```
Adds to config as `knowledge.<repo-name>`.

**Add website** (similar via `rag site add <url>`).

```bash
ainator rag site add https://cli2.readthedocs.io
```
Adds to config as `knowledge.<domain-slug-url-slug>`.

**Search knowledge**:
```bash
ainator rag search <knowledge-name> "your query"
```

**Remove knowledge**:
```bash
ainator rag remove <knowledge-name>
```

**View RAGs**:
```bash
ainator rag
```

### 5. Web Server
```bash
ainator server
```
- [Agno-AGI Open Source Web UI](https://github.com/agno-agi/agent-ui) available
- Swagger docs at `http://localhost:7777/docs` (Powered by the glorious Agno AgentOS)

### Config Inspection
```bash
ainator # help
```
Shows current session (if any) and full config.

## Configuration Hacking

Local `.ainator/config.yml`, auto-created/updated, but can be hacked manually
for hacking purposes:

```yaml
model: agno.models.xai:xAI id=grok-beta  # Or openai:gpt-4o, etc.
db: agno.db.sqlite:SqliteDb db_file=.ainator/agno.db
tools:
  - agno.tools.file:FileTools base_dir=.
  - agno.tools.shell:ShellTools
  - agno.tools.duckduckgo:DuckDuckGoTools
knowledge: {}  # Populated via CLI, e.g.:
#   myrepo:
#     plugin: code
#     path: /path/to/repo
```

The format is `dotted.path.to.module:ClassName arg0 argN kwarg0=value0` to
customize Agno framework object casting, so, you can extend the solution with
your own python code right there in the config, for hacking purpose of course.

## Architecture

- **Core**: [agno](https://agno.yourlabs.io/) (agents, models, tools, SQLite DB).
- **CLI**: [cli2](https://cli2.yourlabs.io/) CLI framework.
- **Knowledge Plugins**:
  | Plugin | Description |
  |--------|-------------|
  | `code` | Faster repos embeds (llama-index CodeSplitter, HierarchicalNodeParser, BAAI/bge-small-en-v1.5 embeddings, LanceDB). |
  | `site` | Faster Website scraping & embedding (Parsel + Chunkie). |
  | `generic` | Feed local directories to Agno Knowledge directly. |
- **Renderer**: Streaming Markdown with reasoning/tool steps.
- **Server**: FastAPI via agno AgentOS.

## Development

```bash
git clone <repo-url>  # e.g., https://yourlabs.io/oss/ainator
cd ainator
pip install -e '.[types]'  # editable + mypy
```

- Type check: `hatch run types:check` (or `mypy src/ainator`)
- Coverage: Configured for `ainator`, `tests`.
- Version: Managed via `src/ainator/__about__.py` (currently `0.0.1`).
- Plugins: Add via `[project.entry-points."ainator.knowledge"]`.

No tests yet; contribute!

## License

MIT © 2026-present [jpic](https://yourlabs.io/jpic)

See [LICENSE.txt](LICENSE.txt).

## Links

- [PyPI](https://pypi.org/project/ainator/)
- [Source](https://yourlabs.io/oss/ainator)
- [Issues](https://yourlabs.io/oss/ainator/issues)
- [Agno](https://agno.yourlabs.io/) (core lib)
