openodke 0.1.0__tar.gz

openodke-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,29 @@
+name: Bug report
+description: Something behaves differently from what it says it does.
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you expected, and what you got instead.
+    validations: {required: true}
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction
+      description: The smallest snippet that shows it. An ontology fragment helps more than a description of one.
+      render: python
+    validations: {required: true}
+  - type: input
+    id: version
+    attributes:
+      label: openodke version
+      placeholder: "0.0.1"
+    validations: {required: true}
+  - type: input
+    id: model
+    attributes:
+      label: Model configuration
+      description: The ModelRoles or model string, if the failure involves a model call.
+      placeholder: "ollama/llama3.1"

openodke-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,19 @@
+name: Feature request
+description: Something the library should be able to do and cannot.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to do? Describe the situation, not the solution you have in mind.
+    validations: {required: true}
+  - type: textarea
+    id: shape
+    attributes:
+      label: What the API might look like
+      render: python
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you are doing instead today

openodke-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## What this changes
+
+<!-- One paragraph. What is different after this merges? -->
+
+## Why
+
+<!-- The reason, not the restatement. If it changes a decision in DECISIONS.md,
+     update that file in this PR. -->
+
+## Checklist
+
+- [ ] `./scripts/verify.sh` passes locally
+- [ ] New behaviour has a test that would fail without the change
+- [ ] Public API changes are reflected in the README
+- [ ] A design call that future-me would question is recorded in `DECISIONS.md`

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

@@ -0,0 +1,129 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    name: verify (python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      # Both legs always report. A break on one version should not hide the
+      # result on another, which is the whole reason for testing three.
+      fail-fast: false
+      matrix:
+        # The range pyproject declares: requires-python = ">=3.11,<3.14".
+        # Advertising support for a version nothing runs is a claim, not a fact.
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      # Every check lives in scripts/verify.sh so that what runs here and what a
+      # contributor runs locally cannot drift apart. See that file for the list.
+      - name: Verify
+        run: ./scripts/verify.sh
+        env:
+          UV_PYTHON: ${{ matrix.python }}
+
+  # The tests that talk to a real Neo4j skip everywhere else: verify.sh refuses
+  # to run with NEO4J_URI or NEO4J_PASSWORD set, because the suite must never
+  # write to somebody's real graph. So they get their own job, a database that
+  # lives exactly as long as the job does, and no verify.sh. What a recording
+  # driver cannot check — that the MERGEs really are idempotent, that the DDL
+  # is accepted, that a check query finds a real violation — is checked here.
+  neo4j-live:
+    name: neo4j live tests (python 3.12, neo4j 5.26)
+    runs-on: ubuntu-latest
+    services:
+      neo4j:
+        # Relationship uniqueness constraints need 5.7 or later; Community,
+        # because the constrainer emits nothing Enterprise-only.
+        image: neo4j:5.26-community
+        env:
+          # A throwaway password for a container that dies with the job,
+          # derived from the run id so no fixed credential sits in the repo.
+          NEO4J_AUTH: neo4j/ci-${{ github.run_id }}
+        ports:
+          - 7687:7687
+        # Healthy means bolt answers a query with these credentials.
+        options: >-
+          --health-cmd "cypher-shell -u neo4j -p ci-${{ github.run_id }} 'RETURN 1'"
+          --health-interval 5s
+          --health-timeout 20s
+          --health-retries 30
+          --health-start-period 20s
+    env:
+      UV_PYTHON: "3.12"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install
+        run: uv sync --locked
+
+      # Only these two steps see the connection settings. Set any wider and the
+      # credential check in verify.sh would be right to refuse.
+      - name: Wait for bolt on 7687
+        env:
+          NEO4J_URI: bolt://localhost:7687
+          NEO4J_USER: neo4j
+          NEO4J_PASSWORD: ci-${{ github.run_id }}
+        run: |
+          uv run python - <<'EOF'
+          import os, time
+          from neo4j import GraphDatabase
+
+          auth = (os.environ["NEO4J_USER"], os.environ["NEO4J_PASSWORD"])
+          deadline = time.monotonic() + 120
+          while True:
+              try:
+                  with GraphDatabase.driver(os.environ["NEO4J_URI"], auth=auth) as driver:
+                      driver.verify_connectivity()
+                      print("bolt is up:", driver.get_server_info().agent)
+                  break
+              except Exception as exc:
+                  if time.monotonic() > deadline:
+                      raise
+                  print(f"waiting for bolt: {exc}")
+                  time.sleep(2)
+          EOF
+
+      # `-k live_neo4j` selects exactly the tests that need a server. A skipped
+      # test is a green tick that proved nothing, so the step then reads the
+      # JUnit report and fails unless at least one ran and none skipped.
+      - name: Live Neo4j tests
+        env:
+          NEO4J_URI: bolt://localhost:7687
+          NEO4J_USER: neo4j
+          NEO4J_PASSWORD: ci-${{ github.run_id }}
+        run: |
+          uv run pytest tests/test_neo4j_sink.py tests/test_neo4j_constraints.py tests/test_bulk_sinks.py tests/test_ontology_neo4j.py tests/test_e2e.py \
+            -k live_neo4j -rA --junitxml=live-neo4j.xml
+          python3 - <<'EOF'
+          import xml.etree.ElementTree as ET
+
+          root = ET.parse("live-neo4j.xml").getroot()
+          suite = root if root.tag == "testsuite" else root.find("testsuite")
+          tests, skipped = int(suite.get("tests")), int(suite.get("skipped"))
+          failed = int(suite.get("failures")) + int(suite.get("errors"))
+          ran = tests - skipped
+          print(f"live neo4j tests: {tests} selected, {ran} ran, {skipped} skipped, {failed} failed")
+          if ran < 1 or skipped or failed:
+              raise SystemExit("the live Neo4j tests must run, not skip")
+          EOF

openodke-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,78 @@
+# The documentation site, built from docs/ and mkdocs.yml.
+#
+# A pull request that touches what the site is built from builds it with
+# --strict, so a broken link, a missing page or a heading that moved fails the
+# PR. Only main deploys, to https://deepskandpal.github.io/odke/, through the
+# github-pages environment. The examples on the pages are run by
+# tests/test_docs_examples.py in the ci workflow, not here.
+
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - "DECISIONS.md"          # rendered into the site
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - "DECISIONS.md"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # A newer push supersedes a PR build; a deploy already running is let finish.
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      # Only the docs group: the site renders markdown and does not import the
+      # package, so it needs neither the package nor its extras to build.
+      - name: Build
+        run: uv run --locked --only-group docs mkdocs build --strict
+        env:
+          UV_PYTHON: "3.12"
+
+      - name: Upload the site
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

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

@@ -0,0 +1,123 @@
+# Publishing to PyPI, with no credential anywhere in this repository.
+#
+# Trusted Publishing (OIDC): PyPI is configured to trust this exact repository,
+# workflow filename and environment, and GitHub mints a short-lived token per
+# run. There is no API token to create, share, paste into a secret, rotate, or
+# leak. If this file is renamed, or the environment below changes, PyPI stops
+# trusting it and the upload fails closed.
+#
+# The verify job runs the same checks that guard every push, on every supported
+# interpreter, before anything is uploaded. A release that skipped the checks
+# would defeat the point of having them.
+
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        required: true
+        default: testpypi
+        type: choice
+        options: [testpypi, pypi]
+
+jobs:
+  verify:
+    name: verify (python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: ./scripts/verify.sh
+        env:
+          UV_PYTHON: ${{ matrix.python }}
+
+  build:
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      # The tag is the source of truth for the version. A tag that disagrees
+      # with pyproject.toml means one of the two is a typo, and guessing which
+      # is how a wrong version reaches PyPI permanently: uploads cannot be
+      # replaced, only yanked.
+      - name: Tag matches pyproject version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          if [ "$tag" != "$pkg" ]; then
+            echo "tag v$tag does not match pyproject version $pkg" >&2
+            exit 1
+          fi
+          echo "v$tag matches pyproject"
+
+      - run: uv build
+
+      # Catches the metadata problems that make a page look broken on PyPI,
+      # before the upload rather than after it.
+      - name: Check the distribution metadata
+        run: uv run --isolated --no-project --with twine twine check --strict dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write          # the whole credential story: a short-lived OIDC token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    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
+
+  github-release:
+    needs: pypi
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes

openodke-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.hypothesis/
+.coverage
+htmlcov/
+site/
+.env
+.DS_Store
+# What `odke run` writes when the examples are run in place.
+examples/e2e/out/

openodke-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

openodke-0.1.0/CHANGELOG.md

@@ -0,0 +1,201 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses
+[semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-09-14
+
+The v0.1 milestones now on `main`: the data model (M0), ontology I/O (M1),
+loaders and extraction (M2), grounding and corroboration (M3), the Neo4j sink and
+`odke run` (M4), and evaluation against your own labels (M6). Not yet on PyPI:
+the release (M7) waits on Trusted Publishing.
+
+### Added
+
+#### M0 — Data model (#60)
+
+Every change here is to a frozen type, which is why it landed before anything
+was serialised. Two of them fix live correctness bugs.
+
+- `Fact.polarity` (`Polarity`: asserted / denied / partial), and it is part of
+  `Fact.signature`. A denial no longer merges with its own contradiction. (#47)
+- Qualifier identity semantics. `Predicate.qualifiers` maps each key to a
+  `Qualifier(identity=...)`; `Ontology.identity_keys()` and `Fact.identity_keys`
+  carry the identity-bearing keys onto the fact, and `signature` includes them,
+  sorted. Reconcilable qualifiers stay out, as before. (#48)
+- `EntityLink` (`LinkKind`: SAME_AS / SIMILAR / DIFFERENT, with `score`,
+  `evidence` and a `reason` naming the identifier that disagreed) and
+  `KnowledgeGraph.links`, so resolution is never destructive. (#49)
+- `Fact.valid_from` / `valid_to` — the valid clock, alongside `retrieved_at`'s
+  transaction clock. Neither is in the signature. (#50)
+- `Resolution` and `Entity.resolution` — how the key was decided: by the caller,
+  an external id, or a named linker with a score. (#51)
+- `Chunk`, `RouteVerdict` and the `Router` protocol; the default passes every
+  chunk. (#52)
+- `openodke.stages`: thirteen stage protocols — `Loader`, `Chunker`, `Router`,
+  `Extractor`, `Grounder`, `Normalizer`, `Resolver`, `Corroborator`, `Scorer`,
+  `Validator`, `Sink`, `Constrainer`, `Inferrer` — each with a pass-through
+  default, plus `ValidationVerdict`. (#53)
+- `PlatformProfile` (declared on a sink), `Delegated(to=...)` (a pass-through
+  that satisfies every stage protocol and stamps provenance), and
+  `DoubleStageWarning`, raised once when a stage is configured in openodke and the
+  sink's platform does it too. Warned, never refused. (#59)
+
+#### M1 — Ontology I/O & validation (#63)
+
+- `Ontology.from_dict`, `from_json` and `from_yaml`. A failed load raises
+  `OntologyLoadError` with one line per problem: the dotted path to the key,
+  what was found there, a did-you-mean for a misspelt key, and a line and column
+  for a syntax error. `strict=True` also validates. PyYAML is imported lazily,
+  behind the new `[yaml]` extra.
+- `Ontology.from_pydantic(*models)`: models become entity types, fields become
+  predicates, a field typed as another model is an edge. Adds
+  `Predicate.required`.
+- `Ontology.validate()`, returning `Diagnostic`s and never raising: unknown
+  ranges, parents and keys, unreachable predicates, duplicate aliases, name
+  mismatches and inheritance cycles, each with the exact path.
+- `Ontology.diff()`, marking every change breaking or compatible, and the
+  `odke ontology validate` and `odke ontology diff [--fail-on-breaking]` commands.
+- `Predicate.cardinality_scope` and `Predicate.scope_keys`: what a single-valued
+  predicate is single *within*, shared by the corroborator and the Neo4j check.
+
+#### M2 — Loaders & extraction (#66)
+
+- `SentenceChunker(max_words, overlap)`: whole sentences, paragraph breaks
+  preferred, `doc.text[start:end] == chunk.text` always. (#6)
+- `TextLoader`, `MarkdownLoader` (the raw file as text, the heading outline with
+  offsets in metadata) and `DirectoryLoader`, reading bytes so CRLF offsets are
+  file offsets. (#7)
+- `CsvLoader`, `TsvLoader`, `JsonLoader`, `JsonlLoader`, `RecordsLoader` and
+  `record_document`: one structured document per record, rendered so a span can
+  point into it. `ParquetLoader` behind the new `[parquet]` extra. (#10)
+- `PatternExtractor` and `RecordMapping`: records, pipe tables and `Key: value`
+  blocks to facts, with no model call. (#11)
+- `LLMExtractor`: ontology snippets in, facts with checked evidence spans out;
+  every drop in `rejections`, every call's usage in `calls`. (#12)
+- `HybridExtractor` and `PathReport`: routed by modality, merged by signature. (#13)
+- `ReplayClient`, `Cassette` and `RecordingClient`: model paths in CI with no key
+  and no network. (#14)
+
+#### M3 — Grounding (#61)
+
+- `check_span`, `SpanStatus` and `SpanGrounder`: an offset that does not resolve
+  to its quote is rejected before any model is asked. (#15)
+- `LLMGrounder`, `render_claim` and `parse_verdict`: one fact, one span, one
+  verdict from the `ground` role; `RecordedClient` for thread-safe replay. (#16)
+- `LLMGrounder.ground_many`, `RetryPolicy` and `is_transient`: a document's facts
+  grounded concurrently, transient errors retried, a failed call left
+  `unchecked` rather than failing the run. (#17)
+
+#### M3 — Normalise, resolve, corroborate, score (#65)
+
+- `ValueNormalizer`: dates, numbers, quantities and name keys to one form each,
+  refusing when unsure and keeping the source spelling. (#18)
+- `NativeResolver`: blocking, strong identifiers, a scored name match, and the
+  disagreement rule — a `DIFFERENT` link naming both identifiers. (#19)
+- `SignatureCorroborator`: merge by signature, `support` as independent sources,
+  contested values ranked on trust × freshness × volume-discounted agreement;
+  losers kept with the reason. (#20)
+- `EvidenceScorer`: confidence from the extractor, the verdict, support and any
+  lost contest, with its inputs kept on the fact. (#21)
+
+#### M4 — Neo4j (#62)
+
+- `Neo4jSink`: batched, idempotent `UNWIND … MERGE` on entity keys and fact
+  signatures, provenance on every fact relationship, literal facts as `:Claim`
+  nodes, `EntityLink`s as relationships. The driver is imported lazily behind
+  `[neo4j]`. (#22)
+- `Neo4jConstrainer`, `Neo4jSink.bootstrap()` and `Neo4jSink.check()`: the
+  ontology compiled into uniqueness constraints and indexes, and a check query
+  per single-valued predicate for what Neo4j cannot enforce. (#23)
+
+#### M6 — Evaluation, bring your own labelled dataset (#64)
+
+- `StageReport`, a JSONL format per stage, fixtures that are not a benchmark, and
+  `odke eval <stage> --labels … [--predictions … | --run …] [--describe]`. (#36)
+- Evaluators for routing (#54), extraction with the four-way error split (#37),
+  grounding and `grounding_ablation` (#55), resolution with B-cubed (#56),
+  calibration with Brier, reliability and ECE (#57), and validation with sink
+  idempotency (`check_idempotency`, `assert_idempotent`) (#58).
+- `CostMeter`, `CostReport` and `compare_costs`: tokens, USD and latency per
+  stage, with unknown cost kept unknown. (#39)
+
+#### M4 / M6 — The run command, the example, the ablation
+
+- `odke run config.yaml [--dry-run]` and `openodke.run`: the whole pipeline from one
+  YAML or JSON file — inputs and loaders, ontology, model roles with recorded
+  responses and a cost meter, the implementation of each of the thirteen stages
+  by short name or `package.module:Name`, sinks, and `bootstrap`. Every stage's
+  counts are copied into `KnowledgeGraph.stats`, and a document's id is its
+  source path. `examples/run.yaml` comments every key. (#29)
+- `VerdictValidator`: the default gate, refusing `contradicted` and, on request,
+  `not_found`. (#29)
+- `examples/e2e/`: an invented corpus, ontology, recorded responses and configs,
+  run into JSON Lines or Neo4j, with the queries that show provenance, a
+  `DIFFERENT` link and a cardinality check. (#30)
+- `odke eval ablation --config … --labels …` and `openodke.eval.run_ablation`:
+  extraction alone, + grounding, + corroboration over your own labels. (#38)
+- `odke run` short names for the loaders and sinks that landed after its
+  builder: loaders `html`, `pdf` and `docx`; sinks `cypher_file`,
+  `neo4j_admin_csv`, `rdf` and `networkx` (which also writes node-link JSON
+  when given `path`). Options pass through as extra keys. A missing extra is a
+  config error naming it, raised while the config is built and before any sink
+  is opened, and each input's loader is now built then too.
+
+### Changed
+- `odke ontology infer` with no readable documents lists every suffix
+  `DirectoryLoader` reads, taken from its own table, so `.html`, `.pdf` and
+  `.docx` are no longer missing from the hint. The `docs` extra is pypdf and
+  python-docx: beautifulsoup4 and lxml were in it and nothing imported them.
+- The distribution and the import package are now `openodke` (`pip install
+  "openodke[neo4j]"`, `import openodke`); the command is still `odke`, and an
+  `openodke` command runs the same app. The reserved `odke.*` keys, the RDF
+  `odke:` vocabulary and the Neo4j `odke_*` schema names are unchanged. Nothing
+  had been published under the old name, so there is no compatibility shim.
+  (DECISIONS #22)
+- The stage protocols live in `openodke.stages`; `openodke.pipeline` re-exports them.
+  `Extractor` takes one `Chunk` and the ontology; `Grounder` takes one fact and
+  its document and sets the verdict rather than dropping; `Corroborator` returns
+  facts and the pipeline assembles the graph. (#60)
+- `Pipeline.run` chunks and routes before extracting, resolves before
+  corroborating, validates before writing, and reports counts in
+  `KnowledgeGraph.stats`. `Pipeline.constraints()` exposes the constrainer's
+  output for a sink to apply. (#60)
+- `Pipeline.run` grounds a document's candidates together, through
+  `ground_many` when the grounder has it. (#61)
+- No `DoubleStageWarning` for a constrainer whose `platform` matches the sink's
+  profile: it is the store's other half, not a second pass. (#62)
+- `Predicate.qualifiers` is a mapping; a bare list of names is still accepted
+  and every name in it is reconcilable. (#60)
+- `JsonlSink` writes `links.jsonl` and counts links in the manifest. (#60)
+- README rewritten around what runs today, with install from GitHub until the
+  PyPI release. ROADMAP marks M0–M4 and M6 done. (#43)
+
+## [0.0.1] — 2026-09-01
+
+The scaffold. Everything here is the contract later milestones are written
+against, not a preview of the finished library.
+
+### Added
+- Core data model: `Document`, `Span`, `Evidence`, `Entity`, `Fact`,
+  `KnowledgeGraph`, with frozen semantics and character-offset provenance.
+- Ontology compiler: `Ontology`, `EntityType`, `Predicate`, inheritance-aware
+  `predicates_for()`, and cycle-safe `lineage()`.
+- `OntologySnippet` — the ranked, per-type schema fragment from the ODKE+ paper,
+  rendered either as prose or as JSON Schema from one object.
+- Provider-neutral model layer: `LLMClient` protocol, `ModelSpec`, `ModelRoles`,
+  a standard-library OpenAI-compatible client (Ollama, vLLM, LM Studio,
+  llama.cpp, OpenRouter, Groq, Together, DeepSeek, gateways), a litellm adapter
+  for everything else, a `register()` escape hatch, and `ScriptedClient` for
+  offline tests.
+- `Pipeline` and the five stage protocols: `Initiator`, `Retriever`, `Extractor`,
+  `Grounder`, `Corroborator`, plus `Sink`.
+- `JsonlSink`, and the `odke` CLI with `ontology snippet` and `ontology types`.
+- `scripts/verify.sh` — ten checks, run identically in CI and locally.
+- CI on Python 3.11/3.12/3.13; PyPI release via Trusted Publishing.
+
+[Unreleased]: https://github.com/deepskandpal/odke/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/deepskandpal/odke/releases/tag/v0.0.1

openodke-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing
+
+## The whole check is one script
+
+```bash
+git clone https://github.com/deepskandpal/odke && cd odke
+curl -LsSf https://astral.sh/uv/install.sh | sh   # if you don't have uv
+./scripts/verify.sh
+```
+
+Ten steps: credentials, interpreter, lock, lint, format, types, tests, the
+base-install guarantee, the build, and a smoke test of the built wheel in a clean
+environment. CI runs this same script on three interpreters — there is no second
+list of steps to drift out of sync with this one.
+
+## What a good change looks like
+
+- **A test that would fail without it.** Not coverage for its own sake: a test
+  that names the behaviour and would catch its loss.
+- **The reason, in the code.** Comments here explain *why*, not *what*. If you
+  found the reasoning non-obvious, so will the next person.
+- **A `DECISIONS.md` entry** for anything a future contributor would reasonably
+  try to reverse.
+
+## Things worth knowing before you start
+
+- **The base install talks to nothing.** `pip install openodke` must keep working
+  with no provider, no driver and no network. `verify.sh` step 8 enforces it, so
+  a new top-level import of `litellm`, `neo4j` or `rdflib` will fail the build.
+  Import those inside the module that needs them.
+- **No vendor names outside `openodke/llm/`.** Everything else goes through
+  `LLMClient`. A `import anthropic` in the extractor is a bug, not a shortcut.
+- **Tests never touch the network.** Use `ScriptedClient` for model calls and the
+  injected opener for HTTP. Step 1 refuses to run if a live key is in the
+  environment.
+- **Facts are frozen.** Stages return new objects. A stage that mutated one in
+  place would make its own provenance wrong.
+
+## Adding a sink
+
+`Sink` is a `Protocol` — one method, no base class, no registration:
+
+```python
+class MySink:
+    def write(self, kg: KnowledgeGraph) -> None: ...
+```
+
+If it needs a driver, put it behind an extra in `pyproject.toml` and import the
+driver inside the module, not at package level.
+
+## Adding a provider
+
+Most providers need no code: they are either OpenAI-shaped (already covered) or
+supported by litellm (already covered). If yours is genuinely neither, implement
+`LLMClient` and register it:
+
+```python
+from openodke.llm import register
+
+register("myprovider", lambda spec: MyClient(spec))
+```
+
+A new adapter in this repository needs a test proving it normalises to the same
+`Completion` as the others — including `cost_usd is None` when the provider does
+not report cost, rather than `0.0`.