Metadata-Version: 2.4
Name: pprose
Version: 0.2.0
Summary: Practical Prose tooling: metrics, rubric scoring, evaluation reports, comparisons, and agent skills
Project-URL: Repository, https://github.com/jlevy/practical-prose
Author-email: Joshua Levy <joshuadlevy@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.11
Requires-Dist: aiolimiter>=1.2
Requires-Dist: flexdoc==0.3.0
Requires-Dist: flowmark>=0.7.1
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic-ai-slim[anthropic,google,openai]==1.93.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# pprose

Practical Prose tooling: deterministic metrics, rubric scoring, evaluation reports, and
comparisons for practical documents.

`pprose` is the command-line companion to
[Practical Prose](https://github.com/jlevy/practical-prose), a reference system and
evaluation toolkit for writing that helps a reader understand, decide, do, verify, or
maintain something.

## Install

The distribution and command are both `pprose`. After publication, run with no install
using [uv](https://docs.astral.sh/uv/):

```bash
uvx pprose <command> ...
```

Or install it:

```bash
uv tool install pprose
```

## Commands

```bash
pprose metrics doc.md                              # deterministic metrics for a document
pprose report from-metrics doc.md --out doc.eval.md  # build an eval report stub
pprose score doc.eval.md --model opus              # LLM rubric scoring (Anthropic, OpenAI, or Google)
pprose compare a.eval.md b.eval.md                 # compare N eval reports
pprose render doc.eval.md                          # render an eval report as static HTML

pprose about                                       # the project narrative (bundled README)
pprose skill                                       # workflow skills overview + routing pointers
pprose list                                        # every bundled guideline, shortcut, runbook, skill
pprose guidelines <name>                           # print one style guide (no name lists them)
pprose install                                     # install skills into the current project
pprose install --global                            # install skills user-wide for every project
```

`pprose install` runs in one of two **scopes**:

- **Project** (`--project`, the default when cwd is inside a git repo) writes into
  `<repo>/.agents/skills/` (Codex, Gemini CLI, pi), `<repo>/.claude/skills/` (Claude
  Code), and a marker-bounded block in `<repo>/AGENTS.md`.
- **User-global** (`--global`) writes into `~/.agents/skills/pprose-*/` and
  `~/.claude/skills/pprose-*/`, making the skills available across every project.
  Skips `~/.codex/AGENTS.md` so the global instruction file stays user-authored.

Outside an unambiguous project context (`$HOME`, a non-git directory), `--project` or
`--global` must be passed explicitly; there is no silent default.
`$HOME` is always refused under `--project`; use `--global` for a user-wide install.
Pass `--surfaces=portable,claude,agents-md` (or `--surfaces=all`, the default) to select
install destinations within the chosen scope, or `--pin <version>` to override the
version baked into the bootstrap line.

Every generated artifact carries a `format=fNN` stamp; re-running install is idempotent,
and a newer-format artifact is never clobbered by an older pprose.
Each generated skill bakes in a pinned, local-first invocation (`pprose` if on PATH,
else `uvx pprose@<version>`). Cross-scope coexistence is the supported pattern:
project-scope skills shadow user-scope skills of the same name in modern agents.
Run `pprose --help` or `pprose install --help` for full options.

**Upgrading:** new releases can add guidelines, shortcuts, runbooks, and skills.
Because installed skills pin the version that installed them, a repo picks up additions
only after you upgrade pprose and re-run install (`uvx pprose@latest install`, or
`uv tool install --upgrade pprose && pprose install`); re-running refreshes both the
artifacts and the baked version pin.

`score` requires the API key for the chosen provider (`ANTHROPIC_API_KEY`,
`OPENAI_API_KEY`, or `GOOGLE_API_KEY`); the package auto-loads `.env` and `.env.local`
from the current directory hierarchy and `$HOME`.

## Project Docs

- Installing uv and Python: [installation.md](docs/installation.md)
- Development workflows: [development.md](docs/development.md)
- Publishing to PyPI: [publishing.md](docs/publishing.md)

## License

The package code is MIT licensed (the `license` field in package metadata).
The wheel also bundles practical-prose **content** (the guidelines, rubric, runbooks,
and other prose under `resources/`), which is licensed under Creative Commons
Attribution 4.0 ([CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)). See the
[repository LICENSE](https://github.com/jlevy/practical-prose/blob/main/LICENSE).

<!-- This document follows common-doc-guidelines.md.
See github.com/jlevy/practical-prose and review guidelines before editing.
-->
