evidence-graph 0.1.1__tar.gz

evidence_graph-0.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,34 @@
+name: Bug report
+description: Something behaves differently from what its docstring or the README says.
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you expected, and what you got instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Minimal reproduction
+      description: >
+        The smallest input that shows the problem. Please use synthetic text — never paste
+        unpublished research, patient data, or anything under an NDA into a public issue.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: "`pip show evidence-graph`, or the commit SHA."
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+    validations:
+      required: true

evidence_graph-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/SciWay-platform/evidence-graph/security/advisories/new
+    about: Report privately through a security advisory. Please do not open a public issue.

evidence_graph-0.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature request
+description: Propose a capability that fits the library's scope.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What you are trying to do that the library makes hard or impossible.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed shape
+      description: Roughly what the API would look like, if you have a view.
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope check
+      description: >
+        The library is deliberately narrow — see [CONTRIBUTING.md](../blob/main/CONTRIBUTING.md#scope).
+      options:
+        - label: This needs no network access, no credentials, and no model at import time.
+        - label: This does not require knowing about users, tenants, or requests.

evidence_graph-0.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## What this changes
+
+<!-- One or two sentences. What behaviour is different after this merges? -->
+
+## Why
+
+<!-- The problem, not the patch. If it fixes an issue, link it. -->
+
+## Checklist
+
+- [ ] Tests cover the change, and `python -m unittest discover -s tests` passes.
+- [ ] `ruff check .` passes.
+- [ ] No new runtime dependency (`python scripts/check_no_runtime_deps.py` passes). If the change
+      needs a model, a network call, or a credential, it is injected through a Protocol rather than
+      imported here — see [CONTRIBUTING.md](../CONTRIBUTING.md#scope).
+- [ ] Nothing secret, private, or customer-identifying is in the diff, including in test fixtures.
+- [ ] If this changes how an edge is asserted or abstained, the reasoning is stated in the PR body
+      and reflected in the docstring.

evidence_graph-0.1.1/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  # The library has no runtime dependencies, so the supply-chain surface that actually exists is
+  # the CI workflows. A stale pinned action is the realistic risk here, not a stale package.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "ci"
+    labels: ["dependencies", "ci"]

evidence_graph-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Least privilege: nothing in this workflow writes to the repository.
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: pip install ruff==0.16.7
+      # `ruff check` only. There is deliberately no `ruff format --check`: this code must stay
+      # diffable against its origin in the SciWay codebase, and a wholesale reformat would make
+      # the first round of review impossible to read.
+      - run: ruff check .
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+        include:
+          # One Windows leg, because the library handles file paths and text encodings and those
+          # are where a "pure stdlib, works everywhere" claim usually turns out to be false.
+          - os: windows-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      # No install step: the library and its tests are standard-library only. If this line ever
+      # needs a `pip install`, the zero-dependency guarantee has been broken — see the job below.
+      - name: Run test suite
+        run: python -m unittest discover -s tests -v
+
+  no-runtime-deps:
+    # The zero-dependency promise is a design constraint (see pyproject.toml), so it gets a test.
+    # Without one it erodes the first time somebody reaches for a convenience library.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python scripts/check_no_runtime_deps.py
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      # Catches a malformed README or bad metadata before it reaches PyPI, where a release
+      # cannot be replaced, only yanked.
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7

evidence_graph-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release
+
+# Publishing a GitHub release uploads that version to PyPI. Trusted Publishing (OIDC) does the
+# upload, so there is no API token anywhere: PyPI accepts it only from this workflow file, in this
+# repository, running in the `pypi` environment, as registered on the project's publishing page.
+# A failed upload is retried with "Re-run failed jobs"; the built files are reused, not rebuilt.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Tag matches the package version
+        # PyPI never lets a version be replaced, only yanked, so a mismatch is caught here.
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "release tag ${GITHUB_REF_NAME} does not match pyproject version ${version}"; exit 1
+          fi
+      - run: python -m unittest discover -s tests
+      - run: python scripts/check_no_runtime_deps.py
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check --strict dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/evidence-graph/
+    permissions:
+      id-token: write   # the OIDC token PyPI exchanges for a short-lived upload credential
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

evidence_graph-0.1.1/.github/workflows/security.yml

@@ -0,0 +1,79 @@
+name: Security
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # Weekly, so a rule set that learns about a new credential format still scans this history,
+    # and CodeQL re-runs against updated queries without waiting for a commit.
+    - cron: "17 5 * * 1"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: security-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  secrets:
+    name: Secret scan (full history)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # Full history. Scanning only the tip would miss a credential that was committed and then
+          # "removed" in a later commit, which is exactly the case that matters: the object is still
+          # in the pack file and still public.
+          fetch-depth: 0
+      # The gitleaks GitHub Action requires a paid licence key for organisation-owned repos. The
+      # gitleaks binary itself is MIT and free, so we install it directly and pin both the version
+      # and its checksum. To upgrade: bump VERSION, then take the new hash from
+      # https://github.com/gitleaks/gitleaks/releases/download/v<VERSION>/gitleaks_<VERSION>_checksums.txt
+      - name: Install gitleaks
+        env:
+          VERSION: "8.30.1"
+          SHA256: "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb"
+        run: |
+          set -euo pipefail
+          curl -fsSL -o gitleaks.tar.gz \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${VERSION}/gitleaks_${VERSION}_linux_x64.tar.gz"
+          echo "${SHA256}  gitleaks.tar.gz" | sha256sum -c -
+          tar -xzf gitleaks.tar.gz gitleaks
+          sudo install -m 0755 gitleaks /usr/local/bin/gitleaks
+          gitleaks version
+      - name: Scan git history
+        # --redact so a finding never echoes the credential into public build logs, which would
+        # turn the detector into a second disclosure.
+        run: gitleaks git --redact --verbose --config .gitleaks.toml .
+      - name: Scan the working tree
+        # Catches an unstaged or newly added file that history scanning would not see.
+        run: gitleaks dir --redact --verbose --config .gitleaks.toml .
+
+  codeql:
+    name: CodeQL
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write   # required to upload results to the Security tab
+    steps:
+      - uses: actions/checkout@v7
+      - uses: github/codeql-action/init@v4
+        with:
+          languages: python
+          queries: security-extended
+      - uses: github/codeql-action/analyze@v4
+
+  dependency-review:
+    name: Dependency review
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # A no-op today (the library has zero runtime dependencies) and that is the point: the first
+      # pull request that adds one gets its licence and advisories reviewed automatically.
+      - uses: actions/dependency-review-action@v5
+        with:
+          fail-on-severity: moderate
+          allow-licenses: Apache-2.0, MIT, BSD-2-Clause, BSD-3-Clause, ISC, PSF-2.0

evidence_graph-0.1.1/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Secrets — belt and braces. Nothing in this repo should ever need one, and the secret scan
+# (.github/workflows/security.yml) fails the build if one is committed anyway.
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+credentials.json
+service-account*.json
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+*.swp

evidence_graph-0.1.1/.gitleaks.toml

@@ -0,0 +1,24 @@
+# gitleaks configuration for evidence-graph.
+#
+# The library holds no credentials by design: it never opens a socket and never authenticates, so
+# any secret-shaped string reaching this repo is a mistake. We therefore run the full default rule
+# set and keep the allowlist deliberately small — a broad allowlist is how secret scanning quietly
+# stops working.
+
+title = "evidence-graph"
+
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Documented placeholders only. Add an entry only with a comment saying why it is safe."
+regexes = [
+  # Documentation and test fixtures use obvious non-secrets. These patterns must be self-evidently
+  # fake; never allowlist a string that could plausibly be real.
+  '''(?i)(example|placeholder|dummy|fake|redacted|your[-_]?(key|token|secret)[-_]?here)''',
+  '''^x{8,}$''',
+]
+paths = [
+  '''^LICENSE$''',
+  '''^NOTICE$''',
+]

evidence_graph-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+# Local guardrails. Install once with:  pre-commit install
+#
+# These run the same checks CI runs, so a mistake is caught before it reaches a public commit.
+# The secret scan is the one that matters most here: once a credential is pushed to a public repo
+# it must be treated as compromised, and rewriting history does not undo that.
+default_install_hook_types: [pre-commit, pre-push]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: detect-private-key
+      - id: check-added-large-files
+        # 8 MB, to admit the vendored vocabulary files under evidence_graph/data/ (ChEBI is ~6.9 MB).
+        # Code and fixtures should stay far below this; if a source file approaches it, something
+        # that belongs in a build step has been committed instead.
+        args: ["--maxkb=8192"]
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.7
+    hooks:
+      - id: ruff
+        args: ["--fix"]

evidence_graph-0.1.1/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+## 0.1.1 — 2026-11-03
+
+The first release on PyPI. Packaging only: the library code is the same as in 0.1.0, which was
+tagged but never uploaded.
+
+### Changed
+
+- `pip install evidence-graph` works. Releases are uploaded by `.github/workflows/release.yml`
+  through PyPI Trusted Publishing, so no upload token exists in the repository or its secrets.
+- Added the `py.typed` marker. The `Typing :: Typed` classifier already claimed the package was
+  typed, but without the marker type checkers ignored its annotations.
+- Dropped the `License ::` classifier. `license = "Apache-2.0"` is the PEP 639 declaration, and
+  the classifier is deprecated next to it.
+- README links are absolute, so they also resolve on the PyPI project page.
+
+## 0.1.0 — 2026-09-14
+
+First release. Extracted from [SciWay](https://sciway.software), then extended with the pieces a
+biomedical knowledge graph actually needs.
+
+### Added
+
+- **`grounding`** — surface strings to MONDO, ChEBI, GO, UBERON, CL, HGNC and UniProt CURIEs, with
+  the Biolink category each implies. 369,627 terms vendored as 10.8 MB of gzipped TSV, read with
+  stdlib gzip. Refuses most strings; reports ambiguity rather than resolving it; no edit-distance
+  fallback.
+- **`biolink`** — Biolink Model 4.4.4 categories, predicates and CURIE typing. Returns None for the
+  ~50 prefixes declared by several classes instead of guessing.
+- **`adjudicate`** — assert / abstain / conflict per candidate edge over an `EdgeScorer` Protocol.
+  Default scorer is keyless and deterministic and is explicit that it scores grounding, not truth.
+- **`maintain`** — re-runs that append revisions instead of overwriting. Edges are weakened,
+  contradicted or withdrawn, never silently deleted.
+- **`evaluation`** — edge-level precision as a function of abstention, against an explicit
+  no-abstention baseline, with a dependency-free SVG renderer.
+- **`kgx`** — KGX interchange in TSV and JSON Lines, including the Biolink-required
+  `knowledge_level` and `agent_type` that most KGX files omit.
+- **`pipeline`** — the whole spine in one call, plus `scripts/run_pipeline.py`.
+- **`evidence`** — `RetrievalHit` as the library's public input type.
+- **`ro_crate_validation`** — the RO-Crate structural validator, decoupled from any application.
+- Corpus builder for the PubMed Central Open Access subset on AWS Open Data, filtering on licence.
+
+### Fixed
+
+Four defects that only a real corpus exposed, three of them in code that was already in production:
+
+- `relations` truncated evidence quotes to the first 160 characters while the matched value could
+  be anywhere in the passage, so **a citation did not necessarily contain what it was cited for**.
+  Quotes are now windowed on the match. Adjudicated coverage moved from 6.5% to 53.8%.
+- Evidence notes carried the normalised entity key, which by construction never appears in the
+  source text, making those citations unverifiable. Each side now quotes its own surface form.
+- The entity and measurement grammars matched prose and identifiers: `at 0.01%` became an entity,
+  `PMC12345` and `IgG1` became measured quantities. Candidate edges fell from 18,191 to 12,185.
+- `adjudicate` treated descriptive trigger notes as verifiable claims about the quote, and required
+  a normalised label to appear in prose where it never does.
+
+Plus, in new code: `Vocabulary.__len__` made an empty vocabulary falsy, so `vocabulary or
+load_vocabulary()` silently loaded the real data; and lowercase prose grounded to gene symbols
+(`for` to WWOX) until surface shape was required for symbol vocabularies.
+
+### Known limitations
+
+- No gold standard for the bundled corpus, so no published precision figure.
+- The `sciway:` JSON-LD namespace in RO-Crate and PROV-O output, and the `id`/`chunk_id` key
+  inconsistency between chunks and hits, are both inherited and both breaking changes to fix.

evidence_graph-0.1.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# 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, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at hello@sciway.software. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

evidence_graph-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to evidence-graph
+
+Thanks for looking. This is a research library at 0.x: the API will change, and there is no support
+SLA. Issues and pull requests are welcome on that understanding.
+
+## Scope
+
+The library is deliberately narrow, and most of the review effort on a pull request goes into
+whether a change belongs here at all. Two rules define the boundary:
+
+**1. No network, no credentials, no models.** The library never opens a socket, never reads an API
+key, and never imports a model at runtime. It has zero runtime dependencies and CI enforces that
+(`scripts/check_no_runtime_deps.py` walks every import in the package and fails on anything outside the
+standard library).
+
+This is not minimalism for its own sake. A library that decides whether evidence supports a claim
+has to be auditable by the scientist relying on it, and has to run inside an air-gapped lab. The
+moment it needs a key, both properties are gone.
+
+If your change genuinely needs a model — an LLM that scores whether a chunk supports an edge, say —
+the right shape is a `Protocol` defined here and implemented by the caller. The library states what
+it needs; it does not reach out and get it.
+
+**2. No knowledge of users, tenants, projects, or requests.** Those concepts belong to whatever
+application embeds this. The library's world is text with provenance in, asserted edges with
+lineage out.
+
+## What a good contribution looks like
+
+- **A failing test first.** Every module here is deterministic and pure, so almost any bug can be
+  written as a test before it is fixed. If it cannot, say why in the issue.
+- **Evidence stays attached.** No code path may produce an edge, a value, or a quote that is not
+  traceable to a specific location in a source document. A convenience that drops provenance will
+  be rejected even when it is faster.
+- **Abstention is a feature.** When the evidence does not support an assertion, the correct output
+  is an abstention or a recorded conflict. Pull requests that improve coverage by lowering the bar
+  for assertion need to show the precision cost, not just the coverage gain.
+- **Synthetic fixtures only.** Never commit real unpublished research, patient data, or anything
+  under an NDA, including in tests.
+
+## Development
+
+```bash
+git clone https://github.com/SciWay-platform/evidence-graph.git
+cd evidence-graph
+
+python -m unittest discover -s tests -v      # the suite; standard library only, no install needed
+pip install ruff==0.16.7 && ruff check .     # lint
+python scripts/check_no_runtime_deps.py      # the zero-dependency guard
+
+pip install pre-commit && pre-commit install # optional, runs the same checks plus a secret scan
+```
+
+There is no build step and nothing to install to run the tests. If that ever stops being true,
+something has gone wrong.
+
+## Style
+
+Match the surrounding code. Concretely, for this repo that means:
+
+- A module docstring that states what the module is for and why it exists in that form. The
+  docstrings here carry design reasoning deliberately, because the *why* is the part that decays.
+- Type hints on public functions, `from __future__ import annotations` at the top.
+- Comments explain decisions, not mechanics.
+- `ruff check .` must pass. There is no enforced formatter: line-length errors are switched off
+  because much of this code is regex grammar and vocabulary tables where a hard wrap hurts.
+
+## Licensing
+
+By contributing you agree that your contribution is licensed under the
+[Apache License 2.0](LICENSE), the same licence as the project. There is no CLA.
+
+Code adapted from another project must keep its attribution and be recorded in [NOTICE](NOTICE),
+with the upstream licence reproduced in full.
+
+## Security
+
+Do not report vulnerabilities in a public issue. See [SECURITY.md](SECURITY.md).
+
+## Code of conduct
+
+Participation is covered by the [Contributor Covenant](CODE_OF_CONDUCT.md).