tvastar 0.1.0__tar.gz

tvastar-0.1.0/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:flueframework.com)",
+      "WebFetch(domain:github.com)",
+      "Bash(which uv *)",
+      "Bash(uv --version)",
+      "Bash(uv venv *)",
+      "Bash(uv pip *)",
+      "Bash(uv run *)",
+      "Bash(INPUT_PROMPT=\"List files and summarize\" uv run python examples/deploy/github_action_entry.py)",
+      "Bash(export GROQ_API_KEY=\"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\")",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" \"https://pypi.org/pypi/tvastar/json\")",
+      "Bash(rm -rf dist)",
+      "Bash(uv build *)"
+    ]
+  }
+}

tvastar-0.1.0/.github/workflows/agent.yml

@@ -0,0 +1,35 @@
+name: Tvastar Agent
+
+# Run a Tvastar agent as a CI job — on demand, or wire it to issues/PRs.
+on:
+  workflow_dispatch:
+    inputs:
+      prompt:
+        description: "What should the agent do?"
+        required: true
+        default: "List the files in the workspace and summarize the project."
+
+jobs:
+  run-agent:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install Tvastar
+        run: uv pip install --system -e ".[anthropic]"
+
+      - name: Run agent
+        id: agent
+        env:
+          # Offline-safe default; set TVASTAR_REAL=1 + the secret to use Claude.
+          INPUT_PROMPT: ${{ github.event.inputs.prompt }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: python examples/deploy/github_action_entry.py
+
+      - name: Show result
+        run: |
+          echo "Agent finished with: ${{ steps.agent.outputs.stopped }}"
+          echo "${{ steps.agent.outputs.result }}"

tvastar-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (all extras + dev)
+        run: uv pip install --system -e ".[all,dev]"
+
+      - name: Lint
+        run: ruff check tvastar/ examples/ tests/
+
+      - name: Format check
+        run: ruff format --check tvastar/ examples/ tests/
+
+      - name: Tests
+        run: pytest -q

tvastar-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+build/
+dist/
+
+# Tvastar runtime artifacts
+.tvastar-workspace/
+.tvastar-state/
+*-trace.jsonl
+tvastar-trace.jsonl
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

tvastar-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to Tvastar are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-06-04
+
+Initial release. Tvastar is a programmable agent harness for Python:
+`Agent = Model + Harness`.
+
+### Added
+
+- **Core harness** — the model↔tool agent loop, `Session`, `Harness`, and
+  `create_agent` / `AgentSpec`.
+- **Model layer** — a provider-agnostic `Model` interface with adapters for
+  Anthropic (Claude), OpenAI (and any OpenAI-compatible endpoint via `base_url`:
+  Cloudflare Workers AI, Groq, Together, Ollama, vLLM, …), and a scripted
+  `MockModel` for offline/testing.
+- **Tools** — the `@tool` decorator with automatic JSON-Schema generation from
+  type hints, a registry, and a built-in toolset (bash, read/write/edit, list,
+  glob, grep).
+- **Sandboxes** — pluggable execution: `VirtualSandbox` (in-memory, runs real
+  Python with no Docker), `LocalSandbox` (jailed subprocess), and external
+  adapters (`DockerSandbox`, generic `RemoteSandbox` for E2B/Daytona/Modal),
+  governed by a `SecurityPolicy`.
+- **Skills** — Markdown-with-frontmatter expertise packages, loaded on demand.
+- **Memory & durable execution** — in-memory and JSON-on-disk stores; full
+  transcript + filesystem checkpointing with crash-safe resume.
+- **MCP** — a Model Context Protocol client over stdio (local servers) and
+  streamable HTTP/SSE (remote servers); MCP tools mount as native tools.
+- **Failure detection** — in-process detectors for silent failures
+  (`unknown_tool`, `schema_mismatch`, `thrash_loop`, `ignored_tool_error`,
+  `unverified_completion`, `empty_answer`, `step_limit`), attached to
+  `RunResult.findings`.
+- **Observability** — span tracing with console, JSONL, and OpenTelemetry
+  exporters.
+- **Serving & deploy** — a CLI (`tvastar chat/serve/run/info`), a FastAPI
+  HTTP+WebSocket server, and deploy adapters for ASGI hosts, AWS Lambda,
+  GitHub Actions / GitLab CI, and generic FaaS.
+- Examples, a test suite, CI (lint + format + tests on Python 3.10–3.13), and a
+  live real-model proof run.
+
+[Unreleased]: https://github.com/vanamayaswanth/tvastar/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/vanamayaswanth/tvastar/releases/tag/v0.1.0

tvastar-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to Tvastar
+
+Thanks for your interest in improving Tvastar! This guide gets you set up and
+explains the conventions that keep the project small, fast, and reliable.
+
+## Quick start
+
+Tvastar uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone <your-fork-url>
+cd tvastar
+uv venv
+uv pip install -e ".[all,dev]"   # all optional features + test tooling
+```
+
+Run the test suite and linter:
+
+```bash
+uv run pytest -q          # tests (offline, no API keys needed)
+uv run ruff check .       # lint
+uv run ruff format .      # auto-format
+```
+
+Everything must be green before you open a pull request.
+
+## Project principles
+
+These are the rules the codebase is built on. Please keep to them:
+
+1. **The core has zero third-party dependencies.** Anything that needs an
+   external package (a model SDK, a web server, OpenTelemetry) goes behind an
+   optional extra and is imported **lazily, inside a `try/except ImportError`**
+   with a helpful message. `import tvastar` must always succeed.
+2. **Nothing observability- or detection-related may break a run.** Tracing and
+   failure detectors run in isolation; if they raise, the error is captured, not
+   propagated.
+3. **Reliability over strictness.** Helpers degrade gracefully (e.g. the schema
+   generator falls back to a permissive schema rather than raising).
+4. **Tests are offline and deterministic.** Use `MockModel` (scripted) and the
+   in-memory `VirtualSandbox`. Don't require network or API keys in tests.
+5. **Small, readable, typed.** Match the surrounding style; add type hints and a
+   one-line docstring to public functions.
+
+## Adding things
+
+- **A tool:** decorate a function with `@tool`; the JSON schema is derived from
+  its type hints. See `tvastar/tools/builtin.py`.
+- **A model provider:** if it has an OpenAI-compatible endpoint, no code is
+  needed — use `OpenAIModel(base_url=...)`. Otherwise subclass `Model` and
+  implement `generate()`. See `examples/custom_provider.py`.
+- **A sandbox backend:** implement the `Sandbox` interface. See
+  `tvastar/sandbox/`.
+- **A failure detector:** write a function `(RunContext) -> list[Finding]` and
+  add it to `default_detectors()` (or document it as opt-in). Keep it
+  high-precision — a noisy detector is worse than none. See `tvastar/detect/`.
+
+## Pull requests
+
+- Keep PRs focused; one logical change per PR.
+- Add or update tests for any behavior change.
+- Update the README if you change public API or add a feature.
+- Describe the motivation, not just the diff.
+
+## Reporting bugs
+
+Open an issue with a minimal reproduction (ideally using `MockModel` +
+`VirtualSandbox` so it runs anywhere) and what you expected to happen.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+project's [MIT License](LICENSE).

tvastar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the Tvastar authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.