Metadata-Version: 2.5
Name: ronnyx
Version: 0.2.0
Summary: Self-hosted MCP runtime with custom tool support. Connect any MCP server, add your own tools, chat via API or CLI.
Project-URL: Homepage, https://github.com/baranylcn/ronnyx
Project-URL: Source, https://github.com/baranylcn/ronnyx
Project-URL: Issues, https://github.com/baranylcn/ronnyx/issues
Author: Baran Yalcin
License: MIT
License-File: LICENSE.md
Keywords: agent,assistant,langgraph,llm,mcp,self-hosted
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: fastapi<1.0.0,>=0.111.0
Requires-Dist: langchain-core<2.0.0,>=1.0.0
Requires-Dist: langchain-mcp-adapters<1.0.0,>=0.2.0
Requires-Dist: langchain-openai<2.0.0,>=1.0.0
Requires-Dist: langgraph<2.0.0,>=1.0.0
Requires-Dist: pydantic<3.0.0,>=2.8.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.1
Requires-Dist: pyyaml<7.0.0,>=6.0.0
Requires-Dist: requests<3.0.0,>=2.31.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.30.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio<2.0.0,>=0.23.0; extra == 'dev'
Requires-Dist: pytest<10.0.0,>=8.0.0; extra == 'dev'
Requires-Dist: ruff<1.0.0,>=0.6.0; extra == 'dev'
Provides-Extra: graphrag
Requires-Dist: graphrag<4.0.0,>=3.3.0; extra == 'graphrag'
Description-Content-Type: text/markdown

# Ronnyx

A self-hosted AI assistant runtime. Define your tools, connect your services, and interact through an HTTP API or CLI -- all from a single YAML file.

Ronnyx runs as a persistent service with session memory and automatic tool dispatch. It supports both external tool servers (via MCP) and custom Python functions, so you can mix off-the-shelf integrations with your own logic.

## Features

- Connect external tool servers or write your own Python tools
- Session-aware chat API with multi-turn conversation history
- Single YAML config with environment variable resolution
- Built-in CLI client for interactive use
- Async LangGraph agent with automatic tool routing

## Quick Start

```bash
pip install ronnyx
```

Create a `ronnyx.yaml` in the directory you will run Ronnyx from:

```yaml
llm:
  model: gpt-4o
  api_key: ${OPENAI_API_KEY}

servers:
  github:
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}
```

A fully commented version is in [`ronnyx.yaml.example`](https://github.com/baranylcn/ronnyx/blob/main/ronnyx.yaml.example).

Set your API keys in a `.env` file next to it, or directly in `ronnyx.yaml`:

```
OPENAI_API_KEY=sk-...
GITHUB_TOKEN=ghp_...
```

Start the server:

```bash
ronnyx-serve
```

In a separate terminal, start the CLI:

```bash
ronnyx-chat
```

## Running the Server

`ronnyx-serve` listens on `127.0.0.1:8000` by default. Use `--host` and `--port` to change it:

```bash
ronnyx-serve --port 9000
ronnyx-serve --host 0.0.0.0   # reachable from other machines
```

The API has no authentication, and the agent acts with every credential in your config. Anyone who can reach the port can use those tools. Keep the default `127.0.0.1` unless the server sits behind a reverse proxy or private network that controls access.

## Configuration

All configuration lives in `ronnyx.yaml`. Environment variables referenced with `${VAR}` are resolved from the shell environment or a `.env` file.

```yaml
llm:
  model: gpt-4o
  api_key: ${OPENAI_API_KEY}

context:
  github_username: ${GITHUB_USERNAME}

servers:
  github:
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}

custom_tools:
  - function: my_tools.list_repos
    name: list_repos
    description: "List GitHub repos for a user with sorting"
```

### Sections

**llm** -- Model, API key, and optional `base_url` for an OpenAI-compatible
provider. Omit `base_url` to keep the default endpoint behavior. For a local
Ollama server, use its OpenAI-compatible endpoint and a placeholder key (Ronnyx
requires a non-empty key even when the server does not authenticate it):

```yaml
llm:
  model: llama3.1
  api_key: ollama
  base_url: http://localhost:11434/v1
```

Other providers can use their own endpoint URL and API key. Like other config
values, `base_url` supports `${VAR}` environment variable references.

**context** -- Key-value pairs injected into the system prompt. Use this to give the assistant information it cannot retrieve from tools (username, timezone, preferences).

**servers** -- External tool servers using the [Model Context Protocol](https://modelcontextprotocol.io). Each entry spawns a subprocess (stdio) or connects to a remote endpoint (SSE). All tools exposed by the server become available to the agent automatically.

**custom_tools** -- Python functions loaded alongside server tools. Point to any callable or `StructuredTool` instance using its dotted import path. Use this when you need custom logic or when an external server doesn't cover your use case.

**knowledge** -- Optional knowledge base over your own documents. See [Knowledge Base](#knowledge-base).

## Knowledge Base

Ronnyx can answer questions from your own documents using [GraphRAG](https://github.com/microsoft/graphrag). This is optional and requires Python 3.11+.

```bash
pip install "ronnyx[graphrag]"
```

Enable it in `ronnyx.yaml`:

```yaml
knowledge:
  provider: graphrag
  root: ./knowledge
```

Create the project, add your documents, and build the index:

```bash
ronnyx-index --init      # creates knowledge/ with GraphRAG settings
# put .txt files in knowledge/input/
ronnyx-index             # builds the index
```

Indexing calls the LLM for every chunk of every document, so it can be expensive on large collections. The command asks for confirmation first; pass `--yes` to skip it. GraphRAG settings, including models, live in `knowledge/settings.yaml`. The Ronnyx API key is used unless `GRAPHRAG_API_KEY` is set.

After indexing, restart `ronnyx-serve`. The agent gets two tools:

- `knowledge_local_search` -- specific questions about people, projects, or concepts in your documents
- `knowledge_global_search` -- broad questions such as main themes or overall summaries

If the index is missing or GraphRAG is not installed, the server still starts and logs a warning.

## API

### POST /api/chat

Send a message and receive a response within a session.

```bash
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"session_id": "1", "message": "How many open issues do I have?"}'
```

```json
{
  "session_id": "1",
  "reply": "You have 3 open issues in your repository."
}
```

Each session maintains its own conversation history, so follow-up questions work naturally.

### GET /api/tools

List all loaded tools.

```bash
curl http://localhost:8000/api/tools
```

### GET /

Health check.

## CLI

The CLI connects to the running server over HTTP.

```bash
ronnyx-chat
ronnyx-chat --base-url http://localhost:8000/api/chat --session-id 42
```

```
You > How many open issues do I have?
Ronnyx > You have 3 open issues in your repository.
```

The server must be running before starting the CLI.

## Development

```bash
git clone https://github.com/baranylcn/ronnyx
cd ronnyx
python -m venv venv
source venv/bin/activate   # macOS / Linux
venv\Scripts\activate      # Windows
pip install -e ".[dev]"
cp ronnyx.yaml.example ronnyx.yaml
```

Run the tests:

```bash
pytest -q
```

All tests run offline without API keys or external servers.

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Pull requests should be focused, clearly scoped, and include tests.

## License

MIT. See [LICENSE.md](LICENSE.md).
