Metadata-Version: 2.5
Name: tantra-harness
Version: 1.4.0
Summary: Agent actor runtime — durable turns as a library
Project-URL: Homepage, https://github.com/malayh/tantra
Project-URL: Documentation, https://malayh.github.io/tantra/docs/
Author-email: Malay Hazarika <malay.hazarika@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: httpx>=0.27
Requires-Dist: openai>=2.0
Requires-Dist: pydantic>=2.9
Provides-Extra: doc
Requires-Dist: pypdf>=6; extra == 'doc'
Requires-Dist: python-docx>=1.1; extra == 'doc'
Provides-Extra: postgres
Requires-Dist: psycopg-pool>=3.2; extra == 'postgres'
Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
Provides-Extra: telemetry
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30; extra == 'telemetry'
Requires-Dist: opentelemetry-sdk>=1.30; extra == 'telemetry'
Provides-Extra: web
Requires-Dist: curl-cffi>=0.15; extra == 'web'
Requires-Dist: tenacity>=9; extra == 'web'
Requires-Dist: trafilatura>=2.0; extra == 'web'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://cdn.jsdelivr.net/gh/malayh/tantra@main/assets/logo.svg" width="140" alt="tantra logo">
</p>

# tantra

The agent actor runtime as a Python library. Install name `tantra-harness`, import name `tantra`.

Tantra gives each agent a durable FIFO inbox, an independent event journal, and one active turn. A process-wide `Runtime` owns providers, stores, tools, hooks, permissions, skills, memory, compaction, telemetry, actor tasks, and writer connections.

## Install

| Command | Adds |
|---|---|
| `pip install tantra-harness` | Core runtime and shell tools |
| `pip install "tantra-harness[web]"` | Brave web search and web fetch |
| `pip install "tantra-harness[doc]"` | PDF and Word document reading |
| `pip install "tantra-harness[postgres]"` | PostgreSQL storage |
| `pip install "tantra-harness[telemetry]"` | OpenTelemetry tracing |

The unrelated PyPI project `tantra` installs the same import name. Do not install both projects in one environment.

## Basic usage

```python
import asyncio
from uuid import uuid4

from tantra import Agent, OpenAICompatible, Runtime, SQLiteStore
from tantra.extratools.web import web_search


class Researcher(Agent):
    model = "gpt-5"
    prompt = "Answer with current, sourced information."
    tools = [web_search(api_key=BRAVE_API_KEY)]


async def main() -> None:
    store = SQLiteStore("sessions.db")
    await store.setup()
    runtime = Runtime(
        OpenAICompatible("https://api.openai.com/v1", OPENAI_API_KEY),
        store,
        [Researcher],
    )
    root_id = await runtime.create(Researcher)
    async with runtime.connect(root_id, writable=True) as connection:
        result = await connection.prompt(
            "What changed in Python 3.13?",
            command_id=uuid4(),
        )
    print(result.text)
    await runtime.aclose()


asyncio.run(main())
```

`Connection.prompt()` accepts a durable command and waits for its terminal result. For streaming, call `send()` and iterate the connection. Reconnect with the last scalar `seq` as `after`; use `Runtime.events()` for a child journal. Command IDs are UUIDs and make acceptance idempotent.

Subagents are independent actors. Models use the injected `spawn`, `status`, `send`, and `finish` tools; no parent stream merges child events. Plain completion leaves a child reusable and notifies its parent with status only, while `finish` delivers the final result. Human asks and approval-gated tools are root-only.

Compaction is opt-in with `Runtime(compactor=PruneThenSummarize())`. Configured runtimes budget the complete provider request, preserve system and tool definitions, and compact each actor independently.

For multi-process deployments, pair `PostgresStore` with the optional `PostgresCoordinator` for leased execution ownership, fenced writes, command forwarding, and takeover recovery. The default remains single-process.

Tantra 1.4 reduces active PostgreSQL runtime CPU with bounded durable delta batching, terminal-aware result checks, shared recent event pages, and focused actor observation. Full history remains the default, and public replay stays complete. Stop PostgreSQL writers before upgrading an existing database; the root-key migration rewrites session rows.

See the [documentation](https://malayh.github.io/tantra/docs/), the [1.4 upgrade guide](https://malayh.github.io/tantra/docs/guides/migration-1.4/), and the [coordinator setup guide](https://malayh.github.io/tantra/docs/guides/migration-1.2/).

## Reference app

`apps/sarathi` is the repository's interactive web application.

## License

Apache-2.0
