Metadata-Version: 2.4
Name: sanjaya
Version: 0.2.1
Summary: Extensible RLM agent framework with video understanding
Author-email: Prathamesh Sarang <prthamesh.sarang@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/pratos/sanjaya
Project-URL: Repository, https://github.com/pratos/sanjaya
Project-URL: Issues, https://github.com/pratos/sanjaya/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-ai>=0.2.0
Requires-Dist: pydantic-monty>=0.0.9
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=14.0
Requires-Dist: genai-prices>=0.0.56
Requires-Dist: nest-asyncio>=1.6.0
Requires-Dist: moondream-station>=0.1.9
Requires-Dist: parakeet-mlx>=0.5.1
Requires-Dist: fastapi>=0.135.3
Requires-Dist: uvicorn>=0.43.0
Requires-Dist: huggingface-hub[cli]>=1.9.0
Provides-Extra: video
Requires-Dist: logfire; extra == "video"
Requires-Dist: Pillow>=10.0; extra == "video"
Provides-Extra: image
Requires-Dist: Pillow>=10.0; extra == "image"
Requires-Dist: pillow-heif>=0.16; extra == "image"
Requires-Dist: cairosvg>=2.7; extra == "image"
Provides-Extra: document
Requires-Dist: pymupdf>=1.24; extra == "document"
Requires-Dist: python-pptx>=1.0; extra == "document"
Requires-Dist: ebooklib>=0.18; extra == "document"
Requires-Dist: beautifulsoup4>=4.12; extra == "document"
Provides-Extra: tracing
Requires-Dist: logfire; extra == "tracing"
Provides-Extra: all
Requires-Dist: sanjaya[document,image,tracing,video]; extra == "all"
Provides-Extra: benchmarks
Requires-Dist: datasets>=3.0; extra == "benchmarks"
Requires-Dist: numpy>=1.26; extra == "benchmarks"
Requires-Dist: Pillow>=10.0; extra == "benchmarks"
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: jupyter>=1.1.1; extra == "dev"
Dynamic: license-file

# Sanjaya

Sanjaya is a Python library for building evidence-first RLM (Recursive Language Model) agents.

It runs a loop where the model writes Python, executes it in a sandboxed REPL, inspects results, calls tools, and iterates until it can return a grounded answer.

## Why the name?

In the *Mahabharata*, Sanjaya narrates events to a blind king with "divine sight." This project follows the same idea: observe evidence and report what happened.

## Install

```bash
pip install sanjaya
```

With extras:

```bash
pip install "sanjaya[video]"      # video analysis
pip install "sanjaya[image]"      # image analysis (Pillow, HEIC, SVG)
pip install "sanjaya[document]"   # PDF/EPUB/PPTX/Markdown/text parsing
pip install "sanjaya[tracing]"    # tracing integrations
pip install "sanjaya[all]"        # everything
```

## Configuration

Set at least:

- `OPENROUTER_API_KEY`

Optional (depends on your model/provider setup):

- `OPENAI_API_KEY`
- `MOONDREAM_API_KEY`
- `LOGFIRE_TOKEN`

## Quick start

```python
from sanjaya import Agent

agent = Agent(max_iterations=8)

answer = agent.ask("What is the capital of France?")
print(answer.text)
```

## Video analysis

```python
from sanjaya import Agent

agent = Agent(max_iterations=12)

answer = agent.ask(
    "How many people are speaking and what are they discussing?",
    video="/path/to/video.mp4",
    # subtitle="/path/to/subtitle.json",  # optional
)

print(answer.text)
print(answer.evidence)
```

When `video=...` is provided, `VideoToolkit` is auto-registered if you have not already added one.

## Document analysis

```python
from sanjaya import Agent

agent = Agent(max_iterations=12)

answer = agent.ask(
    "Summarize the key claims and supporting evidence.",
    document=["/path/to/report.pdf", "/path/to/appendix.md"],
)

print(answer.text)
print(answer.evidence)
```

Supported document types include `.pdf`, `.epub`, `.pptx/.ppt`, `.md`, and `.txt`.

When `document=...` is provided, `DocumentToolkit` is auto-registered if needed.

## Image analysis

```python
from sanjaya import Agent

agent = Agent(max_iterations=10)

answer = agent.ask(
    "What text is visible in this screenshot?",
    image="/path/to/screenshot.png",
)

print(answer.text)
print(answer.evidence)
```

Multiple images:

```python
answer = agent.ask(
    "Compare these two charts and summarize differences.",
    image=["/path/to/chart_q1.png", "/path/to/chart_q2.png"],
)
```

Supported formats: JPEG, PNG, WebP, GIF, TIFF, BMP, HEIC (requires `sanjaya[image]`), SVG (requires `sanjaya[image]`).

When `image=...` is provided, `ImageToolkit` is auto-registered if needed.

## Custom tools

```python
from sanjaya import Agent, Toolkit, tool

class MyToolkit(Toolkit):
    @tool
    def lookup(self, query: str) -> str:
        return f"result for: {query}"

agent = Agent().use(MyToolkit())
answer = agent.ask("Find the latest status update")
print(answer.text)
```

## Answer object

`Agent.ask()` returns an `Answer` object with:

- `text`
- `evidence`
- `iterations`
- `input_tokens`, `output_tokens`, `cost_usd`
- `wall_time_s`

## Development (repo)

If you are working from the repository:

- `just dev` — API + UI
- `just api` — FastAPI backend (`:8000`)
- `just ui` — Next.js frontend (`:5100`)
- `just demo` — run demo prompts

## Status

Sanjaya is actively developed. Core video + document flows are working, and evaluation/dashboard tooling is still evolving.
