Metadata-Version: 2.5
Name: primarysource
Version: 0.1.0
Summary: Citable primary-source libraries for agents: RFCs, NIST, USB-IF, ITU-T, Kiwix and CVE collections behind one core (ref grammar, token-budgeted paging, full-text index, CLI, MCP server).
Author: Justin Capella
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: citation,documents,full-text-search,mcp,model-context-protocol,standards
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Text Processing :: Indexing
Classifier: Typing :: Typed
Requires-Python: >=3.12
Provides-Extra: bbf
Requires-Dist: pypdf>=5; extra == 'bbf'
Provides-Extra: c2sp
Provides-Extra: cavp
Provides-Extra: cve
Provides-Extra: debpolicy
Provides-Extra: dev
Requires-Dist: mypy>=1.20; extra == 'dev'
Requires-Dist: packaging>=24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Provides-Extra: draft
Provides-Extra: ecma
Requires-Dist: pypdf>=5; extra == 'ecma'
Provides-Extra: gitdocs
Provides-Extra: iana
Provides-Extra: ieee
Requires-Dist: pypdf>=5; extra == 'ieee'
Provides-Extra: iso
Requires-Dist: pypdf>=5; extra == 'iso'
Provides-Extra: itu
Requires-Dist: pypdf>=5; extra == 'itu'
Provides-Extra: kconfig
Provides-Extra: mcp
Requires-Dist: mcp>=2; extra == 'mcp'
Provides-Extra: nist
Provides-Extra: pep
Provides-Extra: pms
Provides-Extra: rfc
Requires-Dist: httpx>=0.27; extra == 'rfc'
Requires-Dist: rich>=13; extra == 'rfc'
Requires-Dist: typer>=0.12; extra == 'rfc'
Provides-Extra: rfc-semantic
Requires-Dist: httpx>=0.27; extra == 'rfc-semantic'
Requires-Dist: model2vec>=0.3; extra == 'rfc-semantic'
Requires-Dist: rich>=13; extra == 'rfc-semantic'
Requires-Dist: sqlite-vec; extra == 'rfc-semantic'
Requires-Dist: typer>=0.12; extra == 'rfc-semantic'
Provides-Extra: rfc-zim
Requires-Dist: httpx>=0.27; extra == 'rfc-zim'
Requires-Dist: libzim>=3.7; extra == 'rfc-zim'
Requires-Dist: rich>=13; extra == 'rfc-zim'
Requires-Dist: typer>=0.12; extra == 'rfc-zim'
Provides-Extra: rpmdocs
Provides-Extra: usb
Provides-Extra: usbids
Provides-Extra: zim
Requires-Dist: libzim>=4.1; (sys_platform != 'win32' or platform_machine != 'ARM64') and extra == 'zim'
Description-Content-Type: text/markdown

# primarysource

A primary source is the text itself: answer from it, and say exactly where it is.

One package, many collections. The core is a sectioned-document model, a ref grammar, token-budgeted paging, a fixed result shape, readers, a full-text index, a CLI and an MCP server. Each collection is a subpackage behind an extra: `rfc` (the RFC series, moved in from rfclib), `nist`, `usb`, `itu`, `zim`, `cve`, and more. `PLAN.md` has the design and `ROADMAP.md` the open work.

```
pip install "primarysource[rfc,mcp]"
primarysource collections
primarysource mcp --collection rfc
```

Pre-alpha. It ships no document text: you fetch the sources yourself.

## What works today

```python
from primarysource.budget import page
from primarysource.model import Document, Section, Unit, span_hash
from primarysource.refs import RefGrammar
from primarysource.render import render

grammar = RefGrammar(r"(?:RFC|BCP|STD)\d+")
ref = grammar.parse("RFC9000§9.6¶2")          # Ref(doc='RFC9000', section='9.6', para=2)

document = Document("demo", "Demo", Unit.SENTENCE, (Section("1", "Scope", ("First.", "Second.")),))
section = document.section("1")
result = page(section.units, start=1, max_tokens=2000)
print(render(" ".join(result.units), {"cite": "Demo §1", "unit": document.unit, "span": span_hash("First.")}))
```

| Module | What it does |
|---|---|
| `primarysource.model` | `Document`, `Section`, the declared `Unit` that `¶n` counts, `span_hash` |
| `primarysource.refs` | `RefGrammar`: `<doc>§<section>[#anchor][¶n]` and `<doc>:<first>-<last>`, for a library's own document-id pattern |
| `primarysource.budget` | `tokens`, `page`: whole units up to a token budget, always making progress, with `next_start` |
| `primarysource.render` | body plus `cite:`, `unit:`, `span:`, `next:`, `relaxed:`, `warning:` footer lines in a fixed order |
| `primarysource.errors` | `LibError(message, hint)`: an error that names its remedy |
| `primarysource.home` | `resolve_home(app)`: `$<APP>_HOME` or the per-user data directory; `atomic_write` |

## What it does not do yet

It reads no file format, builds no index, has no command and serves nothing. No library depends on it.

## Tests

`python -m pytest -q` from this directory. All tests use invented text.
