litplan 0.0.1__tar.gz

litplan-0.0.1/.dockerignore

@@ -0,0 +1,9 @@
+.venv
+.env
+__pycache__
+*.pyc
+.git
+.pytest_cache
+.ruff_cache
+.mypy_cache
+runs

litplan-0.0.1/.env.example

@@ -0,0 +1,71 @@
+# Litplan — copy to `.env` locally (never commit `.env`).
+# API keys and tokens MUST come from the environment (or your secret store),
+# never from committed prompts, fixtures, or application source.
+
+# --- LLM (provider-agnostic factory; see README "Configuration & secrets") ---
+
+# Selects which adapter the factory uses. Code default when unset is `gemini` (needs GOOGLE_API_KEY).
+# Supported: stub, gemini, openai, anthropic, grok (xAI OpenAI-compatible endpoint).
+# Use `stub` in this file for offline copy-paste until you add a key.
+LITPLAN_LLM_PROVIDER=stub
+
+# Model id passed to the active provider. Leave empty to use the built-in default for that provider
+# (e.g. Gemini: gemini-3.1-flash-lite-preview, OpenAI: gpt-4.1, Anthropic: claude-sonnet-4-20250514, Grok: grok-3-mini).
+LITPLAN_LLM_MODEL=
+
+# --- Keys (set only for the provider you use) ---
+
+# gemini: Google AI Studio / Gemini API. Either name works (GOOGLE_API_KEY, else GEMINI_API_KEY).
+# GOOGLE_API_KEY=
+# GEMINI_API_KEY=
+
+# openai: Chat Completions API (OPENAI_API_KEY).
+# OPENAI_API_KEY=
+
+# anthropic: Messages API (ANTHROPIC_API_KEY).
+# ANTHROPIC_API_KEY=
+
+# grok: xAI OpenAI-compatible API (XAI_API_KEY). Optional override for the base URL (default https://api.x.ai/v1).
+# XAI_API_KEY=
+# LITPLAN_XAI_BASE_URL=
+
+# --- GROBID (PDF → TEI; run the official container, then point the app at it) ---
+
+# Base URL only (no trailing path). Example: http://127.0.0.1:8070
+# LITPLAN_GROBID_URL=http://127.0.0.1:8070
+
+# Optional digest/tag of the GROBID image used for this parse (manifest / reproducibility).
+# Pin matches docker-compose.grobid.yml (CRF-only; avoid *-full* unless you intend the ~8 GB image).
+# LITPLAN_GROBID_IMAGE_REF=grobid/grobid:0.8.2.1-crf
+
+# Connect vs read/write timeouts (seconds). Full-text can be slow on large PDFs.
+# LITPLAN_GROBID_CONNECT_TIMEOUT_S=30
+# LITPLAN_GROBID_TIMEOUT_S=300
+
+# Retries for transient failures (timeouts, connection errors, 5xx). Total attempts = 1 + this value.
+# LITPLAN_GROBID_MAX_RETRIES=2
+
+# Base seconds for exponential backoff between retries (0 = immediate retry).
+# LITPLAN_GROBID_RETRY_BACKOFF_BASE_S=1
+
+# --- Chunking (DocumentIR → list[DocumentChunk]; see docs/DEVS_README.md) ---
+
+# Max estimated tokens per chunk (rough count; default_token_count in chunking.py).
+# LITPLAN_CHUNK_MAX_TOKENS=512
+
+# Token overlap carried into the next chunk (default 0).
+# LITPLAN_CHUNK_OVERLAP_TOKENS=0
+
+# If true, do not pack segments from different sections into one chunk (default true).
+# LITPLAN_CHUNK_RESPECT_SECTION_BOUNDARIES=true
+
+# --- Prefect node chaos (T6.4; dev / simulation only) ---
+
+# Integer seed enables simulated latency + random task failures (see README "Prefect execution & chaos").
+# LITPLAN_CHAOS_SEED=1
+
+# Optional: failure probability [0, 1], default 0.2
+# LITPLAN_CHAOS_FAILURE_PROB=0.2
+
+# Optional: max sleep ms before failure roll, default 250 (0 = no sleep)
+# LITPLAN_CHAOS_LATENCY_MAX_MS=250

litplan-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  pytest:
+    name: Pytest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-suffix: ci-pytest
+
+      - name: Sync project with dev dependencies
+        run: uv sync --frozen --group dev
+
+      - name: Run pytest
+        run: uv run pytest
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-suffix: ci-build
+
+      - name: Build source and wheel distributions
+        run: uv build
+
+  migrations:
+    name: Alembic smoke
+    runs-on: ubuntu-latest
+    env:
+      LITPLAN_HOME: ${{ github.workspace }}/.litplan-home-ci
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-suffix: ci-migrations
+
+      - name: Sync project runtime dependencies
+        run: uv sync --frozen
+
+      - name: Upgrade database to head
+        run: uv run alembic upgrade head
+
+      - name: Verify SQLite database was created
+        run: test -f "${LITPLAN_HOME}/runs/litplan.db"

litplan-0.0.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,39 @@
+# Publish to PyPI via Trusted Publishing (OIDC). Trigger: push a version tag only (e.g. v0.0.1).
+# Configure the publisher on PyPI to match this repo, workflow file, and optional environment:
+# https://docs.pypi.org/trusted-publishers/using-a-publisher/#github-actions
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    # Strongly recommended by PyPI; must match the "environment" in your PyPI trusted publisher config.
+    environment: pypi
+    permissions:
+      # Required for Trusted Publishing (OIDC).
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build source and wheel distributions
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

litplan-0.0.1/.github/workflows/workflowgen-engines.yml

@@ -0,0 +1,100 @@
+name: Workflowgen engine integration
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  workflowgen:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        engine: [snakemake, nextflow, airflow]
+    steps:
+      - uses: actions/checkout@v6
+
+      # Nextflow uses Java plus the upstream installer; other legs use the project env via uv.
+      - name: Install uv
+        if: matrix.engine != 'nextflow'
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-suffix: workflowgen-${{ matrix.engine }}
+
+      - name: Sync Python env (Snakemake only)
+        if: matrix.engine == 'snakemake'
+        run: uv sync --group dev
+
+      - name: Set up Java (Nextflow)
+        if: matrix.engine == 'nextflow'
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: "17"
+
+      - name: Install Nextflow
+        if: matrix.engine == 'nextflow'
+        run: |
+          set -euo pipefail
+          mkdir -p "${HOME}/.local/bin"
+          curl -fsSL https://get.nextflow.io | bash
+          test -f nextflow
+          mv nextflow "${HOME}/.local/bin/nextflow"
+          chmod +x "${HOME}/.local/bin/nextflow"
+          echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"
+
+      - name: Snakemake dry-run on golden bundles
+        if: matrix.engine == 'snakemake'
+        run: |
+          set -euo pipefail
+          ROOT="${GITHUB_WORKSPACE}"
+          export PROJECT_HOME="${ROOT}"
+          export RUN_ID="ci-workflowgen"
+          mkdir -p "${ROOT}/runs/${RUN_ID}/workspace"
+
+          for name in empty linear_chain diamond parallel_roots edges_unsorted_in_file artifact_chain_linear artifact_merge_diamond artifact_fork_selective; do
+            TMP="$(mktemp -d)"
+            cp "${ROOT}/fixtures/workflowgen/snakemake_golden/${name}.Snakefile" "${TMP}/Snakefile"
+            envsubst < "${ROOT}/fixtures/workflowgen/snakemake_golden/${name}.config.yaml" > "${TMP}/config.yaml"
+            echo "=== snakemake -n: ${name} ==="
+            cd "${ROOT}"
+            uv run snakemake -n --snakefile "${TMP}/Snakefile" --configfile "${TMP}/config.yaml"
+          done
+
+      - name: Nextflow config on golden bundles
+        if: matrix.engine == 'nextflow'
+        env:
+          GITHUB_WORKSPACE: ${{ github.workspace }}
+        run: |
+          set -euo pipefail
+          command -v nextflow >/dev/null 2>&1
+          ROOT="${GITHUB_WORKSPACE}"
+          for name in empty linear_chain diamond parallel_roots edges_unsorted_in_file; do
+            TMP="$(mktemp -d)"
+            cp "${ROOT}/fixtures/workflowgen/nextflow_golden/${name}.main.nf" "${TMP}/main.nf"
+            cp "${ROOT}/fixtures/workflowgen/nextflow_golden/${name}.nextflow.config" "${TMP}/nextflow.config"
+            echo "=== nextflow config: ${name} ==="
+            cd "${TMP}"
+            nextflow config .
+          done
+
+      - name: Airflow DagBag on golden DAG files
+        if: matrix.engine == 'airflow'
+        run: |
+          set -euo pipefail
+          ROOT="${GITHUB_WORKSPACE}"
+          for name in empty linear_chain diamond parallel_roots edges_unsorted_in_file; do
+            TMP="$(mktemp -d)"
+            cp "${ROOT}/fixtures/workflowgen/airflow_golden/${name}.litplan_dag.py" "${TMP}/litplan_dag.py"
+            echo "=== airflow DagBag: ${name} ==="
+            cd "${ROOT}"
+            uv run --with 'apache-airflow>=2.8,<3' python -c \
+              'import sys; from pathlib import Path; from airflow.models import DagBag; f=Path(sys.argv[1]); db=DagBag(dag_folder=str(f), include_examples=False); assert not db.import_errors, db.import_errors; assert db.dags, "no DAGs"; print("ok", len(db.dags))' \
+              "${TMP}"
+          done

litplan-0.0.1/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.env
+runs/
+__pycache__/
+.ruff_cache/
+.pytest_cache/
+*.py[cod]
+dev
+evals/t8_tool_use/report.json
+.DS_Store
+manual-work

litplan-0.0.1/Dockerfile

@@ -0,0 +1,23 @@
+# Litplan — Python 3.11 + uv, dependencies from uv.lock.
+# Add apt packages only if a wheel build fails for a dependency.
+FROM python:3.11-slim-bookworm
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV UV_LINK_MODE=copy
+
+WORKDIR /app
+
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:${PATH}"
+
+COPY pyproject.toml uv.lock README.md ./
+COPY src ./src
+
+RUN uv sync --frozen --group dev
+
+COPY tests ./tests
+
+CMD ["/bin/bash"]

litplan-0.0.1/LICENSE

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

litplan-0.0.1/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: litplan
+Version: 0.0.1
+Summary: Litplan: ingest papers, compile pipeline IR, run multi-agent workflows.
+License: MIT License
+        
+        Copyright (c) 2026 litplan
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.18.4
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: langchain-anthropic>=0.3.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langchain-google-genai>=2.0.0
+Requires-Dist: langchain-openai>=0.3.0
+Requires-Dist: langgraph-checkpoint-sqlite>=3.0.3
+Requires-Dist: langgraph>=1.1.3
+Requires-Dist: lxml>=6.0.2
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.40.0
+Requires-Dist: opentelemetry-sdk>=1.40.0
+Requires-Dist: prefect>=3.0
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sqlalchemy>=2.0.49
+Requires-Dist: sqlite-vec>=0.1.6
+Description-Content-Type: text/markdown
+
+# Litplan
+
+Litplan turns a research paper into structured document data, a checked and versioned `PipelineSpec`, optional approval records, and either a reference execution path or workflow files for your own runtime. It is the governed-plan layer, not a replacement for Snakemake, Nextflow, Airflow, or your HPC stack.
+
+## Start Here
+
+### Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
+- Docker, only if you want live PDF ingest via GROBID
+- An LLM API key, only if you want live goal-driven planning
+
+Run these commands from the repository root:
+
+```bash
+uv sync
+cp .env.example .env
+uv run litplan environment
+uv run litplan ingest fixtures/tei/structural_minimal.tei.xml \
+  --parser-route tei_fixture_replay \
+  --document-ir
+```
+
+What to expect:
+
+- `uv sync` installs the package and CLI from `uv.lock`.
+- `cp .env.example .env` gives you a local config file; it defaults to `LITPLAN_LLM_PROVIDER=stub`, so this path stays offline.
+- `uv run litplan environment` prints JSON hints about paths and config resolution.
+- The offline `ingest` command should return JSON with `"ok": true` and inline `DocumentIR` output.
+
+## Choose Your Path
+
+
+| Path            | Use it when                                                      | Needs                                             | First step                                                          |
+| --------------- | ---------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
+| Offline demo    | You want a first successful run with no external services        | `uv`                                              | Run the `tei_fixture_replay` ingest command above                   |
+| Live PDF ingest | You want to parse a real PDF through GROBID                      | Docker + GROBID                                   | `docker compose -f docker-compose.grobid.yml up -d`                 |
+| LLM planning    | You want `plan-compile` to draft a pipeline from a goal          | A real provider in `.env` plus a matching API key | Set `LITPLAN_LLM_PROVIDER` and provider key in `.env`               |
+| Workflow export | You want Snakemake, Nextflow, or Airflow files from a stored run | A persisted run in the local DB                   | Compile with `--create-run`, then `approve`, then `export-workflow` |
+
+
+## Fastest Successful Runs
+
+### 1. Offline ingest demo
+
+This is the fastest self-contained path and works in a fresh checkout after `uv sync`.
+
+```bash
+uv run litplan ingest fixtures/tei/structural_minimal.tei.xml \
+  --parser-route tei_fixture_replay \
+  --document-ir
+```
+
+Expected outcome:
+
+- You should get JSON output with `"ok": true`.
+- You should get inline `DocumentIR` JSON.
+- No Docker, database, or API key is required.
+
+### 2. Persist a local run
+
+Use this when you want approvals, execution, status, or export commands to work against the local SQLite store.
+
+```bash
+export LITPLAN_HOME="$(pwd)/.litplan-home"
+uv run alembic upgrade head
+RUN_ID="examples-linear-chain-run-$(date +%s)"
+uv run litplan compile fixtures/workflowgen/pipeline_specs/linear_chain.json \
+  --pipeline-id examples.linear_chain \
+  --lockfile uv.lock \
+  --run-id "$RUN_ID" \
+  --create-run
+```
+
+Expected outcome:
+
+- This creates `.litplan-home/` and initializes the SQLite schema there.
+- The compile command should return `"ok": true`.
+- The run and compiled revision are now persisted for later `approve`, `run-status`, `execute`, and export commands.
+
+### 3. Live PDF ingest with GROBID
+
+If PDF ingest is the feature you care about, this is the shortest working setup.
+
+Start GROBID:
+
+```bash
+docker compose -f docker-compose.grobid.yml up -d
+curl -fsSL http://127.0.0.1:8070/api/isalive
+```
+
+Then set `LITPLAN_GROBID_URL=http://127.0.0.1:8070` in `.env` and run:
+
+```bash
+uv run litplan ingest \
+  fixtures/papers/pdf/batatia-2022-mace-force-fields-arxiv-2206.07697v2.pdf \
+  --document-ir
+```
+
+Expected outcome:
+
+- The health check should print an `alive` response from GROBID.
+- The ingest command should return `"ok": true`.
+- You should get parsed document metadata and, with `--document-ir`, inline `DocumentIR` JSON for the PDF.
+
+### 4. Live LLM planning
+
+For this path, change `.env` from the default `stub` provider to a real provider and add its key. Example:
+
+```bash
+LITPLAN_LLM_PROVIDER=gemini
+GOOGLE_API_KEY=your-real-key
+```
+
+Then run:
+
+```bash
+uv run litplan plan-compile "build linear noop pipeline" \
+  --pipeline-id examples.goal_demo \
+  --lockfile uv.lock \
+  --expanded-spec
+```
+
+Expected outcome:
+
+- The command should return `"ok": true` when the provider is configured correctly.
+- You should get a compiled pipeline result and expanded spec JSON.
+- Use `compile` instead of `plan-compile` when you already have full `PipelineSpec` JSON and do not want an LLM involved.
+
+### 5. Workflow export
+
+Once you have a persisted run, you can approve it and generate engine-native workflow files.
+
+```bash
+uv run litplan approve "$RUN_ID"
+uv run litplan export-workflow "$RUN_ID" snakemake ./tmp/workflow-out
+```
+
+Expected outcome:
+
+- `approve` records a non-pending run status for `RUN_ID`.
+- `export-workflow` writes files under `./tmp/workflow-out`.
+- You can switch `snakemake` to `nextflow` or `airflow`.
+
+## Main Commands
+
+
+| Command                       | What it does                                                              |
+| ----------------------------- | ------------------------------------------------------------------------- |
+| `litplan ingest`              | Parse a PDF or TEI file into `DocumentIR`; can include inline JSON output |
+| `litplan compile`             | Validate and compile a `PipelineSpec` JSON input                          |
+| `litplan plan-compile`        | Use a goal-driven planner, then run the same compiler                     |
+| `litplan approve`             | Record approval or other status transitions for a run                     |
+| `litplan execute`             | Execute a persisted approved run through the reference Prefect path       |
+| `litplan run-status`          | Show unified run, planning, and execution status                          |
+| `litplan export-audit-bundle` | Write a reproducibility-oriented bundle for a run                         |
+| `litplan export-workflow`     | Generate Snakemake, Nextflow, or Airflow files from a stored revision     |
+| `litplan environment`         | Print non-secret environment and path hints                               |
+
+
+Run `uv run litplan --help` for the full CLI and option details.
+
+## Project Surfaces
+
+- CLI: `uv run litplan`
+- MCP server: `uv run litplan-mcp`
+- Python library: `import litplan`
+- Streamlit UI (optional): `uv run streamlit run src/litplan/ui/plan_draft_app.py`
+
+The CLI and MCP server call the same shared JSON tool layer, so they expose the same core operations.
+
+### Streamlit UI
+
+The optional Streamlit app is a browser UI on top of the same SQLite project database. You can edit **PlanDraft** text and compare it to a prior draft, append **approval** records, append **hallucination** flags with chunk provenance, and load **unified run status** (LangGraph checkpoints, run timeline, execute-phase node checkpoints, OpenTelemetry hints). Ingest, compile, plan-compile, approve, execute, export, and other pipeline steps still run from the CLI or MCP; the UI does not replace those tools.
+
+![Litplan Streamlit PlanDraft UI](docs/assets/litplan_streamlit_ui.png)
+
+From the repository root, after `uv sync` and `uv run alembic upgrade head` for your chosen `LITPLAN_HOME`:
+
+```bash
+export LITPLAN_HOME="$(pwd)/.litplan-home"
+uv run streamlit run src/litplan/ui/plan_draft_app.py
+```
+
+For a full step-by-step (including diff panels, approvals, flags, and run explorer), see **Part 3** in [MANUAL_CLI_MCP_UI_WORKFLOW.md](docs/manual/MANUAL_CLI_MCP_UI_WORKFLOW.md).
+
+## Examples
+
+Library-first examples live in `examples/`:
+
+- `examples/paper_repro_sketch_tei.py`: saved TEI -> `DocumentIR` -> chunking -> hand-authored `PipelineSpec` -> compile
+- `examples/paper_repro_sketch_pdf.py`: PDF path -> live GROBID ingest -> the same chunk/plan/compile flow
+
+Run them from the repository root:
+
+```bash
+uv run python examples/paper_repro_sketch_tei.py
+uv run python examples/paper_repro_sketch_pdf.py \
+  fixtures/papers/pdf/batatia-2022-mace-force-fields-arxiv-2206.07697v2.pdf
+```
+
+## What To Expect
+
+- The package version is **0.0.1** (see `pyproject.toml`); pre-1.0 semver releases may still evolve public APIs.
+- Offline and stub-backed flows remain supported for local development and tests.
+- The bundled `execute` path demonstrates orchestration, retries, checkpoints, and bookkeeping; use your own workflow engine or cluster stack for production-scale execution.
+
+## Where To Go Next
+
+- [Product scenarios, no-technical overview](docs/PRODUCT_SCENARIOS.md)
+- [Full configuration, env vars, architecture, and command reference](docs/DEVS_README.md)
+- [End-to-end operator walkthrough across CLI, MCP, and UI](docs/manual/MANUAL_CLI_MCP_UI_WORKFLOW.md)
+- [Workflow export details, kind maps, and safety model](docs/workflowgen/)
+- [Paper fixture notes](fixtures/papers/FIXTURES.md)