Metadata-Version: 2.4
Name: distillr
Version: 0.19.56
Summary: Source-to-intelligence platform: turn YouTube, websites, and arXiv papers into a structured, reusable corpus with per-source insights, cross-source synthesis, and Deep Research reports.
Keywords: research,intelligence,synthesis,arxiv,youtube,rag,knowledge-base,mcp
Author: Nick Seal
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Dist: yt-dlp>=2026.7.4
Requires-Dist: openai>=1.0.0
Requires-Dist: google-genai>=1.50.0
Requires-Dist: typer>=0.9.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: python-docx>=1.0.0
Requires-Dist: playwright>=1.52.0
Requires-Dist: mcp>=2.0.0,<3
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: markdown>=3.5.0
Requires-Dist: nh3>=0.2.0
Requires-Dist: pypdf>=6.15.0
Requires-Dist: requests>=2.32.0
Requires-Dist: idna>=3.7
Requires-Dist: psutil>=6.1
Requires-Dist: httpx>=0.28.0
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: deal>=4.24.6
Requires-Dist: tzdata>=2025.2 ; sys_platform == 'win32'
Requires-Dist: transformers>=4.44,<5 ; extra == 'entailment'
Requires-Dist: torch>=2.3 ; extra == 'entailment'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/blisspixel/distillr
Project-URL: Repository, https://github.com/blisspixel/distillr
Project-URL: Issues, https://github.com/blisspixel/distillr/issues
Provides-Extra: entailment
Description-Content-Type: text/markdown

# Distill

[![CI](https://github.com/blisspixel/distillr/actions/workflows/ci.yml/badge.svg)](https://github.com/blisspixel/distillr/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/distillr.svg)](https://pypi.org/project/distillr/)
[![Python](https://img.shields.io/pypi/pyversions/distillr.svg)](https://pypi.org/project/distillr/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)

> Point Distill at a research goal. It finds papers, talks, and pages from
> operator-trusted sites, captures supplied repos, podcasts, feeds, posts, and
> local files, analyzes each into structured insights with source receipts,
> verifies claims before write, and synthesizes a plain-Markdown corpus on your
> disk. Browse it in Obsidian, query it over MCP, ask cited questions that can
> re-enter the corpus, and refresh on a cadence instead of going stale.

*PyPI package [`distillr`](https://pypi.org/project/distillr/); CLI is `distill`
(plus `distill-mcp`).*

## Install and first run

```bash
uv tool install distillr
distill --cost-mode no-metered init
distill --cost-mode no-metered papers "temporal knowledge graph" --topic tkg --limit 5 --preview
```

`no-metered` only allows routes Distill can prove are not API-billed. Preview
builds a current arXiv shortlist without ingesting. When the shortlist looks
right:

Hard dollar budgets cover registered token-priced calls. Gemini Deep Research
has no provider request-side dollar ceiling, so Distill refuses that agent
before remote setup whenever a hard workflow or MCP budget is active.

```bash
distill --cost-mode paid-ok papers "temporal knowledge graph" --topic tkg --limit 20
```

Paper analysis stays one-at-a-time by default. After reviewing the projected
total, pass `--workers 2` or `--workers 3` to analyze independent papers in a
small bounded group. Discovery, artifact writes, verification, synthesis, and
report sections remain serialized.

![distill papers CLI demo with synthetic paper titles, progress lines, cost summary, and Markdown corpus artifacts](docs/assets/cli-papers-demo.png)

*Illustrative demo (synthetic titles and paths). Real runs use current arXiv
results and your configured model route. Distill estimates the selected route
before spend; actual cost and duration depend on source size and model output.*

Alternate installers, keys, local models, and updates:
[`docs/install.md`](docs/install.md). Full command reference:
[`docs/usage.md`](docs/usage.md).

## What you get

One local `library/` of plain Markdown: no database, no cloud lock-in. Same
pipeline shape for every source (capture → analyze → verify → synthesize), with
a write-time verify gate.

| Source | Entry point |
|---|---|
| YouTube | `distill latest`, `distill video`, `distill discover` |
| Websites | `distill site`, `distill site-batch` |
| arXiv | `distill papers` |
| X, repos, podcasts, newsletters, local files | `distill ingest <url-or-path>` |

Plus `distill ask` (cited answers from the corpus), `distill audit` (free trust
report), and `distill report` (a corpus-first sequential report by default,
with explicit accordion and Deep Research profiles). MCP and recurring
profiles expose the same durable corpus to agents. Artifact layout and samples:
[`docs/outputs.md`](docs/outputs.md). Real example corpus:
[`examples/`](examples/README.md).

Agent distribution uses one canonical Agent Skill plus an
[Agent Plugins 1.0.0](https://agent-plugins.org/specification) portable package
and separate client compatibility surfaces. The specification is currently a
Working Draft. `distill export <topic> --format okf` produces an
[OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
projection with portable provenance, bounded receipt copies, lifecycle fields,
and digest-bound machine-verification events. The native `library/` remains the
source of truth. Exact standards boundaries and update policy:
[`docs/interoperability.md`](docs/interoperability.md).

How Distill differs from Deep Research tools, notebooks, and Markdown wikis:
[`docs/positioning.md`](docs/positioning.md).

## Docs

| Doc | For |
|---|---|
| [`docs/README.md`](docs/README.md) | Full documentation index |
| [`docs/usage.md`](docs/usage.md) | Commands, flags, first recipes |
| [`docs/install.md`](docs/install.md) | Install, providers, local models |
| [`docs/cost.md`](docs/cost.md) | Cost model and guardrails |
| [`docs/mcp.md`](docs/mcp.md) | MCP tools and agent paths |
| [`docs/outputs.md`](docs/outputs.md) | What every artifact contains |
| [`docs/architecture.md`](docs/architecture.md) | Data flow and routing |
| [`docs/invariants.md`](docs/invariants.md) | Design charter |
| [`docs/interoperability.md`](docs/interoperability.md) | Agent Plugins and OKF baselines |
| [`docs/SECURITY.md`](docs/SECURITY.md) | Trust boundaries and disclosure |
| [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) | Dev setup and quality gates |
| [`docs/CHANGELOG.md`](docs/CHANGELOG.md) | What shipped |
| [`ROADMAP.md`](ROADMAP.md) | What is next |

## Status

Active beta with a broad working surface (sources, discovery, verify, synthesis,
ask, audit, MCP, dashboard, profiles, deferred workers). Every change still
clears the same release gate (95% branch coverage, ruff, pyright, import-linter,
bandit, pip-audit, supported Python matrix, build provenance). Covered v1
contract snapshots are freeze-ready under the published compatibility policy;
uncovered pre-1.0 surfaces can still improve additively. Pin versions if you
integrate on MCP schemas or frontmatter. 1.0 is a future stability commitment,
not a calendar date:
[`ROADMAP.md`](ROADMAP.md#100---stability-commitment--quality-bar).

## License

Apache 2.0. See [`LICENSE`](LICENSE).
