hunch-jev 0.1.0__tar.gz

hunch_jev-0.1.0/.env.example

@@ -0,0 +1,5 @@
+TYPESAFE_API_KEY=
+TYPESAFE_DEFAULT_MODEL=jev-latest
+CEREBRAS_API_KEY=
+OPENAI_API_KEY=
+OPENROUTER_API_KEY=

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

@@ -0,0 +1,32 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: pytest
+
+  pypi:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

hunch_jev-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.DS_Store
+.hunch/

hunch_jev-0.1.0/LICENSE

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

hunch_jev-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: hunch-jev
+Version: 0.1.0
+Summary: Ask Jev over columns of data: closed-set questions, cached and joined back.
+Project-URL: Homepage, https://github.com/steven-shoemaker/hunch
+Project-URL: Repository, https://github.com/steven-shoemaker/hunch
+Author: Steven Shoemaker
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: pandas>=2.0
+Requires-Dist: typesafe-sdk>=0.5.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hunch
+
+Jev as a column primitive.
+
+[Jev](https://docs.typesafe.ai) is TypeSafe’s System One model: you send state and typed questions, and you get labels, scores, and yes/no probabilities back. **hunch** is a small Python layer on that API. Code owns the table and the side effects. Jev only judges. An optional LLM role may *propose* strings; it never closes.
+
+```python
+import hunch
+from hunch import ask, over, rate
+
+jev = hunch.connect()  # TYPESAFE_API_KEY
+
+@over(prospects, "JOB_TITLE")
+def classify(title):
+    function = ask(
+        title,
+        "what business function does this title state?",
+        among=functions,
+        by=function_rules,
+    )
+    level = ask(
+        title,
+        "what level of rank does this title state?",
+        among=levels,
+        by=seniority_rules,
+    )
+    seniority = level.on(
+        sure=level.top,
+        torn=lambda: ask(
+            title,
+            "which of these two fits better?",
+            among=level.top2,
+            by=seniority_rules,
+        ).top,
+        lost=lambda: (
+            "Individual Contributor"
+            if title.feels("a rank word governing a product, program, or account rather than people")
+            else "review"
+        ),
+    )
+    keep = rate(
+        title,
+        "How important is this account?",
+        ["disposable", "nice to have", "should keep", "must keep"],
+    )
+    return {
+        "function": function.top,
+        "function_shape": function.shape,
+        "seniority": seniority,
+        "seniority_shape": level.shape,
+        "keep": keep.level,
+    }
+
+results = classify.run(jev)
+```
+
+Independent `ask` / `rate` / `feels` calls on the same value go in **one** Jev request. `@over` classifies each distinct value once, caches it, and left-joins onto the frame.
+
+## Install
+
+```sh
+pip install hunch-jev
+# or from a clone:
+pip install -e ".[dev]"
+```
+
+Requires Python 3.10+. Set `TYPESAFE_API_KEY`. Do not put keys in source.
+
+```sh
+pytest
+```
+
+## Verbs
+
+| Call | Jev primitive | You get |
+| --- | --- | --- |
+| `ask(state, question, among=..., by=...)` | Choice | `.top`, `.top2`, `.p`, `.confidence`, `.shape` |
+| `rate(state, question, levels)` | Score | `.score`, `.level`, `.shape` |
+| `value.feels("...")` | Noul | truthy when P(yes) ≥ 0.5 |
+
+`.shape` is **your** policy on the distribution, not a Jev field:
+
+| Shape | Meaning |
+| --- | --- |
+| `sure` | One option dominates |
+| `torn` | Two options are close |
+| `lost` | Flat or weak evidence |
+
+Cutoffs live on `ShapePolicy`. Confidence is how peaked the distribution is, not whether the label is true.
+
+`connect(cache="~/.cache/hunch")` persists answers on disk. `jev.usage` reports calls, cache hits, tokens, and the model name.
+
+## LLM roles
+
+A role may only propose text or a list of labels. `ask` still decides.
+
+```python
+from hunch import ask, draft, openrouter, role
+
+jev = hunch.connect(llm=openrouter())  # OPENROUTER_API_KEY
+taxonomist = role(
+    "Propose 8–16 kebab-case folder names. Include junk. No review pile.",
+    emit=list[str],
+)
+
+with jev.session():
+    taxonomy = draft(listing, taxonomist).labels
+
+folder = ask(name, "which folder?", among=taxonomy)
+```
+
+`hunch.openai`, `hunch.cerebras`, and `hunch.openrouter` are OpenAI-compatible adapters. `via=` on a role overrides `llm=` on `connect()`. A role stops after `max_loops` (default 5) in one session.
+
+## Example
+
+[`examples/organize_downloads.py`](examples/organize_downloads.py) files a Downloads folder: one LLM taxonomy, then Jev assigns each loose file, then the script moves. Destination folders are skipped on later runs. `--dry-run` prints the plan.
+
+## What this is not
+
+Jev does not invent labels. `among=` is the whole set of allowed answers. Roles invent candidates; they have no tools and do not move files. Open-ended writing and multi-step agents are out of scope.
+
+## License
+
+MIT. Jev and TypeSafe are [typesafe.ai](https://typesafe.ai); this library is not affiliated.

hunch_jev-0.1.0/README.md

@@ -0,0 +1,124 @@
+# hunch
+
+Jev as a column primitive.
+
+[Jev](https://docs.typesafe.ai) is TypeSafe’s System One model: you send state and typed questions, and you get labels, scores, and yes/no probabilities back. **hunch** is a small Python layer on that API. Code owns the table and the side effects. Jev only judges. An optional LLM role may *propose* strings; it never closes.
+
+```python
+import hunch
+from hunch import ask, over, rate
+
+jev = hunch.connect()  # TYPESAFE_API_KEY
+
+@over(prospects, "JOB_TITLE")
+def classify(title):
+    function = ask(
+        title,
+        "what business function does this title state?",
+        among=functions,
+        by=function_rules,
+    )
+    level = ask(
+        title,
+        "what level of rank does this title state?",
+        among=levels,
+        by=seniority_rules,
+    )
+    seniority = level.on(
+        sure=level.top,
+        torn=lambda: ask(
+            title,
+            "which of these two fits better?",
+            among=level.top2,
+            by=seniority_rules,
+        ).top,
+        lost=lambda: (
+            "Individual Contributor"
+            if title.feels("a rank word governing a product, program, or account rather than people")
+            else "review"
+        ),
+    )
+    keep = rate(
+        title,
+        "How important is this account?",
+        ["disposable", "nice to have", "should keep", "must keep"],
+    )
+    return {
+        "function": function.top,
+        "function_shape": function.shape,
+        "seniority": seniority,
+        "seniority_shape": level.shape,
+        "keep": keep.level,
+    }
+
+results = classify.run(jev)
+```
+
+Independent `ask` / `rate` / `feels` calls on the same value go in **one** Jev request. `@over` classifies each distinct value once, caches it, and left-joins onto the frame.
+
+## Install
+
+```sh
+pip install hunch-jev
+# or from a clone:
+pip install -e ".[dev]"
+```
+
+Requires Python 3.10+. Set `TYPESAFE_API_KEY`. Do not put keys in source.
+
+```sh
+pytest
+```
+
+## Verbs
+
+| Call | Jev primitive | You get |
+| --- | --- | --- |
+| `ask(state, question, among=..., by=...)` | Choice | `.top`, `.top2`, `.p`, `.confidence`, `.shape` |
+| `rate(state, question, levels)` | Score | `.score`, `.level`, `.shape` |
+| `value.feels("...")` | Noul | truthy when P(yes) ≥ 0.5 |
+
+`.shape` is **your** policy on the distribution, not a Jev field:
+
+| Shape | Meaning |
+| --- | --- |
+| `sure` | One option dominates |
+| `torn` | Two options are close |
+| `lost` | Flat or weak evidence |
+
+Cutoffs live on `ShapePolicy`. Confidence is how peaked the distribution is, not whether the label is true.
+
+`connect(cache="~/.cache/hunch")` persists answers on disk. `jev.usage` reports calls, cache hits, tokens, and the model name.
+
+## LLM roles
+
+A role may only propose text or a list of labels. `ask` still decides.
+
+```python
+from hunch import ask, draft, openrouter, role
+
+jev = hunch.connect(llm=openrouter())  # OPENROUTER_API_KEY
+taxonomist = role(
+    "Propose 8–16 kebab-case folder names. Include junk. No review pile.",
+    emit=list[str],
+)
+
+with jev.session():
+    taxonomy = draft(listing, taxonomist).labels
+
+folder = ask(name, "which folder?", among=taxonomy)
+```
+
+`hunch.openai`, `hunch.cerebras`, and `hunch.openrouter` are OpenAI-compatible adapters. `via=` on a role overrides `llm=` on `connect()`. A role stops after `max_loops` (default 5) in one session.
+
+## Example
+
+[`examples/organize_downloads.py`](examples/organize_downloads.py) files a Downloads folder: one LLM taxonomy, then Jev assigns each loose file, then the script moves. Destination folders are skipped on later runs. `--dry-run` prints the plan.
+
+## What this is not
+
+Jev does not invent labels. `among=` is the whole set of allowed answers. Roles invent candidates; they have no tools and do not move files. Open-ended writing and multi-step agents are out of scope.
+
+## License
+
+MIT. Jev and TypeSafe are [typesafe.ai](https://typesafe.ai); this library is not affiliated.

hunch_jev-0.1.0/examples/organize_downloads.py

@@ -0,0 +1,218 @@
+"""Sort the Downloads folder: an LLM proposes folders, Jev assigns, this script moves."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+import pandas as pd
+
+from hunch import ask, connect, draft, openrouter, over, role
+
+SKIP_NAMES = {".DS_Store", ".localized", "$RECYCLE.BIN"}
+
+
+def load_env(path: Path) -> None:
+    if not path.is_file():
+        return
+    for line in path.read_text().splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        key, value = stripped.split("=", 1)
+        os.environ.setdefault(key.strip(), value.strip())
+
+
+def list_downloads(root: Path) -> pd.DataFrame:
+    rows: list[dict[str, object]] = []
+    for path in root.iterdir():
+        if path.name.startswith(".") or path.name in SKIP_NAMES:
+            continue
+        try:
+            info = path.stat()
+        except OSError:
+            continue
+        rows.append(
+            {
+                "name": path.name,
+                "kind": "dir" if path.is_dir() else "file",
+                "ext": "" if path.is_dir() else path.suffix.lower(),
+                "bytes": info.st_size,
+                "modified": datetime.fromtimestamp(info.st_mtime, tz=timezone.utc).isoformat(),
+                "path": str(path),
+            }
+        )
+    return pd.DataFrame(rows).sort_values("modified", ascending=False).reset_index(drop=True)
+
+
+def unique_dest(folder: Path, name: str) -> Path:
+    dest = folder / name
+    if not dest.exists():
+        return dest
+    stem = Path(name).stem
+    suffix = Path(name).suffix
+    index = 1
+    while True:
+        candidate = folder / f"{stem} ({index}){suffix}"
+        if not candidate.exists():
+            return candidate
+        index += 1
+
+
+def move_item(source: Path, dest: Path) -> Path:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(source), str(dest))
+    return dest
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Sort Downloads into Jev-chosen folders.")
+    parser.add_argument("--root", type=Path, default=Path.home() / "Downloads")
+    parser.add_argument("--limit", type=int, default=0, help="Newest items only. 0 = all.")
+    parser.add_argument("--workers", type=int, default=8)
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--refresh-taxonomy", action="store_true")
+    parser.add_argument(
+        "--cache",
+        type=Path,
+        default=Path.home() / ".cache" / "hunch" / "downloads",
+    )
+    parser.add_argument("--env", type=Path, default=Path(__file__).resolve().parents[1] / ".env")
+    args = parser.parse_args()
+
+    load_env(args.env)
+    items = list_downloads(args.root)
+    if items.empty:
+        raise SystemExit(f"No visible items in {args.root}")
+
+    listing = [
+        f"{row.kind}\t{row.ext}\t{row.name}"
+        for row in items.head(200).itertuples(index=False)
+    ]
+    jev = connect(llm=openrouter(model="z-ai/glm-5.3-flash"), cache=args.cache)
+    taxonomist = role(
+        "Propose 8–16 kebab-case folder names that cover this Downloads pile. "
+        "Group by meaning (work docs, personal paperwork, books, design assets, "
+        "installers, archives, media, project folders), not by file extension alone. "
+        "Include junk for disposable leftovers. Do not include review, other, or misc — "
+        "every item must have a real home. No duplicates.",
+        emit=list[str],
+    )
+
+    print(f"Listed {len(items)} top-level items in {args.root}", flush=True)
+    saved = None if args.refresh_taxonomy else _read_taxonomy(args.cache)
+    if saved:
+        taxonomy = saved
+        print("Using saved taxonomy:", ", ".join(taxonomy), flush=True)
+    else:
+        print("Asking OpenRouter for a taxonomy…", flush=True)
+        with jev.session():
+            taxonomy = draft(listing, taxonomist).labels
+        taxonomy = [label for label in taxonomy if label not in {"review", "other", "misc", "unsorted"}]
+        if "junk" not in taxonomy:
+            taxonomy.append("junk")
+        _write_taxonomy(args.cache, taxonomy)
+        print("Taxonomy:", ", ".join(taxonomy), flush=True)
+
+    dest_names = set(taxonomy)
+    movable = items[~items["name"].isin(dest_names) | (items["kind"] != "dir")].copy()
+    sample = movable if args.limit <= 0 else movable.head(args.limit)
+    if sample.empty:
+        print("Nothing new to file. Destination folders were left alone.")
+        print(f"Jev usage: {jev.usage.calls} calls, {jev.usage.hits} cache hits.")
+        return
+    lookup = {row["name"]: row for row in sample.to_dict(orient="records")}
+    print(f"Classifying {len(sample)} new items with Jev ({args.workers} workers)…", flush=True)
+
+    @over(sample, "name")
+    def classify(name):
+        row = lookup[str(name)]
+        state = {
+            "name": row["name"],
+            "kind": row["kind"],
+            "ext": row["ext"],
+            "bytes": row["bytes"],
+            "modified": row["modified"],
+        }
+        folder = ask(
+            state,
+            "Which folder should this Downloads item go in?",
+            among=taxonomy,
+            by=(
+                "Pick the best fitting folder even if the name is thin. "
+                "Camera-roll stills (IMG_, DSC_, screenshots) go in a photos or screenshots folder. "
+                "App disk images and installers go in installers. "
+                "Named project folders and their zips go in side-projects or dev-projects. "
+                "Use junk only for obvious leftovers or disposable exports. "
+                "Never pick a review, other, or unsorted pile."
+            ),
+        )
+        return {
+            "folder": folder.top,
+            "shape": folder.shape,
+            "confidence": round(folder.confidence, 3),
+            "p": round(folder.p, 3),
+        }
+
+    results = classify.run(
+        jev,
+        max_workers=args.workers,
+        on_item=lambda done, total, _value: print(f"  classified {done}/{total}", flush=True)
+        if done == total or done % 25 == 0
+        else None,
+    )
+
+    moved = 0
+    skipped = 0
+    for row in results.itertuples(index=False):
+        folder = getattr(row, "folder", None)
+        if not isinstance(folder, str) or not folder:
+            skipped += 1
+            continue
+        source = Path(row.path)
+        if not source.exists():
+            skipped += 1
+            continue
+        dest_dir = args.root / folder
+        if source.resolve() == dest_dir.resolve():
+            skipped += 1
+            continue
+        dest = unique_dest(dest_dir, source.name)
+        print(f"{source.name} -> {folder}/{dest.name}", flush=True)
+        if not args.dry_run:
+            move_item(source, dest)
+        moved += 1
+
+    print()
+    print(results.groupby("folder").size().sort_values(ascending=False).to_string())
+    print()
+    action = "Would move" if args.dry_run else "Moved"
+    used = jev.usage
+    print(f"{action} {moved} items. Skipped {skipped}.")
+    print(
+        f"Jev {used.model or 'jev'}: {used.calls} calls, {used.hits} cache hits, "
+        f"{used.input_tokens} in / {used.output_tokens} out tokens."
+    )
+
+
+def _read_taxonomy(cache: Path) -> list[str] | None:
+    path = cache / "taxonomy.json"
+    if not path.is_file():
+        return None
+    labels = json.loads(path.read_text())
+    if not isinstance(labels, list) or not all(isinstance(item, str) for item in labels):
+        return None
+    return labels
+
+
+def _write_taxonomy(cache: Path, labels: list[str]) -> None:
+    cache.mkdir(parents=True, exist_ok=True)
+    (cache / "taxonomy.json").write_text(json.dumps(labels, indent=2) + "\n")
+
+
+if __name__ == "__main__":
+    main()

hunch_jev-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "hunch-jev"
+version = "0.1.0"
+description = "Ask Jev over columns of data: closed-set questions, cached and joined back."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Steven Shoemaker" }]
+dependencies = [
+    "pandas>=2.0",
+    "typesafe-sdk>=0.5.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/steven-shoemaker/hunch"
+Repository = "https://github.com/steven-shoemaker/hunch"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hunch"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "."]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100

hunch_jev-0.1.0/src/hunch/__init__.py

@@ -0,0 +1,41 @@
+"""hunch — Jev as a column primitive, with optional LLM roles that only propose."""
+
+from hunch.answer import Answer, Feeling, Rating
+from hunch.client import Hunch, connect
+from hunch.exceptions import HunchError, NoSessionError
+from hunch.llm import LanguageModel, OpenAICompat, cerebras, openai, openrouter
+from hunch.over import OverJob, over
+from hunch.role import Draft, Role, draft, role
+from hunch.session import ask, rate
+from hunch.shapes import Shape, ShapePolicy
+from hunch.subject import Subject
+from hunch.usage import Usage
+
+__all__ = [
+    "Answer",
+    "Draft",
+    "Feeling",
+    "Hunch",
+    "HunchError",
+    "LanguageModel",
+    "NoSessionError",
+    "OpenAICompat",
+    "OverJob",
+    "Rating",
+    "Role",
+    "Shape",
+    "ShapePolicy",
+    "Subject",
+    "Usage",
+    "ask",
+    "cerebras",
+    "connect",
+    "draft",
+    "openai",
+    "openrouter",
+    "over",
+    "rate",
+    "role",
+]
+
+__version__ = "0.1.0"