Metadata-Version: 2.5
Name: ramabana
Version: 0.1.32
Summary: rama's arrow. a harness that does not miss
Project-URL: Repository, https://github.com/vedicreader/ramabana
Project-URL: Documentation, https://vedicreader.github.io/ramabana/
Author-email: Karthik <karthik.rajgopal@hotmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: nbdev
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: exhash>=0.4.9
Requires-Dist: fastcore>=2.1.16
Requires-Dist: fastspec>=0.2.1
Requires-Dist: fossick>=0.1.17
Requires-Dist: gheasy>=0.0.9
Requires-Dist: koshas>=0.1.7
Requires-Dist: liteparse<2.13,>=2.12
Requires-Dist: litesearch>=0.1.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rgapi>=0.1.19
Requires-Dist: rishi>=0.1.32
Requires-Dist: shalya>=0.0.4
Requires-Dist: uraiyadal>=0.0.6
Requires-Dist: vishalakshi>=0.1.14
Provides-Extra: acp
Requires-Dist: agent-client-protocol>=0.12.1; extra == 'acp'
Provides-Extra: all
Requires-Dist: agent-client-protocol>=0.12.1; extra == 'all'
Requires-Dist: dhrishti>=0.1.2; extra == 'all'
Requires-Dist: jupyter-client>=8.9.1; extra == 'all'
Requires-Dist: mcp>=1.2; extra == 'all'
Requires-Dist: pobblebonk>=0.0.3; extra == 'all'
Requires-Dist: pyghostty>=0.1.0; extra == 'all'
Requires-Dist: rishi[all]; extra == 'all'
Requires-Dist: teleprint>=0.1.1; extra == 'all'
Provides-Extra: cli
Requires-Dist: pyghostty>=0.1.0; extra == 'cli'
Requires-Dist: teleprint>=0.1.1; extra == 'cli'
Provides-Extra: copilot
Requires-Dist: rishi>=0.1.32; extra == 'copilot'
Provides-Extra: cron
Requires-Dist: pobblebonk>=0.0.3; extra == 'cron'
Provides-Extra: dev
Requires-Dist: agent-client-protocol>=0.12.1; extra == 'dev'
Requires-Dist: dhrishti>=0.1.2; extra == 'dev'
Requires-Dist: jupyter-client>=8.9.1; extra == 'dev'
Requires-Dist: mcp>=1.2; extra == 'dev'
Requires-Dist: nbdev>=3.3.11; extra == 'dev'
Requires-Dist: notebook>=7.6.1; extra == 'dev'
Requires-Dist: pobblebonk>=0.0.3; extra == 'dev'
Requires-Dist: pyghostty>=0.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: rishi[all]; extra == 'dev'
Requires-Dist: rishi[all]>=0.1.32; extra == 'dev'
Requires-Dist: teleprint>=0.1.1; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == 'mcp'
Provides-Extra: pyrepl
Requires-Dist: dhrishti>=0.1.2; extra == 'pyrepl'
Requires-Dist: jupyter-client>=8.9.1; extra == 'pyrepl'
Requires-Dist: pyghostty>=0.1.0; extra == 'pyrepl'
Requires-Dist: teleprint>=0.1.1; extra == 'pyrepl'
Description-Content-Type: text/markdown

# ramabana


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

<p align="center">

<img src="media/rama-arrow.png" alt="rama's arrow" width="96" />
</p>

[`Agent`](https://vedicreader.github.io/ramabana/agent.html#agent) runs a model against the tools supplied by a host. A host defines the folders, network access, memory, and approval gate available to the model. The terminal, MCP server, and Agent Client Protocol server use the same agent and tool contracts.

Start with one folder. Ramabana can write only inside the folders named by `--root`. Read access also stays inside those folders. `--read-outside` widens read access to the machine.

<p align="center">

<img src="media/ramabana-cli-demo.gif" alt="ramabana CLI on Gemma 4 LiteRT" width="820" />
</p>

## Run it on a project

Install the terminal frontend and open the current folder:

``` sh
pip install 'ramabana[cli]'
ramabana --root .
```

Omit the prompt for the interactive terminal. Pass a prompt for one turn that prints its answer and exits:

``` sh
ramabana --root . 'Find where request timeouts are configured.'
```

Ramabana starts with `--approve ask`. Write tools wait for approval. `--approve auto` permits writes without asking for the rest of that process. `--no-web` removes the network tools.

## Understand one turn

This example uses the same [`Agent.ask`](https://vedicreader.github.io/ramabana/agent.html#agent.ask) path as a real model. [`fake_agent`](https://vedicreader.github.io/ramabana/testing.html#fake_agent) supplies a deterministic backend and an in-memory project. The page runs without credentials, downloads, or writes to disk.

``` python
from ramabana.testing import fake_agent

agent, backend = fake_agent(replies=['The threshold is defined in `pkg/sizes.py`.'])
answer = agent.ask('Where is the threshold defined?')
answer
```

    'The threshold is defined in `pkg/sizes.py`.'

``` python
assert answer == 'The threshold is defined in `pkg/sizes.py`.'
assert agent.history[-1]['prompt'] == 'Where is the threshold defined?'

agent.turn_lines(), repr(agent.turn_use)
```

    (['🔍 Search Where is the threshold defined?'],
     '15 tok · in 10 · out 5 · model')

## Choose a frontend

Use the terminal for an interactive coding session or a single shell command. Use MCP when another assistant needs Ramabana’s tools. MCP serves read-only tools by default. `--write` adds the write tools. Use ACP when an editor launches Ramabana as its agent.

``` sh
ramabana --root .
ramabana-mcp --root .
ramabana-acp --root .
```

Add `--model MODEL` to pin the turn model. Add `--vault` to retain material read through the memory tools. Run each command with `--help` for its complete options.

## Read the implementation

Start with the page for the contract you need:

- [core](00_core.ipynb): errors, routing, model budgets, and shared values
- [runtime](01_runtime.ipynb): backends, usage, runs, and compaction
- [tools](02_tools.ipynb): hosts, tool construction, and delegation
- [agent](03_agent.ipynb): turns, approvals, activity, plans, history, and branching
- [testing](04_testing.ipynb): in-memory hosts and deterministic backends
- [terminal](05_cli.ipynb), [MCP](06_mcp.ipynb), [PyREPL](11_pyrepl.ipynb), and [ACP](16_acp.ipynb): frontend adapters
- [vault](07_vault.ipynb), [API specifications](10_spec.ipynb), [git](12_git.ipynb), and [folder monitoring](17_monitor.ipynb): optional capabilities
- [shop](08_shop.ipynb): product search tools
- [coding patterns](09_coding_patterns.ipynb), [theory](13_theory.ipynb), [prose](14_write_prose.ipynb), and [documentation](15_write_docs.ipynb): bundled agent skills

## Develop Ramabana

The notebooks are the source. `nbdev-prepare` generates the files under `ramabana/`.

``` sh
uv sync --all-extras --group dev
uv run nbdev-prepare
```

`nbdev-prepare` exports the notebooks, runs notebook tests, cleans notebook metadata, and rebuilds the README.
