batchor 0.0.1__tar.gz

batchor-0.0.1/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "batchor-local",
+  "interface": {
+    "displayName": "Batchor Local"
+  },
+  "plugins": [
+    {
+      "name": "batchor-agent-tools",
+      "source": {
+        "source": "local",
+        "path": "./plugins/batchor-agent-tools"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Coding"
+    }
+  ]
+}

batchor-0.0.1/.agents/skills/batchor-dev/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: batchor-dev
+description: Use when working in the batchor repository to implement or review library, CLI, runtime, provider, storage, source, or documentation changes. Follow AGENTS.md smoke-test rules, prefer the relevant design docs before editing, and keep README plus design docs aligned when behavior changes.
+---
+
+# Batchor Dev
+
+Use this skill for normal contributor work in this repository.
+
+## Start here
+
+1. Read `AGENTS.md` for required validation and doc-maintenance rules.
+2. Read `README.md` for the public mental model and current scope.
+3. Load only the design docs that match the task:
+   - `docs/design_docs/ARCHITECTURE.md` for package layout and runtime boundaries
+   - `docs/design_docs/OPENAI_BATCHING.md` for provider-specific batching behavior
+   - `docs/design_docs/STORAGE_AND_RUNS.md` for durable state, run lifecycle, and retention
+   - `docs/smoke-test.md` for the full validation matrix
+
+## Repo map
+
+- `src/batchor/runtime/`: orchestration, run handles, validation, retry, token budgeting
+- `src/batchor/providers/`: provider interfaces and OpenAI Batch implementation
+- `src/batchor/storage/`: SQLite, Postgres, and in-memory durability backends
+- `src/batchor/sources/`: file-backed checkpointable item sources
+- `src/batchor/artifacts/`: durable request/output artifact handling
+- `src/batchor/cli.py`: operator CLI surface
+- `tests/unit/` and `tests/integration/`: main regression coverage
+
+## Validation rules
+
+- Required smoke path after refactors or behavior-changing edits: `uv run pytest -q`
+- Also run `uv run ty check src` when changing provider wiring, storage wiring, token budgeting, or run lifecycle behavior.
+- Do not weaken the `85%` coverage gate or disable coverage on the main smoke path.
+- If docs or navigation change, also run `uv run mkdocs build --strict`.
+
+## Working style
+
+- Keep changes library-first. New orchestration behavior should usually land in the runtime or provider layers before the CLI.
+- Preserve durable-run invariants. Resume, replay, artifact retention, and terminal-result behavior are core repo constraints.
+- When behavior changes, update `README.md` and the relevant docs in `docs/design_docs/` in the same change.

batchor-0.0.1/.agents/skills/batchor-dev/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Batchor Dev"
+  short_description: "Repo guidance for batchor code, docs, and validation"
+  default_prompt: "Use $batchor-dev to work in this batchor repository, follow AGENTS.md, and keep validation plus docs aligned with the change."
+
+policy:
+  allow_implicit_invocation: true

batchor-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,145 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  gitleaks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Sync dependencies
+        run: uv sync --all-groups
+
+      - name: Lint (ruff check)
+        run: uv run ruff check src
+
+      - name: Format check (ruff format)
+        run: uv run ruff format --check src
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Sync dependencies
+        run: uv sync --all-groups
+
+      - name: Type check
+        run: uv run ty check src
+
+      - name: Test
+        run: uv run pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Sync dependencies
+        run: uv sync --all-groups
+
+      - name: Build
+        run: uv build
+
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Sync dependencies
+        run: uv sync --all-groups
+
+      - name: Build docs
+        run: uv run mkdocs build --strict
+
+  postgres-contract:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_DB: postgres
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      BATCHOR_TEST_POSTGRES_DSN: postgresql+psycopg://postgres:postgres@127.0.0.1:5432/postgres
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Sync dependencies
+        run: uv sync --all-groups
+
+      - name: Postgres storage contract tests
+        run: uv run pytest tests/unit/test_batchor_storage_contracts.py --no-cov -q

batchor-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Sync docs dependencies
+        run: uv sync --group docs
+
+      - name: Build docs
+        run: uv run mkdocs build --strict
+
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy GitHub Pages site
+        id: deployment
+        uses: actions/deploy-pages@v4

batchor-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Sync dependencies
+        run: uv sync --all-groups
+
+      - name: Type check
+        run: uv run ty check src
+
+      - name: Test
+        run: uv run pytest -q
+
+      - name: Build
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    needs: build-test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

batchor-0.0.1/.gitignore

@@ -0,0 +1,49 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*$py.class
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.pyre/
+.hypothesis/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Build and packaging artifacts
+build/
+dist/
+site/
+*.egg-info/
+.eggs/
+pip-wheel-metadata/
+
+# Internal planning docs
+docs/plans/
+plans/
+
+# Coverage and test outputs
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+tmp/
+# Environment and local config
+.env
+.env.*
+*.env
+
+# IDE and editor files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db

batchor-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: ty-check
+        name: ty type check
+        entry: uv run ty check src
+        language: system
+        pass_filenames: false
+        types: [python]

batchor-0.0.1/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md
+
+## Mandatory Smoke Tests
+
+- After any refactor or behavior-changing code edit, run a smoke test before marking work complete.
+- Overall test coverage must stay at or above `85%`. Do not merge changes that require lowering the configured coverage gate.
+- Minimum required smoke test:
+  - extracted repo root: `uv run pytest -q`
+  - monorepo subproject: `cd batchor && uv run pytest -q`
+- The default pytest configuration enforces the coverage gate and runs in parallel. Do not disable coverage for the main smoke path.
+- For changes to provider wiring, storage wiring, token budgeting, or run lifecycle behavior, also run:
+  - `uv run ty check src`
+  - the targeted fake-provider integration suite when relevant
+- In the final report, include:
+  - the smoke command(s) executed
+  - pass/fail outcome
+  - any blocker if a smoke test could not be executed
+
+## Mandatory Doc Maintenance
+
+- When adding a major feature or changing library behavior, update relevant docs in `docs/` in the same change.
+- When changing test workflow or validation policy, update the relevant developer docs in the same change.
+- At minimum, check and update:
+  - `README.md`
+  - `docs/design_docs/ARCHITECTURE.md`
+  - `docs/design_docs/OPENAI_BATCHING.md`
+  - `docs/design_docs/STORAGE_AND_RUNS.md`
+  - `docs/smoke-test.md`
+- If a design area is not implemented yet, keep the section and mark it `TBD` instead of omitting it.
+
+## Repo Agent Helpers
+
+- Repo-local skill: `.agents/skills/batchor-dev/`
+- Repo-local plugin marketplace: `.agents/plugins/marketplace.json`
+- Repo-local MCP plugin: `plugins/batchor-agent-tools/`
+- VS Code workspace MCP config: `.vscode/mcp.json`
+- Prefer these when an agent needs quick orientation on repo structure, docs, or validation commands.

batchor-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Issues and pull requests are welcome for the noncommercial open-source package.
+
+Before submitting changes:
+
+- run `uv run ty check src`
+- run `uv run pytest -q`
+- run `uv run mkdocs build --strict`
+- run `uv build`
+- update docs when behavior, workflow, or validation policy changes
+
+Please keep changes aligned with the documented package boundary:
+
+- durable batch execution
+- OpenAI Batch provider support
+- SQLite-backed local durability by default
+
+Out-of-scope proposals are still useful, but should usually start as an issue discussing fit before implementation.

batchor-0.0.1/LICENSE

@@ -0,0 +1,73 @@
+# PolyForm Noncommercial License 1.0.0
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+Required Notice: Copyright 2026 batchor contributors
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.