agent-once 0.1.0__tar.gz

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

@@ -0,0 +1,119 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev,postgres,stripe]" mcp langchain-core langgraph
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+
+  # Linux runs every test against both SQLite and a Postgres service container.
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: once_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 2s
+          --health-timeout 5s
+          --health-retries 30
+    env:
+      ONCE_TEST_POSTGRES_DSN: postgresql://postgres:postgres@localhost:5432/once_test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev,postgres]"
+      - run: pytest -q --cov=once --cov-report=term-missing
+      - if: matrix.python-version == '3.12'
+        run: pytest -q -m heavy tests/test_stress.py
+
+  # Service containers only run on Linux, so these skip the Postgres tests and
+  # leave postgres.py out of the coverage floor.
+  test-other:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: pytest -q --cov=once --cov-fail-under=0
+      - run: coverage report --omit="*postgres.py" --fail-under=95 --show-missing
+
+  integrations:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        mcp: ["mcp<2", "mcp>=2"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev,stripe]" langchain-core langgraph "${{ matrix.mcp }}"
+      - run: pytest -q tests/test_integrations.py tests/test_integrations_mcp.py tests/test_integrations_langchain.py tests/test_integrations_stripe.py
+      - run: python examples/stripe_example.py
+      - run: python examples/langgraph_example.py
+      - run: python examples/mcp_server.py --demo
+      - run: pytest -q -m heavy tests/test_stress.py
+
+  # One environment per framework, since their pins conflict (crewai wants openai<3).
+  adapters:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - framework: openai_agents
+            extra: openai-agents
+          - framework: pydantic_ai
+            extra: pydantic-ai
+          - framework: crewai
+            extra: crewai
+    env:
+      CREWAI_DISABLE_TELEMETRY: "true"
+      OTEL_SDK_DISABLED: "true"
+      PYDANTIC_AI_NO_BANNER: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev,${{ matrix.extra }}]"
+      - run: python examples/${{ matrix.framework }}_example.py
+      - run: pytest -q tests/test_integrations_${{ matrix.framework }}.py tests/test_integrations_adapters.py
+      - run: >-
+          mypy --python-version 3.12 src/once/integrations/${{ matrix.framework }}.py
+          tests/test_integrations_${{ matrix.framework }}.py examples/${{ matrix.framework }}_example.py

agent_once-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Docs
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -r requirements-docs.txt
+      - run: mkdocs build --strict
+      - if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      # Skip, don't fail, until Settings > Pages > Source is set to GitHub Actions.
+      - id: pages
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh api "repos/$GITHUB_REPOSITORY/pages" > /dev/null 2>&1; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "::notice::GitHub Pages is not enabled, skipping deploy"
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+          fi
+      - id: deployment
+        if: steps.pages.outputs.enabled == 'true'
+        uses: actions/deploy-pages@v4

agent_once-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agent-once
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

agent_once-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+*.db
+*.db-wal
+*.db-shm
+.coverage
+coverage.xml
+htmlcov/
+site/
+.hypothesis/

agent_once-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First release.
+
+- `Once` with `@once.tool`, `execute` and `aexecute`, backed by SQLite.
+- Records move through pending, done, failed and unknown. Failed and unknown are never re-run on their own.
+- `verify` callbacks and `stale_after` to resolve unknown and abandoned pending records.
+- Async tools, `timeout=`, cancellation marks unknown. Sync and async callers in one process wait for each other.
+- `once` command line tool: `ls`, `show`, `reset`, `gc`. `Once.records()` and `Once.purge()`.
+- `Once.close()`, and `Once` works as a context manager.
+- `exclude=` on `once.tool` to leave parameters out of the key.
+- `once.integrations.mcp` and `once.integrations.langchain` decorators, with examples.
+- `once.integrations.openai_agents`, `once.integrations.pydantic_ai` and `once.integrations.crewai` decorators, with examples and extras. The `crewai` and `openai-agents` extras can't be installed together. Pydantic AI tools take their scope from `scope_arg`, then `scope_from(ctx)`, then the enclosing `once.scope()` (read with `current_scope()`), then `ctx.conversation_id`, or `ctx.run_id` with `scope="run"`.
+- The framework helpers take `ttl=`.
+- `PostgresStore` for workers on several machines, behind the `postgres` extra. Use `Once("postgresql://...")` or `Once(store=PostgresStore(dsn, table=...))`. The CLI accepts a Postgres URL for `--db` and has a `--table` option.
+- `Store` protocol, so `Once(store=...)` takes any backend that implements it.
+- `once.verifiers`: `stripe_verifier` and `stripe_params` for Stripe charges, PaymentIntents and refunds (`stripe` extra, or pass a client), and `http_verifier` for any API that can look an effect up by key. `stripe_verifier` falls back to listing when search isn't available to the account.
+- `ttl=` on `Once`, `@once.tool`, `execute` and `aexecute`. Done records expire and the next call runs again; failed and unknown never expire. Stored in a new `expires_at` column, added to existing SQLite and Postgres tables on open. `once gc --expired` and `Once.purge(expired=True)` delete expired records.
+- `current_scope()` returns the active `once.scope()` value. An `idempotency_key` parameter that gets `""` or `None` now means "no key", so one is computed. A `""` default used to become the key itself, so two tools with that default hit `KeyConflict`.
+- `expires_at` is indexed in both stores, so `gc --expired` doesn't scan the whole table. The index is added to existing tables on open.
+- `Once(hooks=Hooks(...))` with `on_claim`, `on_done`, `on_failed`, `on_unknown` and `on_replay`. Hooks get an `Event`, may be async under `aexecute`, and an error in one is logged, not raised.
+- OpenTelemetry spans (`once <tool_name>`) behind the `otel` extra. No-op without a configured tracer.
+
+Fixes from a review before the release:
+
+- A sync call with `timeout=` runs in a thread that keeps the caller's context, so `once.scope()` and tracing still apply inside it.
+- A `ttl` that would expire after year 9999 is treated as never expiring instead of raising `OverflowError`.
+- A claim is given back if the call is interrupted (or an async store step is cancelled) before the tool starts, so the key isn't left pending.
+- Storing the outcome is retried once after a store error, so a dropped connection doesn't leave a finished call pending.
+- Calling the same key from inside its own call raises `OnceError` instead of deadlocking. This includes a sync call inside an async owner.
+- `exclude=` names that are not parameters of the function raise an error.
+- `EffectUnknown` is raised even if the record was reset while the call was finishing.
+- `stripe_verifier` reads the status of the object it finds: failed or canceled counts as not happened, and a status still in flux raises `StripeInconclusive` so the record stays unknown. It also stays unknown when the list scan runs out before the end.
+- `http_verifier` JSON-encodes non-string arguments in the URL, and rejects an argument named `key` that would clash with `{key}`.
+- `PostgresStore` takes `statement_timeout` (30 seconds by default) and retries a statement once after a dropped connection. Postgres URLs are accepted in any case and with `+psycopg`.
+- The CLI refuses SQLite files without an effects table and rejects a negative `--limit`.
+- JSON errors name the argument or the verify function that couldn't be serialized.
+- README and docs have a Gotchas section.
+
+Changes made before the release that break keys from earlier development builds:
+
+- `make_key` is now `sha256(canonical_json([tool_name, args, scope]))`. It used to concatenate the parts, which let some tool names and scopes collide.
+- `canonical_json` now escapes non-ASCII characters (`ensure_ascii=True`), so strings with lone surrogates can be hashed.

agent_once-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Bug reports and pull requests are welcome. For anything bigger than a small fix, open an issue first so we can agree on the approach.
+
+## Setup
+
+```
+python -m venv .venv
+.venv/bin/pip install -e '.[dev,postgres,stripe]'
+```
+
+## Checks
+
+CI runs these, so run them before opening a pull request:
+
+```
+.venv/bin/ruff format --check .
+.venv/bin/ruff check .
+.venv/bin/mypy src tests
+.venv/bin/python -m pytest
+```
+
+The Postgres tests are skipped unless `ONCE_TEST_POSTGRES_DSN` points at a database they can create tables in, for example `postgresql://postgres:postgres@localhost:5432/once_test`. Slow stress tests are marked `heavy` and run with `pytest -m heavy`.
+
+The docs site is MkDocs Material:
+
+```
+pip install -r requirements-docs.txt
+mkdocs serve
+```
+
+## Pull requests
+
+- Add a test for a bug fix or new behavior.
+- Update the README, the docs and `CHANGELOG.md` when behavior changes.
+- Keep changes to stored keys and the table schema backward compatible, or say clearly in the changelog that they are not.

agent_once-0.1.0/LICENSE

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