{"id":50549681,"url":"https://github.com/timolassmann/andamentum","last_synced_at":"2026-06-04T02:01:28.040Z","repository":{"id":362191150,"uuid":"1208462380","full_name":"TimoLassmann/andamentum","owner":"TimoLassmann","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-03T03:02:46.000Z","size":5349,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T05:06:05.548Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TimoLassmann.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T10:12:23.000Z","updated_at":"2026-06-03T03:02:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TimoLassmann/andamentum","commit_stats":null,"previous_names":["timolassmann/andamentum"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/TimoLassmann/andamentum","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimoLassmann%2Fandamentum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimoLassmann%2Fandamentum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimoLassmann%2Fandamentum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimoLassmann%2Fandamentum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimoLassmann","download_url":"https://codeload.github.com/TimoLassmann/andamentum/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimoLassmann%2Fandamentum/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33886160,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-04T02:01:26.662Z","updated_at":"2026-06-04T02:01:28.023Z","avatar_url":"https://github.com/TimoLassmann.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# andamentum\n\n[![Tests](https://github.com/timolassmann/andamentum/actions/workflows/test.yml/badge.svg)](https://github.com/timolassmann/andamentum/actions/workflows/test.yml)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Checked with pyright](https://img.shields.io/badge/type_checked-pyright-blue.svg)](https://github.com/microsoft/pyright)\n[![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)\n[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)\n\nA toolkit of small, composable, locally-runnable research tools.\n\nAndamentum is a single Python package of tightly-scoped, independent tools for\nworking with documents and sources — extracting them, organising and searching\nthem, rendering figures from data, and reviewing your own drafts. Each tool does\none thing and stands on its own; there is no orchestrator and no \"main\" entry\npoint. Some are backed by a language model; several use none at all. Reach for\none, or compose several.\n\nTwo commitments shape the whole package:\n\n- **Responsible by construction.** Confidentiality tripwires, robots.txt and\n  paywalled-publisher gating, SSRF-safe fetching, and AI-provenance watermarks —\n  in-code refusals and stamps, not markdown disclaimers. See\n  [`RESPONSIBLE_USE.md`](./RESPONSIBLE_USE.md).\n- **Explicit control, used sparingly.** Every public function that calls a\n  language model takes `model=` as a keyword-only argument — no shared config,\n  no ambient defaults — and models are used surgically: figure rendering,\n  readability scoring, and chunk segmentation are deterministic, not\n  model-driven. Point any of it at local (Ollama) models to run fully offline\n  when data can't leave your machine.\n\n## What's in the package\n\n**Authoring**\n- `andamentum.scribe` — block-based document drafting (paragraph, heading,\n  figure, table) backed by SQLite; renders to .docx\n- `andamentum.figures` — deterministic publication-quality figure rendering\n  with journal-matched sizing (9 chart types, 7 journal palettes)\n- `andamentum.typeset` — HTML / PDF typesetting used by other modules\n\n**Reviewing your own drafts**\n- `andamentum.whetstone` — criterion-cascade review of your own drafts\n  with track changes, panel mode, and optional novelty check\n- `andamentum.proofread` — deterministic readability + style checking (no LLM)\n- `andamentum.vision_critique` — bounded vision critique of rendered figures\n  via local multimodal models\n\n**Sourcing and indexing**\n- `andamentum.harvest` — universal source → markdown extraction (PDF / HTML /\n  DOCX / PPTX / Markdown / plain)\n- `andamentum.chunker` — structural-first semantic chunking of long markdown\n  into 2k–10k char self-contained units\n- `andamentum.document_store` — SQLite + FTS5 + sqlite-vec personal knowledge\n  base with 4-signal RRF search and LLM metadata extraction\n- `andamentum.deep_research` — web research pipeline (search → fetch → extract\n  → verify → synthesise) over a local SearXNG instance\n\n**Shared infrastructure**\n- `andamentum.core` — model resolution, agent runners, fetch gating, and\n  embedding clients\n\n## What andamentum is not\n\nIt is a set of building blocks you call from your own code or the command line —\nnot a chatbot, not an agent framework, and not a hosted service. whetstone, in\nparticular, refuses to run on material another author has shared with you in\nconfidence.\n\n## Installation\n\n```bash\npip install andamentum\n```\n\nThe core install works out of the box. Two optional extras add heavier,\nself-contained capabilities:\n\n```bash\npip install 'andamentum[html-articles]'   # trafilatura — best-in-class HTML article extraction\npip install 'andamentum[pdf]'             # WeasyPrint — PDF output for andamentum-typeset\n```\n\n## Quickstart\n\nReview a draft you wrote yourself:\n\n```python\nimport asyncio\nfrom andamentum.whetstone import review_document\n\nresult = asyncio.run(\n    review_document(\n        \"draft.md\",\n        model=\"anthropic:claude-haiku-4-5\",\n        confirm_own_draft=True,\n    )\n)\nprint(result.summary)\n```\n\nEvery public function that calls an LLM takes `model=` as a keyword-only\nargument. Set `ANDAMENTUM_MAIN_LLM_MODEL` once to avoid passing `--model` on\nevery CLI invocation:\n\n```bash\nexport ANDAMENTUM_MAIN_LLM_MODEL=anthropic:claude-haiku-4-5\n```\n\n## Command-line tools\n\nTen CLIs are installed with the package. Run `--help` on any of them for\nthe full flag reference.\n\n| Command | What it does | LLM? |\n|---|---|---|\n| `andamentum-scribe` | Block-based document authoring backed by SQLite; renders to .docx | none |\n| `andamentum-figures` | Publication-quality scientific figure rendering (9 chart types, journal-matched sizing). Deterministic plotting — no generative AI. | none |\n| `andamentum-whetstone` | Criterion-cascade review of your own draft → markdown / HTML / .docx with track changes. Five subcommands: `review` (default), `panel` (multi-expert), `proofread` (no LLM), `apply-patches` (no LLM), `verify-provenance` (no LLM) | required for `review` + `panel` |\n| `andamentum-proofread` | Deterministic readability + style check (SMOG, Flesch–Kincaid, weasel words, passive voice, weak openers, adverb density). Accepts URLs, PDF, DOCX, HTML, PPTX, Markdown, plain text. | none |\n| `andamentum-harvest` | Universal source → markdown extraction (PDF / HTML / DOCX / PPTX / Markdown / plain, auto-detected) | none |\n| `andamentum-typeset` | Render Markdown to typeset HTML / PDF in three styles (article / cv / report). PDF needs the `pdf` extra. | none |\n| `andamentum-chunker` | Verifiable semantic chunking of long markdown into 2k–10k char self-contained units | required |\n| `andamentum-vision-critique` | Vision-critique a rendered figure → bounded JSON (label overlap, legibility, suggested fixes). Multimodal model required | required (multimodal) |\n| `andamentum-research` | Web-research pipeline (search → fetch → extract → verify → synthesise) over a local SearXNG instance | required |\n| `andamentum-epistemic` | Formal-epistemology pipeline: `ask \"\u003cquestion\u003e\"` (decompose + research) or `verify \"\u003cclaim\u003e\"` (single-claim verification) | required |\n\n## Documentation\n\nSee [`docs/`](./docs/) for module-level documentation and\n[`examples/`](./examples/) for runnable code demonstrating common workflows.\n\n## Intended use and limits\n\nPlease read [`RESPONSIBLE_USE.md`](./RESPONSIBLE_USE.md) before\npublishing or submitting anything produced with andamentum.\n\nThe short version:\n\n- **`whetstone` is for your own drafts.** It is not a peer-review\n  tool. Do not run it on manuscripts, grant proposals, or other\n  documents shared with you in confidence. Most publishers and\n  funders currently prohibit AI in peer review.\n- **AI disclosure is your responsibility.** Manuscripts, grant\n  proposals, theses, peer reviews, and similar artifacts that\n  incorporate output from andamentum's LLM-using sub-modules must\n  disclose that use per ICMJE / NIH / NHMRC / ARC / COPE / your\n  institution's rules.\n- **`harvest` and `deep_research` consult `robots.txt`** before every\n  external fetch and refuse paywalled academic publishers (Elsevier,\n  Springer Nature, Wiley, IEEE, ACM, NEJM, JAMA, Cell Press, Nature,\n  Science) unless the caller passes `tdm_allowed_hosts` (API) or\n  `--tdm-host` (CLI). Bulk extraction without a TDM licence is\n  contractually prohibited by these publishers.\n- **`figures` plots data, it does not generate it.** Deterministic\n  matplotlib wrapper. Auto-applied visual decisions are reported\n  in `FigureResult.advisor_notes` — mirror them in your captions.\n- **Cloud inference sends your content to the provider.** Use local\n  Ollama models for inputs subject to ethics, NDA, MTA, DUA, or\n  institutional data-classification rules.\n\n`andamentum` is MIT-licensed and ships without warranty. The full\nguidance lives in [`RESPONSIBLE_USE.md`](./RESPONSIBLE_USE.md).\n\n## Pre-release / experimental\n\nThe package includes an additional sub-module that ships installed but is not\nyet publicly documented:\n\n- **`andamentum.epistemic`** — still under active development. The API is\n  unstable and the published documentation does not yet describe it; if you\n  discover it via `pip show -f andamentum` or `andamentum-epistemic --help`,\n  treat it as experimental. A dedicated release will accompany the\n  documentation when the module stabilises.\n\n## License\n\nMIT. See [`LICENSE`](./LICENSE).\n\n## Acknowledgements\n\nandamentum builds on a substantial body of open-source software and\npublicly-funded data infrastructure.\n\n### Software\n\n- **[SearXNG](https://github.com/searxng/searxng)** — privacy-preserving\n  metasearch; self-hosted in `deep_research`. AGPL-3.0.\n- **[trafilatura](https://trafilatura.readthedocs.io/)** — HTML article\n  extraction.\n  Barbaresi, A. (2021). \"Trafilatura: A Web Scraping Library and\n  Command-Line Tool for Text Discovery and Extraction\", *ACL-IJCNLP\n  2021 System Demonstrations*.\n- **[Docling](https://github.com/DS4SD/docling)** (IBM Research) — PDF,\n  DOCX, PPTX extraction.\n- **[pydantic-ai](https://github.com/pydantic/pydantic-ai)** and\n  **[pydantic-graph](https://github.com/pydantic/pydantic-graph)** —\n  agent and DAG infrastructure used across the package.\n- **[sqlite-vec](https://github.com/asg017/sqlite-vec)** (Alex Garcia)\n  — vector search inside SQLite, used by `document_store`.\n- **[Ollama](https://ollama.com/)** and\n  **[EmbeddingGemma](https://huggingface.co/google/embeddinggemma-300m)**\n  (Google) — local embedding and LLM inference.\n- **[textstat](https://github.com/textstat/textstat)** — readability\n  metrics used by `proofread`.\n- **[scikit-learn](https://scikit-learn.org/)** — used internally.\n  Pedregosa et al. (2011). \"Scikit-learn: Machine Learning in Python\",\n  *JMLR* 12: 2825–2830.\n\n### Algorithms\n\n- **Reciprocal Rank Fusion** (RRF) — multi-signal search fusion in\n  `document_store.chunks_search`.\n  Cormack, G.V., Clarke, C.L.A., Büttcher, S. (2009). \"Reciprocal\n  Rank Fusion outperforms Condorcet and individual rank learning\n  methods\", *SIGIR '09*.\n- **Dirichlet-Hawkes Process** (DHP) — temporal clustering in\n  `document_store.dhp`.\n  Du, N., Farajtabar, M., Ahmed, A., Smola, A., Song, L. (2015).\n  \"Dirichlet-Hawkes Processes with Applications to Clustering\n  Continuous-Time Document Streams\", *KDD '15*.\n- **HDBSCAN** — density-based clustering.\n  Campello, R.J.G.B., Moulavi, D., Sander, J. (2013).\n  \"Density-Based Clustering Based on Hierarchical Density\n  Estimates\", *PAKDD '13*. McInnes, L., Healy, J., Astels, S.\n  (2017). \"hdbscan: Hierarchical density based clustering\",\n  *JOSS* 2(11): 205.\n- **BM25** — keyword scoring via SQLite FTS5.\n  Robertson, S., Zaragoza, H. (2009). \"The Probabilistic Relevance\n  Framework: BM25 and Beyond\", *Foundations and Trends in\n  Information Retrieval* 3(4): 333–389.\n\n### Data sources\n\nUsers running the web-research pipeline are bound by each provider's\nterms of use and rate limits. Where the provider asks to be credited\nin publications, please respect that.\n\n- **PubMed / E-utilities** — NCBI / National Library of Medicine.\n  Please set an `NCBI_API_KEY` for the 10 req/s rate, otherwise the\n  pipeline throttles to 3 req/s.\n  https://www.ncbi.nlm.nih.gov/books/NBK25497/\n- **arXiv API** — 1 request per 3 seconds per the arXiv API manual.\n  https://info.arxiv.org/help/api/tou.html\n- **Europe PMC REST API** — please credit Europe PMC where data is\n  shown.\n  https://europepmc.org/Help#whyepmc\n- **bioRxiv** — Cold Spring Harbor Laboratory.\n  https://api.biorxiv.org/\n- **ClinicalTrials.gov API v2** — NIH / National Library of\n  Medicine.\n  https://clinicaltrials.gov/data-api/about-api/api-policy\n- **ChEMBL** — EMBL-EBI.\n  https://chembl.gitbook.io/chembl-interface-documentation/web-services\n- **Monarch Initiative** —\n  https://monarchinitiative.org/about/data-and-services\n- **Open Targets Platform** — EMBL-EBI / GSK / Sanger / others.\n  https://platform-docs.opentargets.org/citation\n- **OpenAlex** —\n  https://docs.openalex.org/how-to-use-the-api/api-overview\n- **Cochrane review abstracts** are accessed only via PubMed; full\n  Cochrane reviews are © Wiley and are not retrieved by this code.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimolassmann%2Fandamentum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimolassmann%2Fandamentum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimolassmann%2Fandamentum/lists"}