foveance 0.1.0__tar.gz

foveance-0.1.0/.dockerignore

@@ -0,0 +1,18 @@
+.git
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+.coverage
+htmlcov/
+bench/results/
+bench/results_real/
+bench/results_mock/
+bench/plots/
+paper/
+prompts/
+CLAUDE.md
+dist/
+data/

foveance-0.1.0/.gitattributes

@@ -0,0 +1,13 @@
+# Normalize line endings: LF in the repo, native on checkout.
+* text=auto eol=lf
+*.png binary
+*.pdf binary
+*.docx binary
+*.whl binary
+*.gz binary
+
+# Keep generated/vendored files out of language stats and diffs where noisy.
+assets/* linguist-documentation
+bench/report.md linguist-documentation
+docs/* linguist-documentation
+*.svg -diff

foveance-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Something doesn't work as documented
+title: "[bug] "
+labels: bug
+---
+
+**What happened**
+A clear description of the bug.
+
+**Reproduce**
+Exact command(s) and the smallest input that triggers it:
+```bash
+python bench/run_bench.py --backend mock ...
+```
+
+**Expected**
+What you expected instead.
+
+**Environment**
+- OS / Python version:
+- Foveance version (`foveance version`):
+- Extras installed (`[dev]`/`[bench]`/`[proxy]`/`[ml]`):
+- If a benchmark issue: attach `bench/results/headline.json` and model/hardware details.
+
+**Logs**
+Paste relevant output (and `bench/results/drift_twin_audit.json` if arms behave unexpectedly).

foveance-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,21 @@
+---
+name: Feature request
+about: Propose an addition (new policy, suite adapter, embedder, ...)
+title: "[feat] "
+labels: enhancement
+---
+
+**Motivation**
+What problem does this solve? Who benefits?
+
+**Proposal**
+What you'd add and where (e.g. a new arm in `foveance.baselines`, a `Suite` adapter in
+`bench/tasks.py`, an `Embedder`).
+
+**Novelty / positioning check**
+Does this stay within the claim boundaries in `docs/NOVELTY.md`? If it adds a comparison
+method, note the citation.
+
+**Alternatives considered**
+
+**Willing to submit a PR?** yes / no

foveance-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+# Pull request
+
+## What and why
+<!-- One or two sentences on the change and the motivation. -->
+
+## Checklist
+- [ ] `make lint` is clean (ruff + mypy)
+- [ ] `make cov` keeps core coverage at or above 90%
+- [ ] New behavior has tests; new policies are registered in `foveance.baselines.POLICIES`
+- [ ] If the `reactive_afm` / `foveance` arms were touched, the drift-twin audit
+      (`bench/results/drift_twin_audit.json`) still reports `only_difference_is_drift: true`
+- [ ] No fabricated benchmark numbers; any results come from a real run
+- [ ] Docstrings on public API; type hints throughout
+- [ ] Claims stay within the boundaries in `docs/NOVELTY.md`
+
+## Results / evidence
+<!-- For perf or benchmark changes, paste the relevant CSV rows or the headline.json diff. -->

foveance-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "${{ matrix.python-version }}" }
+      - run: pip install -e ".[dev,bench,proxy]"
+      - name: lint
+        run: ruff check src tests bench
+      - name: type-check
+        run: mypy src
+      - name: tests + core coverage gate
+        run: |
+          pytest -q --cov=foveance.store --cov=foveance.predictor \
+            --cov=foveance.allocator --cov=foveance.controller \
+            --cov-report=term-missing --cov-fail-under=90
+      - name: offline benchmark smoke + analysis
+        run: |
+          python bench/run_bench.py --backend mock --models mock --suite synthetic \
+            --budgets 1000,2500 --tasks 4 --turns 30 --name-target false \
+            --fidelity-cost true --greedy-gap --ablations
+          python bench/analyze.py
+          python bench/plots.py
+      - name: cli smoke
+        run: foveance demo --budgets 1000,2500 --turns 18

foveance-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with: { name: dist, path: dist/* }
+
+  publish:
+    # Publishes to PyPI via Trusted Publishing (OIDC, no stored secrets).
+    # Configure the project on PyPI first, then this runs on every v* tag.
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist }
+      - uses: pypa/gh-action-pypi-publish@release/v1

foveance-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+htmlcov/
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+# generated artifacts (reproducible); the REAL benchmark evidence in bench/results/,
+# bench/plots/, and bench/results_baselines/ is committed on purpose -- the docs and README
+# promise every number traces to these files.
+# The research manuscript and internal build specs are kept local, out of the public package.
+paper/
+prompts/
+CLAUDE.md
+bench/results_real/
+bench/results_mock/
+bench/results_*/
+!bench/results_baselines/
+bench/report_mock.md
+data/
+!data/longbench/sample.jsonl
+.cache/

foveance-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        files: ^src/
+        additional_dependencies: []
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-added-large-files

foveance-0.1.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-22
+### Added
+- `foveance wrap` — run any CLI/agent through the proxy with one command: starts the proxy,
+  sets `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` for the child process only, launches the tool,
+  and prints a tokens-saved summary (with a ≈$ estimate at `--price-per-mtok`) on exit.
+- Live dashboard at `GET /` and `/admin`: running tokens-saved counter, %, and $-equivalent,
+  polling `/admin/stats` (which now reports `est_tokens_before/after/saved`, `est_saved_pct`,
+  `est_usd_saved`, and `compressed_requests`).
+- Prompt-cache-aware compression: blocks carrying Anthropic `cache_control` are never modified,
+  and `--cache-aware` additionally freezes everything at or before the last breakpoint so the
+  provider's prompt cache is never invalidated (cost arithmetic in `docs/limitations.md`).
+- Structure-preserving in-place compression for agentic requests (Anthropic tool_use/tool_result,
+  OpenAI tool_calls, and the OpenAI Responses API used by Codex), protecting the most recent
+  `--agentic-protect-last` turns; verified live with Claude Code.
+- Additional baseline arms `truncate` and `uniform` in the package and benchmark; single-shot
+  head-to-head probe (`bench/compare_baselines.py`) including real LLMLingua-2.
+- Anticipatory predictor with a forward-drifting future-query posterior; `drift=0` recovers the
+  reactive (AFM) criterion.
+- Multi-fidelity reversible store (POINTER/GIST/DIGEST/FULL) with content-hash-cached renders.
+- Index allocator (Lagrangian/Whittle greedy on concave envelopes), exact DP oracle, and LP
+  bound, giving the `index <= OPT <= LP` sandwich.
+- Compressors (heuristic + LLM), embedders (hashing/sentence-transformers/API), metrics, a
+  learned logistic future-relevance predictor, and an OpenAI-compatible reverse proxy.
+- Baselines as first-class policy arms: `full`, `recency`, `reactive_afm`, `oracle`, optional
+  `llmlingua2`; a drift-twin audit proves `reactive_afm` and `foveance` differ only in drift.
+- Benchmark harness (suites, budget sweep, bootstrap CIs, paired Wilcoxon, greedy-gap, drift /
+  predictor / retrieve / fidelity-cost ablations) with synthetic and LongBench/RULER/AppWorld/
+  OfficeBench adapters that skip gracefully when data is absent.
+- Theory summary (`docs/theory.md`) backed by five theorems with full proofs in the accompanying manuscript.
+- CLI (`foveance demo|proxy|bench|version`), examples, docs, and CI across Python 3.10-3.13.
+
+### Performance
+- `index_allocate` reimplemented with a binary heap, attaining the documented
+  `O(sum_i L_i log sum_i L_i)` time (previously re-sorted the queue each iteration); allocates
+  4000 items in tens of milliseconds. A reproducible overhead benchmark is in `bench/overhead.py`.
+
+### Fixed
+- Proxy `/v1/chat/completions` route returned HTTP 422 because a stringized `Request`
+  annotation (from `from __future__ import annotations`) was not recognized by FastAPI; the
+  route now takes the JSON body as a dict and is covered by a real end-to-end HTTP test.
+
+### Testing & tooling
+- Property-based tests (Hypothesis) for the allocator invariants: budget feasibility,
+  monotonicity, the one-item greedy bound, and the `IDX <= OPT <= LP` sandwich.
+- End-to-end proxy integration test over real HTTP (threaded upstream + FastAPI TestClient).
+- `py.typed` marker (PEP 561), `mkdocs.yml`, `Dockerfile`/`.dockerignore`, `.pre-commit-config.yaml`,
+  `CITATION.cff`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, PR template, and a PyPI release workflow.
+
+### Notes
+- Real-model results (Gemma/Qwen/Llama via Ollama) show budgeted policies reaching full-replay
+  accuracy at roughly 61-62% fewer tokens; see `bench/report.md`. No numbers are hand-entered.

foveance-0.1.0/CITATION.cff

@@ -0,0 +1,30 @@
+cff-version: 1.2.0
+message: "If you use Foveance, please cite the software and the accompanying paper."
+title: "Foveance: Anticipatory Context Allocation for Long-Horizon LLM Agents"
+abstract: >-
+  Foveance is a black-box, reversible, anticipatory context-allocation layer for long-horizon
+  LLM agents. It spends a fixed token budget across accumulated context held at multiple
+  fidelities, choosing each item's fidelity by its expected future relevance, backed by a
+  predictive trajectory rate-distortion theory.
+type: software
+authors:
+  - family-names: Maghsoodi
+    given-names: Abtin
+version: 0.1.0
+license: Apache-2.0
+repository-code: "https://github.com/aimaghsoodi/foveance"
+keywords:
+  - large-language-models
+  - agents
+  - context-compression
+  - rate-distortion
+  - kv-cache
+preferred-citation:
+  type: article
+  title: >-
+    Foveance: A Predictive Rate-Distortion Theory of Anticipatory, Reversible Context
+    Compression for Black-Box LLM Agents
+  authors:
+    - family-names: Maghsoodi
+      given-names: Abtin
+  year: 2026

foveance-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,24 @@
+# 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, religion,
+or sexual identity and orientation.
+
+## Our standards
+Examples of behavior that contributes to a positive environment include using welcoming and
+inclusive language, being respectful of differing viewpoints, gracefully accepting constructive
+criticism, and focusing on what is best for the community. Unacceptable behavior includes
+harassment, trolling, insulting or derogatory comments, and publishing others' private
+information without permission.
+
+## Enforcement
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the
+project maintainers. All complaints will be reviewed and investigated promptly and fairly.
+Maintainers are obligated to respect the privacy and security of the reporter.
+
+## Attribution
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

foveance-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to Foveance
+
+Thanks for your interest! Foveance aims to be a small, rigorous, reviewer-proof codebase.
+
+## Ground rules
+- **Never fabricate benchmark numbers.** Every figure in the report traces to a CSV in
+  `bench/results/`. Unmeasured = `TODO`, not invented.
+- **Keep the novelty boundary honest.** The multi-fidelity store under a budget is prior art
+  (AFM, ContextBudget, ACON, MemAct). Don't claim it. See [`docs/NOVELTY.md`](docs/NOVELTY.md).
+- **Core stays dependency-free.** `store/predictor/allocator/controller` must run offline with no
+  third-party imports. ML/proxy/bench deps live behind extras.
+
+## Dev setup
+```bash
+pip install -e ".[dev,bench]"
+make test     # pytest
+make cov      # coverage gate on core modules (target ≥90%)
+make lint     # ruff + mypy
+```
+
+## Before opening a PR
+1. `make lint` is clean (ruff + mypy).
+2. `make cov` keeps core coverage ≥90%.
+3. New behavior has tests; new policies are added to `foveance.baselines.POLICIES`.
+4. If you touch the `reactive_afm`/`foveance` arms, the drift-twin audit
+   (`bench/results/drift_twin_audit.json`) must still report `only_difference_is_drift: true`.
+5. Docstrings on public API; type hints throughout.
+
+## Commit style
+Small, reviewable commits. If you work within the phased build, tag commits `[phase N]`.
+
+## Reporting issues
+Use the templates in `.github/ISSUE_TEMPLATE/`. For benchmark discrepancies, include the exact
+command, the `headline.json`, and your hardware/model versions.

foveance-0.1.0/Dockerfile

@@ -0,0 +1,16 @@
+# Reproducible Foveance environment (offline core + benchmark).
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY . /app
+
+# Install the package with dev + bench extras; core itself is dependency-free.
+RUN pip install --no-cache-dir -e ".[dev,bench]"
+
+# Smoke test at build time so a broken image fails fast.
+RUN pytest -q && foveance demo --budgets 1000,2500 --turns 18
+
+# Default: run the offline benchmark + analysis + plots.
+CMD ["bash", "-lc", "python bench/run_bench.py --backend mock --models mock --suite synthetic \
+  --budgets 600,1200,2500 --tasks 4 --turns 30 --greedy-gap --ablations && \
+  python bench/analyze.py && python bench/plots.py && cat bench/report.md"]

foveance-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+SPDX-License-Identifier: Apache-2.0
+
+Copyright 2026 Abtin Maghsoodi
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at: http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+NOTE (Phase 5 / release): replace this stub with the full verbatim text of the
+Apache License 2.0 from the URL above before publishing the repository.

foveance-0.1.0/Makefile

@@ -0,0 +1,40 @@
+.PHONY: install test cov lint bench demo repro clean
+
+install:
+	pip install -e ".[dev,bench]"
+
+# Full pytest suite (falls back to the seed script runner if pytest is absent).
+test:
+	@python -m pytest -q 2>/dev/null || python tests/test_allocator.py
+
+# Coverage gate on the core modules.
+cov:
+	python -m pytest -q --cov=foveance.store --cov=foveance.predictor \
+	  --cov=foveance.allocator --cov=foveance.controller --cov-report=term-missing
+
+lint:
+	@ruff check src tests bench 2>/dev/null || echo "ruff not installed (pip install -e .[dev])"
+	@mypy src 2>/dev/null || echo "mypy not installed (pip install -e .[dev])"
+
+# Offline benchmark (mock model) — CI-safe, no GPU/network.
+demo:
+	foveance demo
+
+bench:
+	python bench/run_bench.py --backend mock --models mock --suite synthetic \
+	  --budgets 600,1200,1600,2500,4000 --tasks 6 --turns 40 --drift 0.7 \
+	  --name-target false --fidelity-cost true --greedy-gap --ablations
+	python bench/analyze.py
+	python bench/plots.py
+
+# Real benchmark example (needs Ollama running locally).
+bench-real:
+	python bench/run_bench.py --backend ollama \
+	  --models gemma2:9b,gemma2:2b,qwen2.5:7b,llama3.1:8b \
+	  --budget 2400 --tasks 8 --turns 60 --drift 0.7
+
+repro: test bench
+	@echo "Offline repro complete: CSVs in bench/results/, plots in bench/plots/, report in bench/report.md."
+
+clean:
+	rm -rf **/__pycache__ .pytest_cache .mypy_cache .ruff_cache