Metadata-Version: 2.5
Name: tvastar
Version: 0.29.0
Summary: Tvastar — agents that provably work at minimum cost. The full-stack framework for building, running, and operating AI agents in production.
Project-URL: Homepage, https://github.com/vanamayaswanth/tvastar
Project-URL: Repository, https://github.com/vanamayaswanth/tvastar
Project-URL: Issues, https://github.com/vanamayaswanth/tvastar/issues
Project-URL: Changelog, https://github.com/vanamayaswanth/tvastar/blob/main/CHANGELOG.md
Author-email: vanamayaswanth <vanamayaswanth@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,claude,harness,llm,mcp,model-context-protocol,sandbox,skills,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Provides-Extra: all
Requires-Dist: anthropic>=0.40.0; extra == 'all'
Requires-Dist: fastapi>=0.110.0; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: litellm>=1.40.0; extra == 'all'
Requires-Dist: networkx>=3.0; extra == 'all'
Requires-Dist: openai>=1.40.0; extra == 'all'
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'all'
Requires-Dist: presidio-analyzer>=2.2; extra == 'all'
Requires-Dist: presidio-anonymizer>=2.2; extra == 'all'
Requires-Dist: slack-sdk>=3.0; extra == 'all'
Requires-Dist: spacy>=3.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'all'
Requires-Dist: websockets>=12.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: cryptography>=41.0; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
Requires-Dist: pydantic>=2.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: dspy
Requires-Dist: dspy>=2.5.0; extra == 'dspy'
Provides-Extra: encrypted
Requires-Dist: cryptography>=41.0; extra == 'encrypted'
Provides-Extra: github
Requires-Dist: httpx>=0.27; extra == 'github'
Provides-Extra: graph
Requires-Dist: networkx>=3.0; extra == 'graph'
Provides-Extra: http
Requires-Dist: httpx>=0.27; extra == 'http'
Provides-Extra: litellm
Requires-Dist: litellm>=1.40.0; extra == 'litellm'
Provides-Extra: nats
Requires-Dist: nats-py>=2.0; extra == 'nats'
Provides-Extra: openai
Requires-Dist: openai>=1.40.0; extra == 'openai'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'otel'
Provides-Extra: pagerduty
Requires-Dist: httpx>=0.27; extra == 'pagerduty'
Provides-Extra: presidio
Requires-Dist: presidio-analyzer>=2.2; extra == 'presidio'
Requires-Dist: presidio-anonymizer>=2.2; extra == 'presidio'
Requires-Dist: spacy>=3.0; extra == 'presidio'
Provides-Extra: serve
Requires-Dist: fastapi>=0.110.0; extra == 'serve'
Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'serve'
Requires-Dist: websockets>=12.0; extra == 'serve'
Provides-Extra: slack
Requires-Dist: slack-sdk>=3.0; extra == 'slack'
Description-Content-Type: text/markdown

# Tvastar

[![PyPI](https://img.shields.io/pypi/v/tvastar.svg)](https://pypi.org/project/tvastar/)
[![Python](https://img.shields.io/pypi/pyversions/tvastar.svg)](https://pypi.org/project/tvastar/)
[![CI](https://github.com/vanamayaswanth/tvastar/actions/workflows/ci.yml/badge.svg)](https://github.com/vanamayaswanth/tvastar/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

**A durable Python harness for agents that act on real systems.**

Tvastar gives an agent a controlled runtime for tools, state, sandboxes, sessions, and recovery—then lets you attach task-specific checks, governance, and evidence to the work it performs. Its core is deliberately small: declare an agent, run it through a harness, and add control or assurance layers only when the operating need requires them.

The first reference workflow is **verified CI repair**: run a failing test command, let an agent repair the workspace, and accept success only after Tvastar reruns that same command. The harness is the product; CI repair is the clearest way to see its contract in action.

```
Agent     = Model + Harness
Loop      = Agent + Schedule + Verification + Handoff
Assurance = Evidence + Policy + Receipts
```

## Tvastar product architecture

```text
┌────────────────────────────────────────────────────────────────────┐
│ TVASTAR CORE                                                       │
│ Agent declaration · Harness · Session · Tools · Sandboxes          │
│ Storage · Memory · Models                                          │
│                                                                    │
│ Build and run one capable agent.                                   │
└────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌────────────────────────────────────────────────────────────────────┐
│ TVASTAR CONTROL                                                    │
│ Workflows · Dispatch · Loops · Subagents · Fleet                   │
│ Scheduling · Retry · Handoff · Routing · Coordination              │
│                                                                    │
│ Turn individual runs into managed operational work.                │
└────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌────────────────────────────────────────────────────────────────────┐
│ TVASTAR ASSURANCE                                                  │
│ Findings · Verification · Governance · Approvals · Receipts        │
│ Audit trail · Cost controls · Reliability · Observability          │
│                                                                    │
│ Decide what is allowed, what counts as success, and what occurred. │
└────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌────────────────────────────────────────────────────────────────────┐
│ TVASTAR REFERENCE SOLUTIONS                                        │
│ Verified CI repair · Incident response · Compliance                │
│ Security remediation · Outbound · Other built examples             │
│                                                                    │
│ Concrete applications built from the same Core, Control, and       │
│ Assurance layers.                                                  │
└────────────────────────────────────────────────────────────────────┘
```

| Rack | What it gives you | Start here when… |
|---|---|---|
| **Tvastar Core** | The runtime for defining and running an agent with models, tools, sessions, sandboxes, and state. | You need one agent to complete one task or conversation. |
| **Tvastar Control** | The operational layer for recurring, asynchronous, multi-step, or multi-agent work. | A single harness run needs a workflow, background dispatch, retry, handoff, or routing. |
| **Tvastar Assurance** | The evidence and policy layer around agent action and acceptance. | The work needs verification, approvals, governance, receipts, cost limits, or operational visibility. |
| **Tvastar Reference Solutions** | Inspectable applications that demonstrate the architecture under real workflows. | You want a concrete starting point, especially verified CI repair. |

Start with **Core**. Add **Control** only when work must be operated over time or across agents. Add **Assurance** when an action needs policy, evidence, or an explicit acceptance condition. The reference solutions prove how the same layers combine in real workflows.

For each component, its responsibilities, source location, data flow, and selection guidance, see the [Architecture Map](docs/ARCHITECTURE_MAP.md).

A quality finding can surface suspicious behavior, and a passing named check can validate a defined task. Neither is a universal proof of correctness, security, or safety. See [Benchmarks](docs/BENCHMARKS.md) for the scope and limitations of the repository's detector evaluation.

## Start with a verified repair

Install Tvastar with the model provider you intend to use:

```bash
pip install "tvastar[anthropic]"
export ANTHROPIC_API_KEY="..."
```

Run it from a project with a failing test suite:

```bash
tvastar-fix --path . --test-cmd "pytest -q" --check
```

`tvastar-fix` runs the test command before editing, gives the agent access to the failure, and reruns the same command afterward. `--check` makes the command exit non-zero if the suite is still failing. It reports `already-green`, `fixed`, or `unfixed`; it does **not** push changes or create a pull request for you.

The model resolver also supports `GROQ_API_KEY`, `OPENAI_API_KEY`, a running local Ollama instance, or an explicit OpenAI-compatible endpoint. See the [first-run CI repair guide](docs/GETTING_STARTED.md#first-verified-action-ci-repair) for the supported setup paths.

## Embed the harness in Python

```python
import asyncio

from tvastar import Harness, create_agent, default_toolset
from tvastar.model import AnthropicModel

agent = create_agent(
    "test-fixer",
    model=AnthropicModel("claude-sonnet-4-6"),
    instructions="Inspect the workspace, fix the failing tests, and report what changed.",
    tools=default_toolset(),
)

async def main() -> None:
    result = await Harness(agent).run("Run the tests and fix the underlying defect.")
    print(result.text)
    print(result.ok)  # Runtime/quality outcome; add a named check for task acceptance.

asyncio.run(main())
```

Use a persistent store when a session must survive a process restart:

```python
from tvastar import Harness
from tvastar.memory.store import FileStore

harness = Harness(agent, store=FileStore(".tvastar-state"))
result = await harness.run("Continue the repair.", session_id="ci-repair-42")
resumed = harness.resume("ci-repair-42")
```

`InMemoryStore` is the default, so it does not provide restart recovery. Persistent state is a configuration choice, not an unconditional guarantee.

## Safety and verification boundaries

- **Use a task-specific verifier for a task-specific claim.** Loop verification accepts a `VerificationContract`; a missing, failed, or malformed required verifier fails the loop run. The CI repair workflow's verifier is the independently rerun test command.
- **Detection is post-hoc evidence, not prevention.** Built-in detectors can report failure signals after a run; use governance, approval gates, and an appropriate execution boundary to limit actions before they happen.
- **`VirtualSandbox` is not a security boundary.** It is the convenient default for tests and trusted development. `LocalSandbox` contains a relative `cwd` beneath its configured root, but commands still run on the host; use a container or remote sandbox when isolation is required.
- **Serving controls are opt-in.** `create_app(..., authenticator=..., max_prompt_size=..., max_active_runs=...)` persists authenticated tenant-and-subject session ownership, rejects unknown or foreign sessions, and serializes a session's runs. In a multi-worker or container deployment, use one durable shared store for session and ownership state; the active-run limit is per application process.
- **Receipts are integrity evidence, not third-party attestation.** See the [threat model](docs/threat-model.md) for trust boundaries and remaining risks.

## Documentation

The full documentation map is in **[docs/README.md](docs/README.md)**.

| Start here | Build and extend | Operate and govern |
|---|---|---|
| [Getting Started](docs/GETTING_STARTED.md) | [Usage Guide](docs/USAGE.md) | [Threat Model](docs/threat-model.md) |
| [Examples](examples/README.md) | [API Reference](docs/API.md) | [SLOs](docs/slo.md) |
| [Cookbook](docs/COOKBOOK.md) | [Cookbook recipes](docs/COOKBOOK.md#core-concepts) | [Failure Modes](docs/failure-modes.md) and [Runbooks](docs/runbooks/) |
| [Benchmarks and limitations](docs/BENCHMARKS.md) | [Architecture map](docs/ARCHITECTURE_MAP.md) and [decisions](docs/ARCHITECTURE.md) | [Security Policy](SECURITY.md) |

Advanced control-plane features—loops, workflows, dispatch, multi-agent Fleet, and MCP—are documented as optional compositions. Start with the harness and a concrete success condition first.

## Install extras

```bash
pip install "tvastar[anthropic]"  # Anthropic models
pip install "tvastar[openai]"     # OpenAI-compatible providers and Ollama
pip install "tvastar[litellm]"    # LiteLLM provider integration
pip install "tvastar[serve]"      # HTTP/WebSocket serving
pip install "tvastar[all]"        # Common optional integrations
```

Tvastar requires **Python 3.11+**. The core package has no runtime dependencies; integrations are optional extras.

## CLI

```bash
tvastar run agent.py:agent "summarize this report"  # one-shot prompt
tvastar chat agent.py:agent                          # interactive session
tvastar serve agent.py:agent --port 8000             # HTTP/WebSocket server
tvastar quality agent.py:agent "review this change" # run and inspect quality
tvastar-fix --test-cmd "pytest -q" --check           # verified test repair
tvastar-ci run                                        # configured local CI cycle
tvastar loop --help                                   # scheduled/retrying loop tools
```

## Contributing and security

- [Contributing](CONTRIBUTING.md)
- [Security policy](SECURITY.md)
- [Changelog](CHANGELOG.md)

## License

[Apache 2.0](LICENSE)
