avo 0.1.0__tar.gz

avo-0.1.0/.env.example

@@ -0,0 +1,57 @@
+# Avo provider configuration
+#
+# Copy this file to `.env` (which is git-ignored) and fill in only the
+# variables that apply to your deployment. Never commit a `.env` file with
+# real API keys.
+
+# ---------------------------------------------------------------------------
+# Provider selection (required)
+# ---------------------------------------------------------------------------
+
+# ollama | minimax | anthropic | openai
+AVO_PROVIDER=
+
+# Default model name for the active provider
+AVO_MODEL=
+
+# ---------------------------------------------------------------------------
+# Ollama (local, typically no API key)
+# ---------------------------------------------------------------------------
+
+# SOTERIA_OLLAMA_BASE_URL=http://localhost:11434
+# SOTERIA_OLLAMA_MODEL=
+# SOTERIA_OLLAMA_API_KEY=
+
+# ---------------------------------------------------------------------------
+# MiniMax
+# ---------------------------------------------------------------------------
+
+# SOTERIA_MINIMAX_API_KEY=
+# SOTERIA_MINIMAX_BASE_URL=https://api.minimax.io
+# SOTERIA_MINIMAX_MODEL=
+# SOTERIA_MINIMAX_API_STYLE=anthropic
+
+# ---------------------------------------------------------------------------
+# Anthropic
+# ---------------------------------------------------------------------------
+
+# SOTERIA_ANTHROPIC_API_KEY=
+# SOTERIA_ANTHROPIC_MODEL=
+# SOTERIA_ANTHROPIC_BASE_URL=https://api.anthropic.com
+
+# ---------------------------------------------------------------------------
+# OpenAI (and OpenAI-compatible self-hosted endpoints)
+# ---------------------------------------------------------------------------
+
+# SOTERIA_OPENAI_API_KEY=
+# SOTERIA_OPENAI_MODEL=
+# SOTERIA_OPENAI_BASE_URL=https://api.openai.com/v1
+
+# ---------------------------------------------------------------------------
+# Runtime overrides (optional)
+# ---------------------------------------------------------------------------
+
+# SOTERIA_DATABASE_PATH=
+# SOTERIA_MAX_TOTAL_TOKENS=
+# SOTERIA_MAX_RUNTIME_SECONDS=
+# SOTERIA_REPEATED_ACTION_LIMIT=

avo-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Report a bug in Avo
+title: "[bug] "
+labels: bug
+---
+
+**Describe the bug**
+A clear description of what happens vs. what you expected.
+
+**Reproduction**
+Minimal code or commands that reproduce the issue. Include provider
+(`AVO_PROVIDER`) and model (`AVO_MODEL`) where applicable.
+
+**Environment**
+- Avo version (`pip show avo` or `python -c "import avo; print(avo.__version__)"`)
+- Python version
+- Provider (Ollama / MiniMax / Anthropic / OpenAI / OpenAI-compatible)
+- OS
+
+**Logs / trace**
+If available, paste a `avo --database avo.db runs inspect RUN_ID`
+trace excerpt.
+
+**Notes**
+Anything else that might be relevant (e.g. was a paid model invoked,
+is the bug reproducible on the deterministic `FakeProvider`).

avo-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,38 @@
+---
+name: Pull request
+about: Propose changes to the Avo runtime or its tooling
+title: ""
+labels:---
+
+## Summary
+
+<!-- One-paragraph description of what this PR does and why. -->
+
+## Linked issues
+
+<!-- Link any issue this closes, e.g. "Closes #42". -->
+
+## Quality gates
+
+- [ ] `make lint`
+- [ ] `make format-check`
+- [ ] `make typecheck`
+- [ ] `make test` — 219+ tests passing
+- [ ] No new runtime dependency unless justified in the PR description
+- [ ] Offline tests added for any new public surface
+
+## Provider or state-machine changes
+
+If your PR touches `src/avo/providers/` or
+`src/avo/runtime.py`, confirm:
+
+- [ ] No change to the public `ModelProvider` Protocol contract
+- [ ] No change to the `STOP_REASONS_BY_STATE` mapping without
+  updating `src/avo/state.py` and the README stop-reasons list
+- [ ] No change to event ordering or sequence invariants
+
+## Docs
+
+- [ ] README updated if the public API changed
+- [ ] `project.md` updated if a new module was added
+- [ ] `CHANGELOG.md` entry under `[Unreleased]`

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

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Ruff lint
+        run: ruff check .
+      - name: Ruff format
+        run: ruff format --check .
+      - name: Mypy
+        run: mypy src/avo
+      - name: Tests
+        run: pytest
+      - name: Build
+        run: python -m build

avo-0.1.0/.gitignore

@@ -0,0 +1,233 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Live benchmark runtime results
+benchmark/live/results/*
+!benchmark/live/results/.gitkeep
+
+
+.claude/
+.superpowers/
+CLAUDE.md
+project.md 
+NEXT-UPDATE.md
+soteria.db
+soteria_loop.db
+*.db

avo-0.1.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to Avo are recorded here. Versions follow
+[Semantic Versioning](https://semver.org/). The first public release
+is **0.1.0**.
+
+## [Unreleased]
+
+### Added
+
+- `src/avo/config.py` — single-entry `build_provider_from_env`
+  factory that dispatches `AVO_PROVIDER` to the right provider
+  config (`ollama`, | `minimax`, | `anthropic`, | `openai`).
+- `src/avo/providers/ollama.py` — native `/api/chat` adapter.
+- `src/avo/providers/anthropic.py` — Messages API adapter
+  with `tool_use` block parsing.
+- `src/avo/providers/openai_compatible.py` — OpenAI
+  Chat-Completions adapter that also covers self-hosted gateways.
+- `src/avo/providers/minimax.py` — new `from_avo_env`
+  constructor alongside the legacy benchmark `from_env` path.
+- `src/avo/app_tools/workspace.py` — `Workspace` class and
+  `validate_path` helper. Rejects `..`, absolute escapes, symlink
+  leaves, null bytes, and empty strings.
+- `src/avo/app_tools/approval.py` — `build_approval_callback`
+  reading `AVO_TOOLS_REQUIRE_APPROVAL`.
+- `src/avo/app_tools/file_tools.py` — `read_file_tool` and
+  `write_file_tool` bound through `bind_workspace`.
+- `src/avo/chat.py` — interactive REPL that drives one
+  `AgentRuntime.run(...)` invocation per user line. Slash commands:
+  `/provider`, / `/inspect RUN_ID`, / `/resume RUN_ID`, / `/quit`.
+- `avo chat` — new CLI subcommand (slice 0.4 of the
+  roadmap). Delegates to existing `build_provider_from_env`,
+  `Workspace`, `bind_workspace`, file tools, and `SQLiteEventStore`.
+- `.env.example` — empty placeholder template.
+- `examples/app_tools_demo.py` — offline walk-through of the workspace
+  + approval tools.
+
+### Quality
+
+- 219 offline tests across `tests/` (workspace traversal, approval,
+  provider HTTP-mock, resume, state, SQLite parity).
+- mypy strict, ruff lint + format, coverage gate `fail_under = 90`.
+
+## [0.1.0] — 2026-07-20
+
+Initial alpha foundation. Provider-agnostic async state machine,
+append-only event history, deterministic `FakeProvider`, SQLite-backed
+event store with resume, stop-reason taxonomy (13 enum values).
+See the README for the user-facing overview.

avo-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Code of Conduct
+
+Avo contributors are expected to make participation respectful, safe, and
+welcoming.
+
+## Expected behavior
+
+- Be considerate, patient, and constructive.
+- Discuss ideas and code without personal attacks.
+- Respect differing experience, identity, background, and viewpoint.
+- Give and receive technical feedback in good faith.
+- Protect private information and report security-sensitive details privately.
+
+Harassment, discriminatory language, threats, unwanted sexual attention,
+doxxing, and sustained disruption are not acceptable in project spaces.
+
+## Enforcement
+
+Project maintainers may edit or remove contributions and temporarily or
+permanently restrict participation when behavior violates these expectations.
+Enforcement decisions should be proportionate, documented privately, and
+handled with care for affected people.
+
+Report conduct concerns to the repository owner through a private channel listed
+on the project profile. Reports will be reviewed as promptly and confidentially
+as practical. Good-faith reporters will not face retaliation.
+
+This policy applies to repository discussions, pull requests, community spaces,
+and public interactions made while representing Avo.

avo-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to Avo
+
+Avo welcomes focused changes that improve boundedness, observability,
+recovery, or safety without expanding the project into a general agent
+framework.
+
+## Environment setup
+
+Use Python 3.11 or newer:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+No API key or network access is needed after development dependencies are
+installed.
+
+## Local checks
+
+Run the same gates used by CI:
+
+```bash
+ruff check .
+ruff format --check .
+mypy src/avo
+pytest
+python -m build
+```
+
+To measure core coverage:
+
+```bash
+coverage run -m pytest
+coverage report
+```
+
+Run all offline examples and regenerate the benchmark when runtime behavior
+changes:
+
+```bash
+python examples/basic_agent.py
+python examples/repeated_action.py
+python examples/resume_after_interrupt.py
+python benchmark/run_benchmark.py
+```
+
+## Contribution workflow
+
+1. Open an issue for substantial API or event-schema changes.
+2. Create a focused branch and keep commits reviewable.
+3. Preserve append-only history, state validation, and terminal-event
+   invariants.
+4. Add deterministic behavioral tests for every behavior change or bug fix.
+5. Update `README.md`, `DESIGN.md`, examples, and benchmark results
+   when user-visible contracts change.
+6. Run every local check before opening a pull request.
+
+Avoid real API calls in the default test suite. Error messages should name the
+run, tool, provider operation, or database involved and explain what the user
+can do next.
+
+## Pull requests
+
+Describe the execution behavior before and after the change, the failure modes
+considered, and the checks run. If the change affects persistence or resume,
+include a close/reopen test and a failure-injection test at the relevant
+checkpoint boundary.
+
+By participating, you agree to follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

avo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FaqihHakim
+
+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.

avo-0.1.0/Makefile

@@ -0,0 +1,42 @@
+.PHONY: install dev lint format typecheck test test-app-tools benchmark clean build
+
+PYTHON ?= python
+
+install:
+	$(PYTHON) -m pip install -e .
+
+dev:
+	$(PYTHON) -m pip install -e ".[dev]"
+
+lint:
+	$(PYTHON) -m ruff check .
+
+format:
+	$(PYTHON) -m ruff format .
+
+format-check:
+	$(PYTHON) -m ruff format --check .
+
+typecheck:
+	$(PYTHON) -m mypy src/soteria_loop
+
+test:
+	$(PYTHON) -m pytest
+
+test-app-tools:
+	$(PYTHON) -m pytest tests/test_workspace.py tests/test_approval.py tests/test_file_tools.py -v
+
+benchmark:
+	$(PYTHON) benchmark/run_benchmark.py
+
+build:
+	$(PYTHON) -m build
+
+clean:
+	rm -rf build dist *.egg-info src/*.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .pytest_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .mypy_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .ruff_cache -exec rm -rf {} + 2>/dev/null || true
+
+all-gates: lint format-check typecheck test