pasr-mcp 0.2.0__tar.gz

pasr_mcp-0.2.0/.gitignore

@@ -0,0 +1,226 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# PASR local artifacts — receipts are ignored, Context Packs are committable
+.pasr/*
+!.pasr/packs/
+eval/runs/
+eval/pasr_eval/runs/
+pasr-bench-runs/
+.eval-checkouts/

pasr_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to PASR. Format follows [Keep a Changelog](https://keepachangelog.com/);
+this project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-09-07
+
+First public release. A zero-setup, offline, deterministic context-broker MCP for
+coding and document agents. (0.1.x was the internal M0–M12 build; it was never
+published.)
+
+### MCP tools (stdio)
+
+- **`select_context`** — a budgeted, provenance-tracked slice of the workspace for a
+  query. BM25 + lexical coverage + tree-sitter symbol candidates, optionally an
+  in-process sub-word or MiniLM semantic scorer, fused by reciprocal-rank fusion, then
+  line-aligned active-window assembly under a hard `budget_tokens` cap. Returns the
+  assembled `context`, a `spans` list with `file:line` + token count + reason per span,
+  a `route` (`lossless` when the whole input already fit, else `selected`), full token
+  accounting, and a `query_class` / `confidence` / `advice` triple that tells the agent
+  when PASR is the wrong tool (e.g. aggregation-style questions).
+  - **`map_tokens=N`** — prepend a query-ranked `file:line kind name` symbol index of
+    up to `N` tokens, carved out of `budget_tokens` (never additive), skipped on a
+    `lossless` route. Repo-map-style pointer coverage of the whole file set without
+    giving up the bodies in the slice; in the offline bake-off it lifts `retrieval_ok`
+    from 0.70 to 0.90 (ties a full repo-map) at perfect critical-file coverage.
+    Recorded under `diagnostics.symbol_map`.
+  - **`trace="<symbol>"`** — fold that symbol's dependency closure into the slice as a
+    `# dependency closure` header, also carved out of `budget_tokens`. A one-call
+    "slice + closure" for trace-style questions; recorded under `diagnostics.trace`.
+- **`trace_dependencies`** — deterministic transitive definition closure for a symbol
+  (Python, JS/TS), in source order, with `file:line` provenance and `defines` /
+  `dependencies` per span. An undefined symbol returns `found: false`, not an error.
+  - **`direction="callers"`** — reverse the edges: the closure of every definition that
+    transitively *references* the symbol. Impact analysis — "what breaks if I change
+    this."
+- **`explain_selection`** — the stored receipt for a prior selection: kept spans,
+  dropped candidates with ranks, and the budget accounting.
+- **`expand_context`** — re-run a prior selection once with a larger budget.
+
+Every real `select_context` call (MCP, and `pasr explain` unless `--no-ledger`)
+appends a row to `.pasr/ledger.jsonl` (gitignored): tokens in vs. out, round trips
+saved, route.
+
+### CLI
+
+- `pasr explain` / `pasr trace` (`--callers`) / `pasr pack` / `pasr context` /
+  `pasr review` / `pasr report`.
+- **`pasr review`** — diff-aware context. From a unified diff (`git diff`, `--staged`,
+  `--range A..B`, or `--diff FILE`) it returns the definitions the change *touches*
+  (innermost def per hunk, not the whole enclosing class) plus the definitions that
+  *call* them (a one-level reverse closure), packed under `--budget` with `file:line`
+  provenance. `--json` / `--context-file` for machines.
+- **`pasr report`** — summarise `.pasr/ledger.jsonl`: "PASR handed the model N fewer
+  tokens across M calls, R round trips saved", with `--since` and an optional
+  `--price-per-mtok` dollar estimate.
+- **`pasr context`** — headless slice for CI / autonomous agents, `--format
+  text|json`, `--metrics-file`, `--context-file`; a composite GitHub Action at
+  `.github/actions/pasr-context/`.
+
+### Other
+
+- **Receipts** — byte-stable `.pasr/receipts/<id>.{json,md}` audit records (gitignored).
+- **Context Packs** — committable `.pasr/packs/<name>.json` warm-start slices, loadable
+  with `select_context(pack=…)`, with `source_fingerprint` staleness detection.
+- **Routing** — `classify_query` + `assess` produce the confidence and ordered advice.
+- Torch-free, `mcp`-SDK-free core; `tiktoken` + `pathspec` + `tree-sitter` runtime.
+- **PASR-Bench** — the evaluation harness is a standalone distribution (`pip install
+  ./eval`, package `pasr-bench`, console script `pasr-bench {run,bakeoff,plans}`).
+  Pre-registered 4-arm protocol, paired non-inferiority vs a whole-repo dump,
+  `validate_matrix` (no synthetic rows, no leak, matched matrix). "Bring your own
+  retriever" — add an arm and measure it against the same 50 tasks. Results:
+  `eval/RESULTS.md`, `docs/competitors-benchmark.md`.
+
+[Unreleased]: https://github.com/Apheironn/pasr/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/Apheironn/pasr/releases/tag/v0.2.0

pasr_mcp-0.2.0/CITATION.cff

@@ -0,0 +1,28 @@
+cff-version: 1.2.0
+message: "If you use PASR in your work, please cite it as below."
+title: "PASR — Provenance-Aware Span Recall"
+abstract: >-
+  A zero-setup context-broker MCP server for coding and document agents. Given a query
+  and a workspace it returns a small, hard-budgeted, fully-traceable slice: every span
+  carries its file:line, token count, retrieval score, and the reason it was kept. It
+  classifies each query and signals when it is the wrong tool. Deterministic and offline
+  by default.
+type: software
+authors:
+  - family-names: Catak
+    given-names: Mertcan
+    alias: Apheironn
+repository-code: "https://github.com/Apheironn/pasr"
+url: "https://github.com/Apheironn/pasr"
+license: Apache-2.0
+version: 0.2.0
+date-released: 2026-09-07
+keywords:
+  - model-context-protocol
+  - mcp
+  - retrieval
+  - context-engineering
+  - coding-agent
+  - code-search
+  - token-budget
+  - provenance

pasr_mcp-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer through a private report on the repository's
+[Security tab](https://github.com/Apheironn/pasr/security/advisories/new) or by
+contacting [@Apheironn](https://github.com/Apheironn) on GitHub. All complaints
+will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

pasr_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to PASR
+
+Thanks for looking. PASR is small on purpose; the bar for changes is "does it keep the
+invariants and pay for its own complexity".
+
+## Setup
+
+```bash
+python -m venv .venv && . .venv/bin/activate      # or .venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+pytest -q
+```
+
+## Before you open a PR
+
+All three must be green:
+
+```bash
+ruff check src tests eval
+ruff format --check src tests eval
+pytest -q
+```
+
+CI runs the same on Python 3.10 and 3.12, plus a torch-free / mcp-free import check on
+the core and a headless `pasr context` smoke.
+
+## Invariants (do not regress)
+
+1. The pure-logic core imports **no** `torch` / `transformers`, and no `mcp` SDK
+   outside `pasr.mcp`. Runtime deps stay minimal.
+2. `budget_tokens` is a hard cap — never return more.
+3. Lossless under budget: if the full context already fits, return it unchanged.
+4. Deterministic: same repo + query + config ⇒ identical bytes. No wall-clock, no
+   salted `hash()`, LF-normalized content hashes.
+5. Offline by default: no network, no daemon, no vector DB. External scorers are opt-in
+   extras.
+6. Every returned span carries `file:line` provenance, a token count, and a reason.
+
+A change that touches retrieval or assembly needs a test that pins the new behaviour,
+and the `examples/` transcripts regenerated (`bash scripts/gen_examples.sh`) if their
+output moves.
+
+## Scope
+
+New capability proposals should open an issue first describing the user-visible
+behaviour and which invariant budget it spends; `docs/roadmap.md` has the current
+scope. Model-internal ideas belong in the research line, not here — PASR stays
+model-external.
+
+## Style
+
+Line length 120. English for code and docs. Match the file you are in. `unittest`-style
+classes and plain `pytest` functions both exist; follow the neighbouring test file.
+
+## Commits
+
+Conventional-ish subject lines (`area: what changed`). One logical change per commit.
+
+## Conduct and security
+
+By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md). Security
+issues go through [SECURITY.md](SECURITY.md) — a private report, not a public issue.