askfaro-progressive-context 0.1.0__tar.gz

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

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+# Publishes to PyPI via OIDC trusted publishing (no API token stored).
+# Configure the trusted publisher on PyPI once (Project → Settings → Publishing):
+#   owner: poolside-ventures   repo: askfaro-progressive-context
+#   workflow: publish.yml      environment: pypi
+# Then publishing happens automatically when a GitHub Release is published.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv venv --python 3.12
+      - run: uv pip install -e ".[dev,schema,llm]"
+      - run: uv run pytest -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC token for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

askfaro_progressive_context-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+.DS_Store

askfaro_progressive_context-0.1.0/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+## Unreleased
+
+- **Docs: document `NavSession`.** Added a README section for the agent-loop API
+  (`index` / `look` / `open` / `close`, the `local` / `remote` modes, and the
+  `shown_tokens` / `budget_remaining` accounting). No functional change.
+
+## 0.1.0 - renamed to askfaro-progressive-context (2026-06-17)
+
+- **Package renamed.** Distribution `faro-progressive-context` is now
+  `askfaro-progressive-context`, and the import name `faro_progressive_context`
+  is now `askfaro_progressive_context`, to match the AskFaro brand. Update
+  imports and `pip install askfaro-progressive-context`. The old name ships one
+  final `0.0.8` release that re-exports this package and warns on import. No
+  functional change.
+
+## 0.0.7 — first clean public release (2026-06-11)
+
+- Genericized examples and docs for the public release (neutral fixtures; no
+  product-specific references). No functional change vs 0.0.6. 0.0.6 is yanked.
+
+## 0.0.6 — incremental rebuilds (2026-06-11)
+
+- **Reuse descriptors for unchanged content.** `compile_source(prior_manifest=...)`
+  builds a `content_hash`-keyed cache (`cache_from_manifest`) and reuses the
+  prior descriptor for any node whose content is unchanged. Because a node's
+  hash rolls up its whole subtree, a change re-describes only that node and its
+  ancestor path; only sibling groups whose parent changed are re-contrasted, and
+  only regenerated nodes are re-graded. Stats: `reused` / `regenerated`.
+- Net effect: an unchanged full-catalog rebuild (213 tools) makes **0 model
+  calls**; a one-tool change makes a handful — so the LLM-quality manifest is
+  cheap to keep fresh on every catalog change (seed once, refresh incrementally).
+
+## 0.0.5 — self-describing manifests + concurrent builds (unreleased)
+
+- **Self-description (`usage`).** Every manifest now ships a top-level `usage`
+  block — a plain-language explanation of the navigation protocol — so a cold
+  external agent that has never seen the format knows how to navigate it
+  (descriptors vs content, `node://` refs, the budget, index/open/look). The
+  llms.txt export gets a matching "How to read this index" header.
+- **Concurrent descriptor generation.** `generate_descriptors`/`compile_source`
+  take `max_workers`; the three phases parallelize (level-by-level so a branch's
+  children are always ready). Brings a ~280-node catalog build from ~35 min to
+  ~8 min. Deterministic-equivalent to sequential.
+- **More robust LLM parsing.** Extract the first balanced JSON object (handles
+  trailing "Extra data"); `describe_leaf/branch` degrade to a hint-based
+  descriptor on parse failure instead of crashing a large build.
+
+## 0.0.4 — navigation policy (NavSession + modes) (unreleased)
+
+- **`NavSession`** — the agent-facing navigation policy with three verbs:
+  `index()` (frontier, shortest-useful view), `look(ids)` (escalate candidates
+  to the full descriptor without committing), `open(id)` (drill a branch /
+  splice a leaf). The model's choice of verb is the confidence signal.
+- **Explicit `local`/`remote` modes** encoding the tokens-vs-round-trips
+  tradeoff: `local` opens at a `brief` index and escalates (round-trips ~free);
+  `remote` discloses a `full` index and inlines small leaves to cut round-trips.
+- Runtime is now **view-level aware** in its budget accounting (`view_level`),
+  with `disclose_more()` charging only the escalation delta. `shown_tokens`
+  on the session is the real length the model saw.
+
+## 0.0.3 — length, escalation, locality, error guidance (unreleased)
+
+- **Length is now a first-class metric.** The eval reports `first_view_tokens`,
+  `tokens_to_answer`, and a `disclosure_ratio` vs loading everything — alongside
+  accuracy. (bake-off (24-tool catalog): pcx reaches the answer at ~2.2k tokens vs
+  ~15k to load all schemas, 6.9× less, while being more accurate *and* shorter.)
+- **Shortest-first-view + escalation.** `Runtime.frontier_view(level)` /
+  `frontier_tokens(level)` render the frontier at `title` → `brief` → `full`.
+  A `title`-first view is ~14× smaller than `full` on a 24-tool catalog; the agent
+  escalates only when it can't decide.
+- **Latency/locality.** `Runtime(resolver=...)` resolves leaves from a local
+  in-memory store so `expand` is an O(1) splice, not a network fetch; missing
+  leaves error loudly. `dict_resolver` for the common case.
+- **Error guidance.** Actionable messages for the common setup mistakes
+  (missing `[llm]` extra, no endpoint/model, empty API key, unknown adapter
+  kind, missing source, reserve ≥ budget) + `docs/troubleshooting.md`.
+
+## 0.0.2 — Phase 1 (unreleased)
+
+The compiler: `pcx build` turns content into manifest variants.
+
+- **Adapters** for the four already-hierarchical source kinds — `tools` (JSON
+  schemas, grouped by namespace), `docs` (markdown tree), `skills` (per-skill
+  markdown, grouped by category), `memory` (one-fact files, grouped by type).
+  No clustering/structure-inference yet (that's Phase 3).
+- **Descriptor engine** (the moat): bottom-up generation, a contrastive sibling
+  pass that rewrites each `when` to discriminate from its siblings, and a
+  self-grade + repair loop. `DescriptorModel` is pluggable — `FakeDescriptorModel`
+  for offline/CI, `LLMDescriptorModel` for a real (Flash-class) model via any
+  OpenAI-compatible endpoint.
+- **Cost annotation**: per-node `tokens`/`desc_tokens`, bottom-up
+  `subtree_tokens` rollup, and `content_hash` for incremental rebuilds.
+- **Emit**: one manifest per `--budgets` variant + an `llms.txt` export.
+- **CLI**: `pcx build <path> --kind ... --budgets ... [--fake | --endpoint --model]`.
+
+### Not yet
+- Per-budget frontier-depth/verbosity shaping (variants currently share the tree).
+- `website`/`file` adapters + embedding-based grouping (Phase 3).
+- The host-side wiring + the real bake-off vs flat manifests (consumer task).
+
+## 0.0.1 — Phase 0 (unreleased)
+
+Spec freeze + eval harness, ahead of the compiler.
+
+- **Format**: `pcx` v0.1 progressive-context manifest, defined as JSON Schema
+  (`schema/pcx-0.1.schema.json`). Tiered nodes with `what`/`when` descriptors,
+  per-node and subtree token costs, branch/leaf split, verbatim leaf pointers,
+  and pre-generated per-budget variants.
+- **Validation**: zero-dependency structural checks + optional full JSON Schema
+  validation (`pcx validate`).
+- **Expansion runtime**: `peek` / `expand` / `collapse` / `search` with hard
+  budget enforcement, a runtime `reserve` for host headroom, optional LRU
+  auto-eviction, and a pluggable search backend.
+- **Navigators**: `KeywordNavigator` (deterministic, offline baseline) and
+  `LLMNavigator` (bring-your-own model).
+- **Eval harness**: `navigation-success @ budget`, first-hop precision, and
+  average hops (`pcx eval`), with a `skills` example fixture.
+
+### Not yet
+- `pcx build` — the compiler (adapters, descriptor generation, cost annotation).
+  Lands in Phase 1.

askfaro_progressive_context-0.1.0/LICENSE

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

askfaro_progressive_context-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: askfaro-progressive-context
+Version: 0.1.0
+Summary: Compile any content into a tiered, budget-aware, agent-navigable progressive-disclosure manifest, plus an on-demand expansion protocol — for small/on-device context windows
+Project-URL: Homepage, https://github.com/poolside-ventures/askfaro-progressive-context
+Project-URL: Repository, https://github.com/poolside-ventures/askfaro-progressive-context
+Project-URL: Issues, https://github.com/poolside-ventures/askfaro-progressive-context/issues
+Project-URL: Changelog, https://github.com/poolside-ventures/askfaro-progressive-context/blob/main/CHANGELOG.md
+Author: Faro
+License: MIT
+License-File: LICENSE
+Keywords: agent,context,context-window,llm,llms-txt,on-device,progressive-disclosure,tokens
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: httpx>=0.27; extra == 'llm'
+Provides-Extra: schema
+Requires-Dist: jsonschema>=4.21; extra == 'schema'
+Provides-Extra: tokenize
+Requires-Dist: tiktoken>=0.7; extra == 'tokenize'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# askfaro-progressive-context
+
+**Compile any content into a tiered, budget-aware, agent-navigable progressive-disclosure manifest — for small / on-device context windows.**
+
+On-device models have tiny context windows (~4k today, ~32k near-term). Stuffing everything in — or lossily compressing it — loses information. The alternative is **progressive disclosure**: give the model a compact, accurate *index* of what exists and *when each piece is relevant*, then let it fetch detail on demand within a hard token budget.
+
+`askfaro-progressive-context` is the open-source compiler + format + runtime for that index. It is the **agent-navigated** half of Faro's context tooling (the model reads the index and decides what to expand); its sibling [`askfaro-embedded-search`](https://github.com/poolside-ventures/askfaro-embedded-search) is the retrieval-driven half. The two stay independent — this library has no hard dependency on it.
+
+> Status: **Phase 1 (pre-alpha).** The format, expansion runtime, eval harness, **and the compiler (`pcx build`)** are here and tested — adapters for `tools`/`docs`/`skills`/`memory`, the descriptor engine (bottom-up + contrastive + self-grade), cost annotation, and per-budget emit. Still to come: per-budget frontier shaping, `website`/`file` adapters with clustering (Phase 3), and the hosted Faro registry (Phase 5).
+
+## The idea in one screen
+
+A **progressive-context manifest** (`pcx.json`) is a tree of nodes. Every node carries:
+
+- a **descriptor** — `what` (one line: what this is) and `when` (one line: when it's relevant). These are the *navigation index*, and their quality is the whole game.
+- **token costs** — so the runtime can plan expansion against a budget *without fetching anything*.
+- either **children** (a branch) or a **payload pointer** (a leaf). Leaves are never inlined and always **verbatim** — no information is lost to a summary.
+
+Variants are **pre-generated per budget** (`pcx.4k.json`, `pcx.32k.json`, …); budgets are arbitrary integers, so a developer who needs headroom for their own content can build a `31k` variant — or reserve it at runtime.
+
+## What's here (Phase 0)
+
+| Module | What it does |
+|---|---|
+| `schema/pcx-0.1.schema.json` | the format, as JSON Schema |
+| `askfaro_progressive_context.types` | `Manifest` / `Node` / `Payload` dataclasses |
+| `askfaro_progressive_context.validate` | structural (zero-dep) + JSON Schema validation |
+| `askfaro_progressive_context.runtime` | the expansion protocol: `peek` / `expand` / `collapse` / `search`, with **hard budget enforcement** and a runtime `reserve` |
+| `askfaro_progressive_context.navigator` | `KeywordNavigator` (deterministic baseline, no model) and `LLMNavigator` (bring your own `complete()`) |
+| `askfaro_progressive_context.eval` | the **`navigation-success @ budget`** harness — the headline quality metric |
+
+## Quick start
+
+```bash
+pip install -e ".[dev,schema]"
+
+# validate a manifest
+pcx validate examples/skills/manifest.pcx.4k.json --schema
+
+# score navigation-success @ budget with the deterministic baseline navigator
+pcx eval examples/skills/manifest.pcx.4k.json examples/skills/cases.json -v
+```
+
+```python
+from askfaro_progressive_context import Manifest, Runtime
+
+m = Manifest.from_dict(json.load(open("examples/skills/manifest.pcx.4k.json")))
+rt = Runtime(m, reserve=1024)          # leave 1k for your own content
+
+rt.peek()                               # frontier: tier-1 descriptors + budget_remaining
+rt.expand("recurring")                  # reveal a branch's children (charged against budget)
+ref = rt.expand("recurring.create")     # splice a leaf's verbatim payload; raises if over budget
+```
+
+## The expansion protocol
+
+The runtime — not the model — is the budget authority. `effective_budget = variant.budget − reserve`, and every `expand` is checked against it. When full it auto-collapses LRU leaves (opt-in) or refuses and tells the agent to choose. **The budget is never silently exceeded.**
+
+## Driving it from an agent loop: `NavSession`
+
+`Runtime` is the low-level budget authority; `NavSession` wraps it with the three verbs an agent loop actually drives, plus mode-aware defaults. The model's *choice of verb is the confidence signal* — there is no threshold to tune:
+
+```python
+from askfaro_progressive_context import Manifest, NavSession
+
+s = NavSession(manifest, mode="local", reserve=1024)
+
+s.index()                        # current frontier, shortest-useful view first
+s.look(["recurring", "one_off"]) # escalate candidates to full descriptors WITHOUT opening them
+s.open("recurring")              # branch -> drill into its children;
+                                 # leaf   -> splice the verbatim content (budget-enforced)
+s.close("recurring")             # collapse a node to reclaim budget
+
+s.shown_tokens                   # everything the model has seen this session (the real "length")
+s.budget_remaining
+```
+
+If the index is enough, the model calls `open`; if it can't decide, it calls `look` first. **Modes** encode the tokens-vs-round-trips tradeoff:
+
+| mode | frontier view | small leaves | use when |
+|---|---|---|---|
+| `local` (default) | `brief` | resolved on demand (O(1) resident splice) | on-device / resident manifest — round-trips are ~free, so take many tiny steps |
+| `remote` | `full` | inlined into `index()` (≤200 tokens) | network-backed — each hop costs latency, so disclose more per step to need fewer |
+
+Pass `config=ModeConfig(...)` for a custom policy; an unknown `mode` raises with the valid options.
+
+## Why a benchmark, not vibes
+
+The moat is descriptor quality, so quality is measured, not asserted. The eval harness gives a navigator *only* the manifest and a budget plus `(query → correct leaf)` cases, and reports **navigation-success @ budget**, **first-hop precision**, and **average hops**. The deterministic `KeywordNavigator` establishes an offline floor; swap in an `LLMNavigator` to score a real model.
+
+## Length is the point
+
+Accuracy without length misses why this exists. The eval reports
+`first_view_tokens` and `tokens_to_answer` next to accuracy, and the runtime
+renders the frontier at progressively shorter levels (`title` → `brief` →
+`full`) so the agent opens with the **shortest** view and escalates only when
+unsure. On a 24-tool catalog, a `title`-first view is ~14× smaller than the full
+descriptor set, and the model reaches the right tool having seen ~6.9× less
+context than loading every schema.
+
+Progressive disclosure trades tokens for round-trips, so the whole artifact is
+meant to stay **resident**: `Runtime(resolver=...)` resolves leaves from a local
+store, making every `expand` an O(1) splice rather than a network fetch.
+
+## Troubleshooting
+
+Setup mistakes fail with actionable messages; see [`docs/troubleshooting.md`](docs/troubleshooting.md)
+for the full table (missing extras, model config, architecture mismatches).
+
+## License
+
+MIT © Faro

askfaro_progressive_context-0.1.0/README.md

@@ -0,0 +1,112 @@
+# askfaro-progressive-context
+
+**Compile any content into a tiered, budget-aware, agent-navigable progressive-disclosure manifest — for small / on-device context windows.**
+
+On-device models have tiny context windows (~4k today, ~32k near-term). Stuffing everything in — or lossily compressing it — loses information. The alternative is **progressive disclosure**: give the model a compact, accurate *index* of what exists and *when each piece is relevant*, then let it fetch detail on demand within a hard token budget.
+
+`askfaro-progressive-context` is the open-source compiler + format + runtime for that index. It is the **agent-navigated** half of Faro's context tooling (the model reads the index and decides what to expand); its sibling [`askfaro-embedded-search`](https://github.com/poolside-ventures/askfaro-embedded-search) is the retrieval-driven half. The two stay independent — this library has no hard dependency on it.
+
+> Status: **Phase 1 (pre-alpha).** The format, expansion runtime, eval harness, **and the compiler (`pcx build`)** are here and tested — adapters for `tools`/`docs`/`skills`/`memory`, the descriptor engine (bottom-up + contrastive + self-grade), cost annotation, and per-budget emit. Still to come: per-budget frontier shaping, `website`/`file` adapters with clustering (Phase 3), and the hosted Faro registry (Phase 5).
+
+## The idea in one screen
+
+A **progressive-context manifest** (`pcx.json`) is a tree of nodes. Every node carries:
+
+- a **descriptor** — `what` (one line: what this is) and `when` (one line: when it's relevant). These are the *navigation index*, and their quality is the whole game.
+- **token costs** — so the runtime can plan expansion against a budget *without fetching anything*.
+- either **children** (a branch) or a **payload pointer** (a leaf). Leaves are never inlined and always **verbatim** — no information is lost to a summary.
+
+Variants are **pre-generated per budget** (`pcx.4k.json`, `pcx.32k.json`, …); budgets are arbitrary integers, so a developer who needs headroom for their own content can build a `31k` variant — or reserve it at runtime.
+
+## What's here (Phase 0)
+
+| Module | What it does |
+|---|---|
+| `schema/pcx-0.1.schema.json` | the format, as JSON Schema |
+| `askfaro_progressive_context.types` | `Manifest` / `Node` / `Payload` dataclasses |
+| `askfaro_progressive_context.validate` | structural (zero-dep) + JSON Schema validation |
+| `askfaro_progressive_context.runtime` | the expansion protocol: `peek` / `expand` / `collapse` / `search`, with **hard budget enforcement** and a runtime `reserve` |
+| `askfaro_progressive_context.navigator` | `KeywordNavigator` (deterministic baseline, no model) and `LLMNavigator` (bring your own `complete()`) |
+| `askfaro_progressive_context.eval` | the **`navigation-success @ budget`** harness — the headline quality metric |
+
+## Quick start
+
+```bash
+pip install -e ".[dev,schema]"
+
+# validate a manifest
+pcx validate examples/skills/manifest.pcx.4k.json --schema
+
+# score navigation-success @ budget with the deterministic baseline navigator
+pcx eval examples/skills/manifest.pcx.4k.json examples/skills/cases.json -v
+```
+
+```python
+from askfaro_progressive_context import Manifest, Runtime
+
+m = Manifest.from_dict(json.load(open("examples/skills/manifest.pcx.4k.json")))
+rt = Runtime(m, reserve=1024)          # leave 1k for your own content
+
+rt.peek()                               # frontier: tier-1 descriptors + budget_remaining
+rt.expand("recurring")                  # reveal a branch's children (charged against budget)
+ref = rt.expand("recurring.create")     # splice a leaf's verbatim payload; raises if over budget
+```
+
+## The expansion protocol
+
+The runtime — not the model — is the budget authority. `effective_budget = variant.budget − reserve`, and every `expand` is checked against it. When full it auto-collapses LRU leaves (opt-in) or refuses and tells the agent to choose. **The budget is never silently exceeded.**
+
+## Driving it from an agent loop: `NavSession`
+
+`Runtime` is the low-level budget authority; `NavSession` wraps it with the three verbs an agent loop actually drives, plus mode-aware defaults. The model's *choice of verb is the confidence signal* — there is no threshold to tune:
+
+```python
+from askfaro_progressive_context import Manifest, NavSession
+
+s = NavSession(manifest, mode="local", reserve=1024)
+
+s.index()                        # current frontier, shortest-useful view first
+s.look(["recurring", "one_off"]) # escalate candidates to full descriptors WITHOUT opening them
+s.open("recurring")              # branch -> drill into its children;
+                                 # leaf   -> splice the verbatim content (budget-enforced)
+s.close("recurring")             # collapse a node to reclaim budget
+
+s.shown_tokens                   # everything the model has seen this session (the real "length")
+s.budget_remaining
+```
+
+If the index is enough, the model calls `open`; if it can't decide, it calls `look` first. **Modes** encode the tokens-vs-round-trips tradeoff:
+
+| mode | frontier view | small leaves | use when |
+|---|---|---|---|
+| `local` (default) | `brief` | resolved on demand (O(1) resident splice) | on-device / resident manifest — round-trips are ~free, so take many tiny steps |
+| `remote` | `full` | inlined into `index()` (≤200 tokens) | network-backed — each hop costs latency, so disclose more per step to need fewer |
+
+Pass `config=ModeConfig(...)` for a custom policy; an unknown `mode` raises with the valid options.
+
+## Why a benchmark, not vibes
+
+The moat is descriptor quality, so quality is measured, not asserted. The eval harness gives a navigator *only* the manifest and a budget plus `(query → correct leaf)` cases, and reports **navigation-success @ budget**, **first-hop precision**, and **average hops**. The deterministic `KeywordNavigator` establishes an offline floor; swap in an `LLMNavigator` to score a real model.
+
+## Length is the point
+
+Accuracy without length misses why this exists. The eval reports
+`first_view_tokens` and `tokens_to_answer` next to accuracy, and the runtime
+renders the frontier at progressively shorter levels (`title` → `brief` →
+`full`) so the agent opens with the **shortest** view and escalates only when
+unsure. On a 24-tool catalog, a `title`-first view is ~14× smaller than the full
+descriptor set, and the model reaches the right tool having seen ~6.9× less
+context than loading every schema.
+
+Progressive disclosure trades tokens for round-trips, so the whole artifact is
+meant to stay **resident**: `Runtime(resolver=...)` resolves leaves from a local
+store, making every `expand` an O(1) splice rather than a network fetch.
+
+## Troubleshooting
+
+Setup mistakes fail with actionable messages; see [`docs/troubleshooting.md`](docs/troubleshooting.md)
+for the full table (missing extras, model config, architecture mismatches).
+
+## License
+
+MIT © Faro

askfaro_progressive_context-0.1.0/askfaro_progressive_context/__init__.py

@@ -0,0 +1,57 @@
+"""askfaro-progressive-context: compile any content into a tiered, budget-aware,
+agent-navigable progressive-disclosure manifest, plus an expansion protocol."""
+
+from .eval import CaseResult, EvalReport, NavCase, run_case, run_eval
+from .llm import LLMClient, OpenAICompatibleClient
+from .navigator import KeywordNavigator, LLMNavigator, Navigator
+from .runtime import (
+    VIEW_LEVELS,
+    BudgetExceeded,
+    FrontierEntry,
+    LeafResolver,
+    Runtime,
+    SearchBackend,
+    dict_resolver,
+    render_descriptor,
+)
+from .session import LOCAL, REMOTE, ModeConfig, NavSession
+from .tokenizer import make_tokenizer
+from .types import PROTOCOL_USAGE, Manifest, Node, Payload, Variant, estimate_tokens
+from .validate import schema_errors, structural_errors, validate
+
+__version__ = "0.0.7"
+
+__all__ = [
+    "BudgetExceeded",
+    "CaseResult",
+    "EvalReport",
+    "FrontierEntry",
+    "KeywordNavigator",
+    "LLMClient",
+    "LLMNavigator",
+    "LOCAL",
+    "REMOTE",
+    "LeafResolver",
+    "Manifest",
+    "ModeConfig",
+    "NavCase",
+    "NavSession",
+    "Navigator",
+    "Node",
+    "OpenAICompatibleClient",
+    "PROTOCOL_USAGE",
+    "Payload",
+    "Runtime",
+    "SearchBackend",
+    "VIEW_LEVELS",
+    "Variant",
+    "dict_resolver",
+    "estimate_tokens",
+    "make_tokenizer",
+    "render_descriptor",
+    "run_case",
+    "run_eval",
+    "schema_errors",
+    "structural_errors",
+    "validate",
+]

askfaro_progressive_context-0.1.0/askfaro_progressive_context/build/__init__.py

@@ -0,0 +1,33 @@
+"""The compiler: source content -> annotated tree -> pcx manifest variants.
+
+Pipeline: an Adapter yields a SourceTree (native structure, verbatim leaves),
+the descriptor engine generates what/when/keywords, cost annotation tokenizes
+and rolls up subtree costs, and emit writes one manifest per budget variant
+plus an llms.txt export.
+"""
+
+from .compiler import BuildResult, compile_source
+from .descriptors import (
+    Descriptor,
+    DescriptorModel,
+    FakeDescriptorModel,
+    Grade,
+    LLMDescriptorModel,
+    cache_from_manifest,
+    generate_descriptors,
+)
+from .ir import SourceNode, SourceTree
+
+__all__ = [
+    "BuildResult",
+    "Descriptor",
+    "DescriptorModel",
+    "FakeDescriptorModel",
+    "Grade",
+    "LLMDescriptorModel",
+    "SourceNode",
+    "SourceTree",
+    "cache_from_manifest",
+    "compile_source",
+    "generate_descriptors",
+]

askfaro_progressive_context-0.1.0/askfaro_progressive_context/build/_frontmatter.py

@@ -0,0 +1,62 @@
+"""Tiny frontmatter reader for markdown sources.
+
+Uses PyYAML if available; otherwise a minimal parser that handles the shapes
+our adapters need: top-level `key: value`, inline lists `[a, b]`, and a single
+nested mapping block (e.g. a one-fact memory store's `metadata:`). Keeps the core
+dependency-free.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def split_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+    if not text.startswith("---"):
+        return {}, text
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}, text
+    block = text[3:end].strip("\n")
+    body = text[end + 4 :].lstrip("\n")
+    return _parse_yaml(block), body
+
+
+def _parse_yaml(block: str) -> dict[str, Any]:
+    try:
+        import yaml  # type: ignore
+
+        data = yaml.safe_load(block)
+        return data if isinstance(data, dict) else {}
+    except ImportError:
+        return _minimal_parse(block)
+
+
+def _scalar(v: str) -> Any:
+    v = v.strip()
+    if v.startswith("[") and v.endswith("]"):
+        inner = v[1:-1].strip()
+        return [x.strip().strip("\"'") for x in inner.split(",")] if inner else []
+    return v.strip("\"'")
+
+
+def _minimal_parse(block: str) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    parent: str | None = None
+    for line in block.splitlines():
+        if not line.strip() or line.strip().startswith("#"):
+            continue
+        indented = line[0] in " \t"
+        key, _, val = line.strip().partition(":")
+        key = key.strip()
+        if indented and parent is not None:
+            if not isinstance(out.get(parent), dict):
+                out[parent] = {}
+            out[parent][key] = _scalar(val)
+        elif val.strip() == "":
+            out[key] = {}
+            parent = key
+        else:
+            out[key] = _scalar(val)
+            parent = None
+    return out

askfaro_progressive_context-0.1.0/askfaro_progressive_context/build/adapters/__init__.py

@@ -0,0 +1,21 @@
+"""Adapters turn a source on disk into a SourceTree.
+
+Phase 1 ships the four already-hierarchical kinds (no structure inference):
+docs, skills, tools, memory.
+"""
+
+from .base import Adapter, get_adapter, register_adapter
+from .docs import DocsAdapter
+from .memory import MemoryAdapter
+from .skills import SkillsAdapter
+from .tools import ToolsAdapter
+
+__all__ = [
+    "Adapter",
+    "DocsAdapter",
+    "MemoryAdapter",
+    "SkillsAdapter",
+    "ToolsAdapter",
+    "get_adapter",
+    "register_adapter",
+]

askfaro_progressive_context-0.1.0/askfaro_progressive_context/build/adapters/base.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from ..ir import SourceTree
+
+_REGISTRY: dict[str, "Adapter"] = {}
+
+
+class Adapter(Protocol):
+    kind: str
+
+    def load(self, path: Path, *, source_id: str | None = None) -> SourceTree:
+        ...
+
+
+def register_adapter(adapter: "Adapter") -> "Adapter":
+    _REGISTRY[adapter.kind] = adapter
+    return adapter
+
+
+def get_adapter(kind: str) -> "Adapter":
+    if kind not in _REGISTRY:
+        raise KeyError(f"unknown adapter kind {kind!r}; known: {sorted(_REGISTRY)}")
+    return _REGISTRY[kind]
+
+
+def slugify(text: str) -> str:
+    out = "".join(c if c.isalnum() else "-" for c in text.lower()).strip("-")
+    while "--" in out:
+        out = out.replace("--", "-")
+    return out or "node"