Metadata-Version: 2.4
Name: lathe-tools
Version: 0.1.0
Summary: The tool that creates the tools: a model-free pipeline that turns real, cited pain into scored project ideas.
Author: Jared
License: MIT
License-File: LICENSE
Keywords: ai-safety,cli,ideation,local-first
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# Lathe

*The tool that creates the tools.*

A lathe is the one machine tool that can machine its own parts. This Lathe is
the same idea turned on software: a small, model-free pipeline that turns
real, cited pain into scored, evidence-backed project ideas -- and the first
thing it was used to score was itself.

## Why it exists

Most "AI idea generators" produce confident prose with no evidence trail.
Lathe inverts that: **no card without citations, no citation without a gated
signal, no signal without a verifiable quote.** If a pain point can't be
traced back to real people saying it out loud, it never enters the system.

## The pipeline

```
SIGNALS --> GENERATE --> SCORE --> SHORTLIST --> SPEC --> BUILD --> SHIP --> MEASURE
   ^                                                                          |
   |--------------------- reception reweights the rubric ---------------------+
```

- **Signals** -- pain points collected from public communities (Reddit
  watchlists, GitHub trending) or seeded by hand. Stored with source URL,
  date, and a verbatim quote.
- **Generate** -- any agent harness (or a human) reads a *generate brief* and
  writes idea cards against a strict schema. Lathe itself never calls a model.
- **Score** -- deterministic weighted rubric (below). The math belongs to the
  tool, never to the model.
- **Shortlist** -- a human picks one. The pipeline enforces a WIP limit of 1
  in BUILD, so ideas can't pile up faster than they ship.
- **Spec / Build / Ship / Measure** -- a card graduates to a one-page brief;
  release reception feeds back and reweights the rubric.

## Model-free by design

Lathe holds no API keys and makes no model calls. The *generate* step is a
document: Lathe emits a brief (schema + rubric + gated signals), and whatever
harness you already trust -- Hermes, Claude Code, Kimi, Codex, or a plain text
editor -- writes the cards. `lathe ingest` validates them fail-closed.

The AI enters through a harness you chose. The tool itself is pure local
files, and it passes its own rubric at maximum score.

## The public rubric

This is the quality bar every card is scored against, 0-5 per criterion.
It is public on purpose: it is the methodology, not a secret.

| Criterion | Weight | The question it asks |
|---|---:|---|
| Standalone | 15% | Runs local-first, no required account, cloud, or key? |
| Safety | 15% | Small permission surface; nothing can leak or phone home? |
| Setup | 12% | Time-to-first-value under 5 minutes, ideally one command? |
| AI authenticity | 12% | Does AI do something rules genuinely can't -- not AI-washing? |
| Audience pull | 15% | Would the target community feel this pain? Evidence-backed? |
| Leanness | 10% | Small codebase, few dependencies, readable end-to-end? |
| Unfair advantage | 8% | Leverages what the builder already knows deeply? |
| Soundness | 8% | Is the design clean, separable, testable, built to last? |
| Maintenance | 5% | Low carrying cost; still works a year from now? |

## Install

From source (today):

```bash
git clone https://github.com/UpsettiSpegetti/lathe
cd lathe
pipx install .
```

From PyPI (once published):

```bash
pipx install lathe-tools  # gavel:skip -- not live until the PyPI publish
```

## Quickstart

```bash
lathe validate      # schema-check every signal and idea card (fail-closed)
lathe score         # rank the cards in cards/scored/ against the rubric
lathe brief         # emit the generate brief for any harness (or human)
lathe ingest        # fail-closed intake: cards/draft -> cards/scored, citations verified
lathe shortlist     # ranked top cards with their evidence trails
lathe promote ID    # advance a card one stage (WIP limit: one card in building)
lathe kill ID       # move a card to killed/ -- kills are data
lathe spec ID       # export the one-page spec brief to specs/
lathe collect       # pull pain signals from public communities (read-only)
```

## Example

`lathe score` on a real idea pool (five cards, one rubric):

```
                    lathe score -- cards/scored
┌───────────┬────────┬──────────┬──────────────┬─────────────────┬────────┐
│ ID        │ Name   │    Total │ Strongest    │ Weakest         │ Stage  │
├───────────┼────────┼──────────┼──────────────┼─────────────────┼────────┤
│ IDEA-0005 │ gavel  │ 4.48 / 5 │ standalone   │ ai_authenticity │ scored │
│ IDEA-0004 │ permit │ 4.45 / 5 │ standalone   │ setup           │ scored │
│ IDEA-0001 │ lathe  │ 4.38 / 5 │ standalone   │ setup           │ scored │
│ IDEA-0002 │ attic  │ 4.33 / 5 │ standalone   │ ai_authenticity │ scored │
│ IDEA-0006 │ tally  │ 3.89 / 5 │ safety       │ ai_authenticity │ scored │
└───────────┴────────┴──────────┴──────────────┴─────────────────┴────────┘
```

Cards are plain Markdown with YAML frontmatter, moved between stage folders
(`draft -> scored -> shortlisted -> specced -> building -> shipped`, plus
`killed/` -- kills are data) only via Lathe commands, so git history is the
audit trail.

## Safety stance

- No network calls in the core tool. Collectors are separate, read-only, and
  treat fetch failure as skip-and-log.
- Signal quotes are verified verbatim against fetched source text.
  Hallucinated evidence cannot enter the system.
- Idea cards generated by a harness **must** cite gated signals; cards without
  citations are rejected at ingest.
- No telemetry, no accounts, no phone-home. Uninstall is deleting the folder.

## License

MIT -- see [LICENSE](LICENSE).
