chumak 0.1.0__tar.gz

chumak-0.1.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "fix"
+      prefix-development: "chore"
+      include: "scope"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci"
+      include: "scope"

chumak-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,81 @@
+name: 📦🚀 CI
+
+
+on:
+  push:
+    branches:
+      - '**'
+
+
+permissions:
+  contents: write
+  pull-requests: write
+
+
+env:
+  DEFAULT_PYTHON_VERSION: '3.13'
+
+
+jobs:
+  validation:
+    name: 🧪 Validation
+    if: ${{ !contains(github.event.head_commit.message, 'chore(main)') }}  # don't run on chore(main) commits (e.g. release - it already ran)
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ${{ github.ref == 'refs/heads/main' && fromJson('["3.13"]') || fromJson('["default"]') }}
+        os: ${{ github.ref == 'refs/heads/main' && fromJson('["ubuntu-latest", "macos-latest", "windows-latest"]') || fromJson('["ubuntu-latest"]') }}
+
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+      issues: none
+      pull-requests: none
+
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: corriander/gha/uv/test@main
+        env:
+          UV_PYTHON: ${{ matrix.python-version == 'default' && env.DEFAULT_PYTHON_VERSION || matrix.python-version }}
+
+  release:
+    name: 🚀 Release
+    runs-on: ubuntu-latest
+    needs: validation
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write  # for PyPI trusted publishing
+    if: |  # always run on default branch as long as no failures, even if validation is skipped
+      always()
+      && !contains(needs.*.result, 'failure')
+      && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    steps:
+      - uses: googleapis/release-please-action@v5
+        id: release
+        with:
+          release-type: python
+
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        if: steps.release.outputs.release_created
+
+      - name: Build
+        if: steps.release.outputs.release_created
+        run: uv build
+
+      - uses: svenstaro/upload-release-action@v2
+        if: steps.release.outputs.release_created
+        with:
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          file: dist/*
+          tag: ${{ steps.release.outputs.tag_name }}
+          file_glob: true
+          make_latest: false
+
+      - name: Publish to PyPI
+        if: steps.release.outputs.release_created
+        run: uv publish --trusted-publishing always

chumak-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.venv/
+venv/
+.python-version-local
+
+build/
+dist/
+*.egg-info/
+.eggs/
+
+.pytest_cache/
+.ruff_cache/
+.ty_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+
+.env
+.env.local
+.env.*.local
+
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+uv.lock.local

chumak-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

chumak-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 (2026-05-23)
+
+
+### Features
+
+* scaffold chumak inference substrate ([37187d8](https://github.com/corriander/chumak/commit/37187d84c775f43e1cfe3922769031e265dd169b))
+
+
+### Bug Fixes
+
+* **deps:** bump langchain-openai from 1.2.1 to 1.2.2 ([fc7bb6a](https://github.com/corriander/chumak/commit/fc7bb6a486a049a79a81806c12703ce528443444))

chumak-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing
+
+## Principles
+
+- **Keep the substrate thin.** chumak coordinates handlers, profiles, and meta. It does not own prompts, domain concepts, or secret management — those are consumer concerns.
+- **Handlers are pluggable.** Adding a transport (LangChain, subprocess, …) is dropping a module under `src/chumak/handlers/`, extending `HandlerType`, and registering it in `HANDLER_REGISTRY`. No edits in `surface.py` or `profile.py`.
+- **The library never reads env vars unprompted.** The profile env-overlay is the one exception, gated on the prefix the consumer passes to `ProfileLoader`.
+- **Prefer fixtures over hand-rolled setup.** See `tests/conftest.py` (`write_profile`, `make_loader`, `stub_handler`).
+
+## Dev setup
+
+```bash
+git clone <repo>
+cd chumak
+uv sync                         # core deps + dev tools (ruff, ty, pytest, pytest-mock, langchain-anthropic)
+uv sync --extra openai          # add when running the LangChain live integration test
+```
+
+Python 3.12+ (no 3.13-only syntax is used — keep it that way to stay broadly compatible with consumer projects).
+
+## Tests
+
+### Unit tests (default — fast, hermetic, no network)
+
+```bash
+uv run pytest
+```
+
+These cover every code path. The `stub_handler` fixture swaps the LangChain handler in `HANDLER_REGISTRY` for a deterministic fake so surface/meta tests never touch a real LLM. Use it when writing new tests that need a known `HandlerResult`.
+
+Profile-loader tests use `write_profile` to drop TOML files into a per-test tmp dir and `make_loader` to build a `ProfileLoader` pointed at it. Pass `env=` to inject a synthetic environment without mutating `os.environ`.
+
+### Integration test — LangChain handler against an OpenAI-compat backend
+
+Marker-gated, off by default. Exercises chumak end-to-end through a real LangChain `init_chat_model` call against any OpenAI-API-compatible server: llama.cpp, vLLM, LiteLLM, real OpenAI, etc. This is the test that proves the `openai:<model>` + `base_url` wiring still works after handler / langchain version bumps.
+
+```bash
+uv sync --extra openai                                # install langchain-openai
+uv run pytest --integration tests/test_langchain_live.py -v
+```
+
+Defaults: `http://localhost:8080/v1`, model `gpt-3.5-turbo`, dummy API key. Override per-run via env vars:
+
+```bash
+CHUMAK_TEST_OPENAI_URL=http://localhost:8000/v1 \
+CHUMAK_TEST_OPENAI_MODEL=qwen2.5-7b-instruct \
+  uv run pytest --integration tests/test_langchain_live.py -v
+```
+
+The test uses a tiny `ColourTag { colour: str, is_warm: bool }` schema — small enough that any reasonable 7B-class instruct model handles it. If you add coverage for a new handler or option, add a sibling test under the same marker and document the env vars it needs here.
+
+#### Why no subprocess live test?
+
+The subprocess handler is harder to gate (each CLI has its own auth / install requirements). Cover it with unit tests against a temporary script (`tests/test_subprocess_handler.py` does this), and rely on downstream consumers for true end-to-end exercise.
+
+## Quality checks
+
+Before opening a PR:
+
+```bash
+uv run ruff check .
+uv run ruff format .
+uv run ty check src tests
+```
+
+All three must pass clean. CI will run the same.
+
+## Adding a handler
+
+1. Module under `src/chumak/handlers/<name>.py` exporting a class with `execute(prompt, output_schema, profile) -> HandlerResult`.
+2. Add the discriminator to `HandlerType` in `src/chumak/handlers/types.py`.
+3. Register the class in `HANDLER_REGISTRY` (`src/chumak/handlers/__init__.py`).
+4. If the handler needs new profile fields, add them to `Profile` with the validator enforcing mutually-exclusive field sets per handler.
+5. Add unit tests via `stub_handler` for the surface side and direct handler tests for transport-specific quirks.
+
+## Adding a new profile field
+
+Profile fields live in `src/chumak/profile.py`. The validator enforces which handler types may use which fields — extend it when you add fields that only make sense for a specific handler. The env-overlay walker in `loader.py` picks them up automatically as long as they're declared on the `Profile` model.

chumak-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: chumak
+Version: 0.1.0
+Summary: Thin inference substrate: user-authored profiles, LangChain as a handler, optional provenance.
+Author-email: Alex Corrie <alex.j.corrie@gmail.com>
+Requires-Python: >=3.12
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: langchain>=0.3
+Requires-Dist: pydantic>=2.10
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic>=0.3; extra == 'anthropic'
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=1.2.2; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# chumak
+
+A thin **inference substrate** for Python projects: user-authored profiles, LangChain
+as a handler, optional provenance/meta on every response.
+
+> *Chumaks* (Чумаки) were wandering Ukrainian salt-traders who traversed the steppe
+> between distant places. They named the Milky Way after themselves —
+> *Чумацький Шлях*, the Chumaks' Way — because they navigated by it.
+
+## What it is
+
+A small library that abstracts away which LLM you're calling and how.
+
+1. Author **profiles** (TOML files) under the app's XDG config dir.
+2. Load a profile via `ProfileLoader` (with inheritance + env-var overrides)
+3. Call `infer(prompt=..., output_schema=..., profile=...)` and get back a validated
+   pydantic payload, normalised citations, and (optionally) a provenance `Meta` stamp.
+
+Two built-in handlers:
+
+- **`langchain`** — uses `langchain.chat_models.init_chat_model(profile.model)` so a
+  single identifier (`anthropic:claude-opus-4-7`, `openai:gpt-5`, …) routes to the
+  right provider. Structured output, citations, and token usage all handled.
+- **`subprocess`** — shells out to a CLI (`claude --print`, `codex exec`, etc.).
+  Useful for prompt iteration via an existing, authorised tool.
+  Schema is injected into the prompt as JSON Schema; stdout is parsed and validated.
+
+## Profiles
+
+Profiles are user-authored. chumak ships at most one generic example
+(`anthropic-claude-opus-4-7` via the LangChain handler). Everything else is yours.
+
+Profiles live in consumer app directory, e.g. `~/.config/<your-app>/chumak/profiles/`.
+chumak does not impose a config dir; the app passes `search_paths` to `ProfileLoader`.
+
+### File shape
+
+```toml
+# ~/.config/galops-vision/chumak/profiles/claude.toml
+handler = "langchain"
+model = "anthropic:claude-opus-4-7"
+temperature = 0.0
+
+[model_kwargs]
+max_tokens = 4096
+```
+
+### Inheritance
+
+```toml
+# claude-account-b.toml
+extends = "claude"
+
+[model_kwargs]
+# api_key sourced from env — see below
+```
+
+### Env-var overlay
+
+Every field on a profile is overridable from the environment. chumak does not
+provision special fields; the convention is uniform:
+
+```
+{APP_PREFIX}_PROFILE_{PROFILE_NAME}_{FIELD_PATH}
+```
+
+with `__` as the nested-field delimiter (single `_` stays inside field names):
+
+```sh
+# top-level field
+export MYAPP_VISION_PROFILE_CLAUDE_MODEL=anthropic:claude-haiku-4-5
+
+# nested into model_kwargs
+export MYAPP_VISION_PROFILE_CLAUDE_ACCOUNT_B_MODEL_KWARGS__API_KEY=sk-ant-...
+```
+
+This means a profile file can be effectively empty on disk (just declaring the
+profile's existence and maybe an `extends`), with all values supplied by the
+environment. You decide which fields are sensitive and never touch disk.
+
+## Usage
+
+```python
+from pathlib import Path
+from chumak import ProfileLoader, infer
+
+loader = ProfileLoader(
+    search_paths=[Path.home() / ".config/my-app/chumak/profiles"],
+    env_prefix="MYAPP",
+)
+loader.names()                # -> ["claude", "claude-creative", ...]
+profile = loader.load("claude")
+
+from pydantic import BaseModel
+
+class AnneSchema(BaseModel):
+    title: str
+    value: int
+
+result = infer(
+    prompt="Extract title and value from this text: ...",
+    output_schema=AnneSchema,
+    profile=profile,
+)
+result.payload          # -> MissionTitle(title=..., bounty=...)
+result.citations        # -> [Citation, ...] (if the model supplied any)
+result.meta             # -> Meta with cost, generated_at, model identity
+```
+
+### With provenance
+
+```python
+from chumak import Provenance
+
+result = infer(
+    prompt="...",
+    output_schema=AnneSchema,
+    profile=profile,
+    provenance=Provenance(
+        artefact_type="model@v1",
+        artefact_id="artifact-type:2026-05-20T12:34:56Z",
+    ),
+)
+result.meta.artefact_type    # "mission_title@v1"
+result.meta.derived_from     # [...]
+```
+
+## Design notes
+
+- **No domain knowledge**: chumak carries no built-in prompts, no role concepts
+  (tactical/narrator etc. — that's an app concern; just name your profile).
+- **LangChain is a handler, not the spine**: subprocess CLIs are first-class.
+- **Provenance is opt-in**: omit `provenance=` and `meta.artefact_type` is `None`.
+- **The lib never reads env directly** for its own settings. The env overlay
+  for profiles is a deliberate, scoped exception, gated on the prefix the
+  consumer passes in.
+
+## Tooling
+
+uv, Python 3.12+, ruff, ty, pytest. See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the integration test, and quality-check commands.

chumak-0.1.0/README.md

@@ -0,0 +1,140 @@
+# chumak
+
+A thin **inference substrate** for Python projects: user-authored profiles, LangChain
+as a handler, optional provenance/meta on every response.
+
+> *Chumaks* (Чумаки) were wandering Ukrainian salt-traders who traversed the steppe
+> between distant places. They named the Milky Way after themselves —
+> *Чумацький Шлях*, the Chumaks' Way — because they navigated by it.
+
+## What it is
+
+A small library that abstracts away which LLM you're calling and how.
+
+1. Author **profiles** (TOML files) under the app's XDG config dir.
+2. Load a profile via `ProfileLoader` (with inheritance + env-var overrides)
+3. Call `infer(prompt=..., output_schema=..., profile=...)` and get back a validated
+   pydantic payload, normalised citations, and (optionally) a provenance `Meta` stamp.
+
+Two built-in handlers:
+
+- **`langchain`** — uses `langchain.chat_models.init_chat_model(profile.model)` so a
+  single identifier (`anthropic:claude-opus-4-7`, `openai:gpt-5`, …) routes to the
+  right provider. Structured output, citations, and token usage all handled.
+- **`subprocess`** — shells out to a CLI (`claude --print`, `codex exec`, etc.).
+  Useful for prompt iteration via an existing, authorised tool.
+  Schema is injected into the prompt as JSON Schema; stdout is parsed and validated.
+
+## Profiles
+
+Profiles are user-authored. chumak ships at most one generic example
+(`anthropic-claude-opus-4-7` via the LangChain handler). Everything else is yours.
+
+Profiles live in consumer app directory, e.g. `~/.config/<your-app>/chumak/profiles/`.
+chumak does not impose a config dir; the app passes `search_paths` to `ProfileLoader`.
+
+### File shape
+
+```toml
+# ~/.config/galops-vision/chumak/profiles/claude.toml
+handler = "langchain"
+model = "anthropic:claude-opus-4-7"
+temperature = 0.0
+
+[model_kwargs]
+max_tokens = 4096
+```
+
+### Inheritance
+
+```toml
+# claude-account-b.toml
+extends = "claude"
+
+[model_kwargs]
+# api_key sourced from env — see below
+```
+
+### Env-var overlay
+
+Every field on a profile is overridable from the environment. chumak does not
+provision special fields; the convention is uniform:
+
+```
+{APP_PREFIX}_PROFILE_{PROFILE_NAME}_{FIELD_PATH}
+```
+
+with `__` as the nested-field delimiter (single `_` stays inside field names):
+
+```sh
+# top-level field
+export MYAPP_VISION_PROFILE_CLAUDE_MODEL=anthropic:claude-haiku-4-5
+
+# nested into model_kwargs
+export MYAPP_VISION_PROFILE_CLAUDE_ACCOUNT_B_MODEL_KWARGS__API_KEY=sk-ant-...
+```
+
+This means a profile file can be effectively empty on disk (just declaring the
+profile's existence and maybe an `extends`), with all values supplied by the
+environment. You decide which fields are sensitive and never touch disk.
+
+## Usage
+
+```python
+from pathlib import Path
+from chumak import ProfileLoader, infer
+
+loader = ProfileLoader(
+    search_paths=[Path.home() / ".config/my-app/chumak/profiles"],
+    env_prefix="MYAPP",
+)
+loader.names()                # -> ["claude", "claude-creative", ...]
+profile = loader.load("claude")
+
+from pydantic import BaseModel
+
+class AnneSchema(BaseModel):
+    title: str
+    value: int
+
+result = infer(
+    prompt="Extract title and value from this text: ...",
+    output_schema=AnneSchema,
+    profile=profile,
+)
+result.payload          # -> MissionTitle(title=..., bounty=...)
+result.citations        # -> [Citation, ...] (if the model supplied any)
+result.meta             # -> Meta with cost, generated_at, model identity
+```
+
+### With provenance
+
+```python
+from chumak import Provenance
+
+result = infer(
+    prompt="...",
+    output_schema=AnneSchema,
+    profile=profile,
+    provenance=Provenance(
+        artefact_type="model@v1",
+        artefact_id="artifact-type:2026-05-20T12:34:56Z",
+    ),
+)
+result.meta.artefact_type    # "mission_title@v1"
+result.meta.derived_from     # [...]
+```
+
+## Design notes
+
+- **No domain knowledge**: chumak carries no built-in prompts, no role concepts
+  (tactical/narrator etc. — that's an app concern; just name your profile).
+- **LangChain is a handler, not the spine**: subprocess CLIs are first-class.
+- **Provenance is opt-in**: omit `provenance=` and `meta.artefact_type` is `None`.
+- **The lib never reads env directly** for its own settings. The env overlay
+  for profiles is a deliberate, scoped exception, gated on the prefix the
+  consumer passes in.
+
+## Tooling
+
+uv, Python 3.12+, ruff, ty, pytest. See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the integration test, and quality-check commands.

chumak-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "chumak"
+version = "0.1.0"
+description = "Thin inference substrate: user-authored profiles, LangChain as a handler, optional provenance."
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [
+    { name = "Alex Corrie", email = "alex.j.corrie@gmail.com" },
+]
+dependencies = [
+    "pydantic>=2.10",
+    "langchain>=0.3",
+    "langchain-core>=0.3",
+]
+
+[project.optional-dependencies]
+anthropic = ["langchain-anthropic>=0.3"]
+openai = ["langchain-openai>=1.2.2"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-mock>=3.14",
+    "ruff>=0.15.14",
+    "ty>=0.0.21",
+    "langchain-anthropic>=0.3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+dev-mode-dirs = ["src"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chumak"]
+
+[tool.ruff]
+src = ["src"]
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.ty.environment]
+extra-paths = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: requires a live inference backend (use --integration to enable)",
+]

chumak-0.1.0/src/chumak/__init__.py

@@ -0,0 +1,48 @@
+"""chumak — thin inference substrate.
+
+Public surface in `surface.infer`. Profile-loading in `loader.ProfileLoader`.
+Response types in `response`. Handlers are pluggable via `handlers.HANDLER_REGISTRY`.
+
+The library is subject-agnostic and carries no domain knowledge: no
+built-in prompts, no role names, no per-domain artefact types. Consumers
+build those on top.
+"""
+
+from chumak.handlers import HANDLER_REGISTRY, Handler, HandlerType, PromptDelivery
+from chumak.loader import (
+    ProfileCycleError,
+    ProfileLoader,
+    ProfileLoaderError,
+    ProfileNotFoundError,
+)
+from chumak.profile import Profile
+from chumak.response import (
+    ArtefactRef,
+    Citation,
+    Cost,
+    InferResult,
+    Meta,
+    ProducedBy,
+    Provenance,
+)
+from chumak.surface import infer
+
+__all__ = [
+    "HANDLER_REGISTRY",
+    "ArtefactRef",
+    "Citation",
+    "Cost",
+    "Handler",
+    "HandlerType",
+    "InferResult",
+    "Meta",
+    "ProducedBy",
+    "Profile",
+    "ProfileCycleError",
+    "ProfileLoader",
+    "ProfileLoaderError",
+    "ProfileNotFoundError",
+    "PromptDelivery",
+    "Provenance",
+    "infer",
+]

chumak-0.1.0/src/chumak/handlers/__init__.py

@@ -0,0 +1,27 @@
+"""Handlers package.
+
+Owns the `HandlerType` discriminator and the `HANDLER_REGISTRY` mapping each
+`HandlerType` to its concrete handler class. Adding a new handler type means
+dropping a module here, extending `HandlerType` in `types.py`, and adding
+the class to the registry below — no edits in `surface.py` or `profile.py`.
+"""
+
+from chumak.handlers.base import Handler, HandlerResult
+from chumak.handlers.langchain import LangChainHandler
+from chumak.handlers.subprocess import SubprocessHandler
+from chumak.handlers.types import HandlerType, PromptDelivery
+
+HANDLER_REGISTRY: dict[HandlerType, type[Handler]] = {
+    HandlerType.LANGCHAIN: LangChainHandler,
+    HandlerType.SUBPROCESS: SubprocessHandler,
+}
+
+__all__ = [
+    "HANDLER_REGISTRY",
+    "Handler",
+    "HandlerResult",
+    "HandlerType",
+    "LangChainHandler",
+    "PromptDelivery",
+    "SubprocessHandler",
+]