distribird 0.1.0__tar.gz

distribird-0.1.0/.dockerignore

@@ -0,0 +1,12 @@
+.venv
+__pycache__
+*.pyc
+.git
+.github
+.claude
+tests
+paper
+*.docx
+.mypy_cache
+.pytest_cache
+.ruff_cache

distribird-0.1.0/.env.example

@@ -0,0 +1,19 @@
+# Distribird configuration
+# Copy to .env and fill in your values:  cp .env.example .env
+
+# Auth (change these!)
+DISTRIBIRD_AUTH_USERNAME=demo
+DISTRIBIRD_AUTH_PASSWORD=changeme
+
+# LLM (required — any OpenAI-compatible endpoint via LiteLLM)
+DISTRIBIRD_LLM_BASE_URL=https://your-llm-host.example.com/api
+DISTRIBIRD_LLM_API_KEY=sk-your-key-here
+DISTRIBIRD_LLM_MODEL=gemini-3-pro
+
+# Semantic Scholar (optional, increases rate limits)
+DISTRIBIRD_SEMANTIC_SCHOLAR_API_KEY=
+
+# Deep Research (optional)
+DISTRIBIRD_DEEP_RESEARCH_BASE_URL=
+DISTRIBIRD_DEEP_RESEARCH_API_KEY=
+DISTRIBIRD_DEEP_RESEARCH_MODEL=o4-mini-deep-research

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

@@ -0,0 +1,99 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff check
+        run: ruff check src/ tests/
+
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Mypy
+        run: mypy src/distribird/
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest --tb=short -q
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: pip install --upgrade pip build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check package metadata
+        run: |
+          pip install twine
+          twine check dist/*
+
+  docker:
+    name: Docker Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build Docker image
+        run: docker build -t distribird:ci .

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

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Build & Publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: pip install --upgrade pip build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

distribird-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Environment / secrets
+.env
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing / linting caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude Code
+.claude/

distribird-0.1.0/.streamlit/config.toml

@@ -0,0 +1,3 @@
+[theme]
+base = "light"
+primaryColor = "#2d6a4f"

distribird-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to Distribird
+
+Contributions are welcome! Here's how to get started.
+
+## Development Setup
+
+```bash
+git clone https://github.com/HUN-REN-AI1Science/Distribird.git
+cd distribird
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+## Code Style
+
+We use ruff for linting and formatting:
+
+```bash
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+Type checking with mypy:
+```bash
+mypy src/distribird/
+```
+
+## Pull Requests
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+## Reporting Issues
+
+Please open an issue on GitHub with:
+- A clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior

distribird-0.1.0/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.13-slim
+
+WORKDIR /app
+
+# System deps for matplotlib
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libglib2.0-0 libsm6 libxrender1 libxext6 && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml README.md ./
+COPY src/ src/
+
+RUN pip install --no-cache-dir .
+
+COPY examples/ examples/
+
+EXPOSE 8501 8000

distribird-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roland Hollos, Patrik P. Süli
+
+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.

distribird-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: distribird
+Version: 0.1.0
+Summary: Literature-informed Prior distributions for Bayesian model calibration
+Project-URL: Repository, https://github.com/HUN-REN-AI1Science/Distribird
+Project-URL: Documentation, https://distribird.streamlit.app
+Author: Roland Hollos, Patrik P. Süli
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bayesian,calibration,distribution,literature,prior
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.104
+Requires-Dist: httpx>=0.25
+Requires-Dist: langgraph>=1.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: openai>=1.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: scipy>=1.11
+Requires-Dist: streamlit-local-storage>=0.0.21
+Requires-Dist: streamlit>=1.28
+Requires-Dist: uvicorn[standard]>=0.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo.svg" alt="Distribird" width="360">
+</p>
+
+<p align="center">
+  <strong>Automated Bayesian prior construction from scientific literature</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10+"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/tests-148%20passed-brightgreen" alt="Tests: 148 passed">
+  <img src="https://img.shields.io/badge/lint-ruff-261230?logo=ruff&logoColor=D7FF64" alt="Linting: ruff">
+  <a href="https://langgraph.dev/"><img src="https://img.shields.io/badge/orchestration-LangGraph-1C3C3C?logo=langchain&logoColor=white" alt="LangGraph"></a>
+  <a href="https://fastapi.tiangolo.com"><img src="https://img.shields.io/badge/API-FastAPI-009688?logo=fastapi&logoColor=white" alt="FastAPI"></a>
+  <a href="https://distribird.streamlit.app"><img src="https://static.streamlit.io/badges/streamlit_badge_black_white.svg" alt="Open in Streamlit"></a>
+</p>
+
+---
+
+**Distribird** turns a parameter name and description into a fully cited, publication-ready prior distribution.
+It searches Semantic Scholar, OpenAlex, and LLM deep-research agents in parallel, extracts numerical values from papers, and fits the best-matching `scipy.stats` distribution via AIC selection.
+
+> *"I need a prior for maximum leaf area index of maize."*
+>
+> &#x279C; `truncated_normal(mu=5.2, sigma=1.5, a=0, b=12)` &mdash; fitted from 6 peer-reviewed sources with full citations.
+
+<p align="center">
+  <a href="https://distribird.streamlit.app"><img src="https://img.shields.io/badge/Try_it_now-distribird.streamlit.app-2d6a4f?style=for-the-badge" alt="Try it now"></a>
+</p>
+
+## Why Distribird?
+
+Bayesian calibration requires informative priors, but building them from literature is tedious.
+Researchers default to flat priors, losing valuable domain knowledge.
+Distribird closes that gap: **describe your parameter, get a defensible prior in seconds.**
+
+## Architecture
+
+```
+                        ┌──────────────────────────────┐
+                        │        LangGraph DAG         │
+                        └──────────────────────────────┘
+
+START ─► Enrich ─► QueryGen ─► Search ─► RelevanceJudge ──┬► CrossEnrich ───┐
+                                 ▲                        │                 │
+                                 │                        └► FetchFulltext ◄┘
+                          RefineSearch                            │
+                                 ▲                            Extract
+                                 │                                │
+                                 │   RefineExtraction ◄─── QualityGate
+                                 │         │                │     │
+                                 │         └────────────────┘     │
+                                 │                                ▼
+                                 └─────────────────────────  Synthesize ─► END
+```
+
+**Multi-agent search** &mdash; Semantic Scholar, OpenAlex, and LLM deep-research agents run concurrently; a moderator LLM selects the best papers via deliberation.
+
+**Relevance scoring** &mdash; An LLM-based relevance judge scores each paper before extraction. When multiple high-relevance papers are found, the pipeline routes through cross-enrichment (citation snowballing + follow-up queries) to discover additional sources.
+
+**Feedback loops** &mdash; A quality gate inspects extraction results and can trigger search refinement (new queries) or extraction refinement (web-assisted re-extraction) before falling through to synthesis.
+
+**Budget-bounded** &mdash; `IterationBudget` caps every loop to guarantee termination.
+
+**Live progress** &mdash; The pipeline streams node-by-node updates to the UI, showing which step is running, paper/value counts, and per-parameter progress bars.
+
+## Quickstart
+
+### Install
+
+```bash
+pip install distribird
+```
+
+<details>
+<summary><strong>Development install</strong></summary>
+
+```bash
+git clone https://github.com/HUN-REN-AI1Science/Distribird.git
+cd distribird
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest                     # 148 tests, all passing
+```
+</details>
+
+### Configure
+
+Distribird reads configuration from environment variables (prefix `DISTRIBIRD_`) or a `.env` file in the project root.
+
+```bash
+# .env (or export these in your shell)
+DISTRIBIRD_LLM_BASE_URL="http://localhost:4000"   # any OpenAI-compatible endpoint
+DISTRIBIRD_LLM_API_KEY="your-key"
+DISTRIBIRD_LLM_MODEL="gpt-4o"
+DISTRIBIRD_SEMANTIC_SCHOLAR_API_KEY=""            # optional, increases rate limits
+```
+
+**Sidebar behaviour in the Streamlit UI:**
+
+- Settings provided in `.env` are used automatically — no manual input needed.
+- Settings **not** provided in `.env` appear as required fields in the sidebar; the user must fill them in before generation can start.
+- An **"Override configured settings"** toggle lets users temporarily replace `.env` values without editing the file.
+- Literature source toggles (Semantic Scholar, OpenAlex, LLM Web Search, LLM Deep Research) are always visible and control which connection fields are required.
+
+### Use
+
+**Python**
+
+```python
+import asyncio
+from distribird.agent.pipeline import run_parameter
+from distribird.models import ParameterInput, ConstraintSpec
+
+result = asyncio.run(run_parameter(
+    ParameterInput(
+        name="max_lai",
+        description="Maximum leaf area index of maize",
+        unit="m2/m2",
+        domain_context="Biome-BGCMuSo maize crop modeling",
+        constraints=ConstraintSpec(lower_bound=0, upper_bound=12),
+    )
+))
+
+print(result.prior.display_name())   # truncated_normal(mu=5.2, sigma=1.5, a=0, b=12)
+print(result.prior.n_sources)        # 6
+print(result.prior.confidence.value) # high
+```
+
+**REST API**
+
+```bash
+distribird-api                          # starts on :8000
+
+curl -u demo:distribird2026 -X POST http://localhost:8000/api/v1/parameter \
+  -H "Content-Type: application/json" \
+  -d '{"name":"max_lai","description":"Maximum leaf area index of maize","unit":"m2/m2"}'
+```
+
+**Streamlit UI**
+
+Try the hosted version at **[distribird.streamlit.app](https://distribird.streamlit.app)**, or run locally:
+
+```bash
+streamlit run src/distribird/ui/app.py
+```
+
+## Prior Fitting Strategy
+
+| Evidence | Method | Confidence |
+|---|---|---|
+| 5+ values | AIC across Normal, Truncated Normal, Gamma, Log-Normal, Beta | **High** |
+| 2 &ndash; 4 values | Moment matching with widened &sigma; | Medium |
+| 1 value | Wide Normal centered on value | Low |
+| 0 values | Jeffreys / wide uninformative prior | None |
+
+All fitted distributions respect user-specified physical constraints (bounds).
+
+## Export Formats
+
+```python
+from distribird.export.json_export import export_json
+from distribird.export.r_export import export_r
+from distribird.export.python_export import export_python
+```
+
+| Format | Output |
+|---|---|
+| **JSON** | Parameter name, family, params, citations, confidence |
+| **R** | Executable R script with distribution calls |
+| **Python** | `scipy.stats` code ready for MCMC samplers |
+
+## Demo
+
+A complete worked example using five Biome-BGCMuSo maize parameters:
+
+```bash
+python examples/maize_bgcmuso/demo.py
+```
+
+## Testing
+
+```bash
+pytest                 # 148 tests
+ruff check src/ tests/ # lint
+mypy src/distribird/      # type checking (strict)
+```