scitex.clew API Reference

scitex-clew — Hash-based verification for reproducible science.

Standalone package. Zero dependencies (pure stdlib + sqlite3). When used with scitex, integration is automatic via @stx.session + stx.io.

Public API:

import scitex_clew as clew

# Verification
clew.status()                      # git-status-like overview
clew.run(session_id)               # verify one run (hash check)
clew.chain(target_file)            # trace file → source chain
clew.dag(targets)                  # verify full DAG
clew.rerun(target)                 # re-execute & compare (sandbox)
clew.rerun_dag(targets)            # rerun full DAG in topo order
clew.rerun_claims()                # rerun all claim-backing sessions
clew.list_runs(limit=100)          # list tracked runs
clew.stats()                       # database statistics
clew.estimate(script_or_target)    # pre-flight runtime/success estimate

# Claims
clew.add_claim(...)                # register manuscript assertion
clew.list_claims(...)              # list registered claims
clew.verify_claim(...)             # verify a specific claim
clew.verify_all_claims(...)        # verify every claim -> fail-loud code

# Citations (\cite -> scholar-verified source gate)
clew.add_citation(...)             # register (push) a scholar-resolved cite
clew.list_citations(...)           # list registered citation nodes
clew.verify_citations(entries)     # per-key {status,doi,source_id,link,reason}
clew.verify_all_citations(entries) # fail-loud VerificationResult (same-run)

# Stamping
clew.stamp(...)                    # create temporal proof
clew.list_stamps(...)              # list stamps
clew.check_stamp(...)              # verify a stamp

# Hashing
clew.hash_file(path)               # SHA256 of a file
clew.hash_directory(path)          # SHA256 of all files in dir

# Visualization
clew.mermaid(...)                  # generate Mermaid DAG diagram

# Examples
clew.init_examples(dest)           # scaffold example pipeline

# Session lifecycle hooks (invoked by @scitex.session)
clew.on_session_start(session_id)  # open a tracked run
clew.on_session_close(status=...)  # finalize run + combined hash

Implementation note (audit-all §10 cold-start):

This module uses the PEP 562 ``__getattr__`` lazy-import pattern. All
submodules and re-exports below ``__version__`` are loaded on first
access only, so ``import scitex_clew`` stays well under the 500ms
cold-start threshold. The public attribute names listed above (and in
``__all__``) resolve exactly as before — no caller-visible change.

scitex.clew.status()

Get verification status summary (like git status).

scitex.clew.run(session_id: str, from_scratch: bool = False)

Verify a specific run.

Parameters:

• session_id (str) – Session identifier

• from_scratch (bool, optional) – If True, re-execute the script and verify outputs (slow but thorough). If False, only compare hashes (fast).

scitex.clew.chain(target: str)

Verify the dependency chain for a target file.

scitex.clew.dag(targets=None, claims=False, strict=False)

Verify the DAG for multiple targets or all claims.

Parameters:

• targets (list of str or Path, optional) – Target files to verify (mutually exclusive with claims).

• claims (bool, optional) – If True, build the DAG from every registered claim.

• strict (bool, optional) – If True (F2), return a failure-attribution dict with failed_node / root_cause / invalidated_claims / still_valid_claims instead of a DAGVerification.

scitex.clew.rerun(target, timeout: int = 300, cleanup: bool = True)

Re-execute a session in a sandbox and compare outputs.

Parameters:

• target (str or list[str]) – Session ID, script path, or artifact path.

• timeout (int, optional) – Maximum execution time in seconds (default: 300).

• cleanup (bool, optional) – Remove sandbox outputs after verification (default: True).

scitex.clew.rerun_dag(targets=None, timeout=300, cleanup=True, skip_unchanged=False)

Rerun-verify an entire DAG in topological order.

Each session is re-executed against its ORIGINAL stored inputs then compared to its original outputs. When skip_unchanged=True a freshness check short-circuits the subprocess for unchanged sessions.

Parameters:

• targets (list of str, optional) – Target output files. If None all recorded outputs are used.

• timeout (int, optional) – Max execution time per session in seconds (default: 300).

• cleanup (bool, optional) – Remove sandbox output directories after each rerun.

• skip_unchanged (bool, optional) – OPT-IN incremental skip (default: False). When True, each session is tested for freshness BEFORE the expensive subprocess launch. A session is fresh when: (1) script_hash is recorded; (2) script file exists and matches script_hash; (3) every recorded INPUT file exists and its hash matches the recorded value. Fresh sessions are marked status=VERIFIED / level=CACHE so is_verified_from_scratch is False — clearly distinct from an actual re-execution. Non-fresh sessions fall through to the normal _execute_script path. Default is False: behavior is byte-identical to the original.

Returns:

Unified verification result for the entire DAG.

Return type:

DAGVerification

scitex.clew.rerun_claims(file_path=None, claim_type=None, timeout=300, cleanup=True)

Rerun-verify all sessions that produced files referenced by claims.

Parameters:

• file_path (str, optional) – Filter claims by manuscript file path.

• claim_type (str, optional) – Filter claims by type (statistic, figure, table, text, value).

• timeout (int, optional) – Maximum execution time per session in seconds (default: 300).

• cleanup (bool, optional) – Whether to remove sandbox output directories after each rerun.

Returns:

Unified verification result for the upstream DAG.

Return type:

DAGVerification

scitex.clew.list_runs(limit: int = 100, status: str = None)

List tracked runs.

scitex.clew.stats()

Get database statistics.

scitex.clew.estimate(script_or_target: str, *, heavy_threshold: int = None)

Pre-flight runtime/success estimate for a script or target file.

Parameters:

• script_or_target (str) – Path to a Python script or a target output file. Target files are resolved to their producing script via the run DB.

• heavy_threshold (int, optional) – Override the p90 threshold (seconds) above which the heavy flag is set. Defaults to scitex_clew.HEAVY_THRESHOLD_SECONDS.

Returns:

Estimation result with match_tier, p50/p90 runtime, success rate, typical #outputs, heavy flag, and hint text.

Return type:

EstimateResult

scitex.clew.add_claim(file_path, claim_type, line_number=None, claim_value=None, source_file=None, source_session=None, *, claim_id=None)

Register a claim linking a manuscript assertion to the verification chain.

Parameters:

• file_path (str) – Path to the manuscript file (e.g., paper.tex).

• claim_type (str) – One of: statistic, figure, table, text, value.

• line_number (int, optional) – Line number in the manuscript.

• claim_value (str, optional) – The asserted value (e.g., “p = 0.003”).

• source_file (str, optional) – Path to the source file that produced this claim.

• source_session (str, optional) – Session ID that produced the source.

• claim_id (str, optional) – Explicit, stable claim id used VERBATIM as the primary key (keyword- only). Supply this when the caller owns a meaningful identity — e.g. a figure’s image save-path, or a semantic key per manuscript number — so the id never collapses and downstream \clew*{id} render macros can join on it deterministically. When omitted, the id is DERIVED from (file_path, line_number, claim_type, claim_value) — folding the value in so two distinct numbers on one line no longer collapse. Re- registering the same explicit id (or the same derived tuple) overwrites idempotently.

Returns:

The registered claim object.

Return type:

Claim

scitex.clew.list_claims(file_path=None, claim_type=None, status=None, limit=100, *, include_superseded=False, file_path_prefix=None)

List registered claims with optional filters.

Parameters:

• file_path (str, optional) – Filter by manuscript file path (exact match).

• claim_type (str, optional) – Filter by claim type.

• status (str, optional) – Filter by verification status.

• limit (int) – Maximum number of claims to return.

• include_superseded (bool, optional) – When False (default), excludes claims with status "superseded" so they do not pollute the active-claim view or fail-loud gate. Pass True to see the full audit trail including superseded rows.

• file_path_prefix (str, optional) – Prefix-match on file_path (resolved). Only claims whose file_path starts with this prefix are returned. If both file_path and file_path_prefix are given, both filters apply (intersection).

Return type:

list of Claim

scitex.clew.verify_claim(claim_id_or_location, hash_cache=None, chain_cache=None)

Verify a specific claim by checking its source against the verification chain.

Parameters:

• claim_id_or_location (str) – Either a claim_id or a location string like “paper.tex:L42”.

• hash_cache (dict or None, optional) – Per-pass cache mapping resolved-path -> hash (see scitex_clew._hash.hash_file()). When provided, a source file shared by multiple claims is hashed at most once per pass. Pass None (default) to disable caching — direct callers are unaffected.

• chain_cache (dict or None, optional) – Per-pass memo mapping str(resolved source_file) -> ChainVerification. When provided, the full chain walk (verify_chain) for a source_file that appears on multiple claims is executed at most once per verify_all_claims() pass. Pass None (default) to disable memoization — direct callers are unaffected.

Returns:

Verification result with claim details and chain status.

Return type:

dict

scitex.clew.verify_all_claims(file_path=None, claim_type=None, *, strict=False, config=None)

Verify every registered claim and reduce to a fail-loud result.

This is the reusable core behind clew verify (claim-set mode). It re-verifies each claim (re-hashing its source and, in strict mode, checking upstream @stx.session lineage), updates each claim’s stored status as a side effect (via verify_claim()), and reduces the per-claim outcomes to a single VerificationResult.

Parameters:

• file_path (str, optional) – Restrict to claims registered against this manuscript path.

• claim_type (str, optional) – Restrict to claims of this type.

• strict (bool, optional) – When True, a claim only passes if its source additionally has upstream computation lineage (its provenance chain verifies). A hand-written leaf (no @stx.session behind it) fails with NO_LINEAGE even though its hash matches. strict also promotes NO_LINEAGE to ERROR severity regardless of config. Default False.

• config (str or pathlib.Path, optional) – Explicit .scitex/clew config file/dir overriding the resolved user/project severity map (see scitex_clew._core._config).

Returns:

Structured outcome. result.exit_code == 0 (result.ok) is the DONE-gate; any nonzero code means the agent MUST abstain honestly instead of claiming success. Per-pattern severity (configurable via .scitex/clew) decides which fired patterns are errors (fail) vs warnings (tolerated). See scitex_clew._cli._exit_codes.

Return type:

VerificationResult

scitex.clew.export_claims_json(path=None, *, file_path_filter=None, read_only=True, include_superseded=False)

Export every registered claim to a canonical JSON artifact.

The exported file is the single human-readable + machine-consumable view of the claims table in clew.db. The DB remains the source of truth; this JSON is a regenerable artifact.

Path resolution (mirrors scitex_clew._db._core._default_db_path()):

1. Explicit ``path`` argument.
2. ``$SCITEX_CLEW_CLAIMS_JSON`` env var (escape hatch).
3. ``<project_root>/.scitex/clew/runtime/claims.json``
   (project root = nearest ancestor dir with ``.git`` or
   ``pyproject.toml``; falls back to cwd if none found).

Parameters:

• path (str | Path, optional) – Override the resolved path. Useful for tests / one-off dumps.

• file_path_filter (str, optional) – When set, only claims registered against this manuscript file path are exported. Default: every claim in the DB.

• read_only (bool, optional) – After writing, chmod 0o444 the file so accidental edits fail loudly at the OS layer. Default True (the file IS derived). Set False for tests that need to mutate the file.

• include_superseded (bool, optional) – When False (default), superseded claims are excluded from the exported JSON — consumers should only see active claims. Pass True to include them (audit/debug use).

Returns:

The path the artifact was written to (absolute).

Return type:

Path

Examples

>>> import scitex_clew as clew
>>> clew.add_claim("paper.tex", "value", 42, "0.94", source_file="r.csv")
>>> # claims.json now auto-exported under ./.scitex/clew/runtime/
>>> clew.export_claims_json()  # idempotent — re-emit on demand
PosixPath('.../.scitex/clew/runtime/claims.json')

scitex.clew.export_manuscript_claims(path=None, *, read_only=True)

Emit the unified render feed (value + citation + figure) to claims.json.

Reads both clew ledgers and writes ONE claims list in scitex-writer’s frozen render schema. This is the compile-time exporter behind clew export-claims --unified; the compiler calls it last so render_clew reads the complete unified shape.

Parameters:

• path (str | Path, optional) – Output path. Resolution mirrors export_claims_json(): explicit path > $SCITEX_CLEW_CLAIMS_JSON > <project_root>/.scitex/clew/runtime/claims.json (the canonical file render_clew reads). Pass an explicit path for a dedicated file.

• read_only (bool, optional) – chmod 0o444 the file after writing (default True — it is derived).

Returns:

The path written (absolute).

Return type:

Path

scitex.clew.register_intermediate(name, value, supports=None, session_id=None, claim_type='value')

Register a computed intermediate as a Clew claim.

Use this from inside a @stx.session script (or from an agent loop) to record any non-trivial intermediate value with explicit upstream support. The claim becomes part of the DAG and can be queried via clew.chain, clew.dag, or the MCP clew_chain / clew_dag tools.

Parameters:

• name (str) – Descriptive identifier (e.g. “acute_n_sig_pathways”). Avoid generic names like “result_3” — the id is the only handle a future inspector has on the value.

• value (Any) – The computed result. Coerced to string for storage; the hash chain sees repr(value) so types matter.

• supports (Optional[List[str]]) – List of upstream claim ids or session ids that this value depends on. Stored as JSON in the claim’s value field for retrieval. None means no explicit upstream (use sparingly).

• session_id (Optional[str]) – The session this value belongs to. If None, read from the SCITEX_SESSION_ID env var that @stx.session sets at start.

• claim_type (str) – One of statistic, figure, table, text, value. Defaults to value since intermediates are usually scalar / categorical results.

Returns:

The registered claim object.

Return type:

Claim

Raises:

ValueError – If no session_id can be determined (env var unset and not passed).

Examples

Inside a @stx.session script:

>>> from scitex_clew import register_intermediate
>>> n_sig = sum(1 for p in pathways if p.padj < 0.05)
>>> register_intermediate(
...     name="chronic_r2_n_sig_pathways",
...     value=n_sig,
...     supports=["chronic_r2_min_pvals", "reactome_pathways_v2024"],
... )

scitex.clew.remove_claim(claim_id_or_location)

Hard-delete a claim from the database.

Permanently removes the claim row identified by claim_id_or_location (a claim_id string, a location like "paper.tex:L42", or a bare file path — resolved via the same logic as verify_claim()).

After deletion export_claims_json() is called so the JSON artifact stays in sync with the DB.

Parameters:

claim_id_or_location (str) – Claim identifier. Resolution order: 1. Exact claim_id match. 2. Location string "file.tex:L42". 3. File path only (first row).

Returns:

True if a row was deleted; False if nothing matched.

Return type:

bool

scitex.clew.supersede_claim(claim_id_or_location)

Soft-retire a claim by setting its status to "superseded".

The row is kept in the database (audit trail) but excluded from the default list_claims() view (include_superseded=False is the default), from verify_all_claims(), and from the default export_claims_json() output.

This allows a user to retire stale/dead claims so that clew verify can reach exit 0 without deleting the historical record.

Parameters:

claim_id_or_location (str) – Claim identifier resolved the same way as remove_claim().

Returns:

True if the claim existed and was updated; False if nothing matched.

Return type:

bool

scitex.clew.add_citation(cite_key, *, manuscript_file=None, line_number=None, doi=None, source_id=None, metadata=None, url=None, is_stub=False, resolved=True)

Register (push) a citation node resolved by scitex-scholar.

This is the ledger-write half of the push model: scholar resolves a \cite key to a real source and records the outcome here. clew stores the node plus a content hash over the normalized metadata so a later out-of-band edit to the bib entry is caught (drift -> hash mismatch).

Parameters:

• cite_key (str) – The BibTeX citation key (e.g. "Berens2009CircStat").

• manuscript_file (str, optional) – Manuscript the key is cited from (e.g. paper.tex).

• line_number (int, optional) – Line number of the \cite in the manuscript.

• doi (str, optional) – Resolved DOI of the real source (None for a stub / unresolved).

• source_id (str, optional) – Scholar’s internal source identifier for the resolved record.

• metadata (dict, optional) – Bib fields (author/year/title/journal/doi) used for the content hash.

• url (str, optional) – Explicit source URL. Takes precedence over the derived https://doi.org/<doi> link — supply it for no-DOI records (e.g. SemanticScholar CorpusId-only) so the renderer has an href.

• is_stub (bool, optional) – True if scholar flagged this as a stub / placeholder. Default False.

• resolved (bool, optional) – True if scholar resolved the key to a real source. Default True.

Returns:

The stored citation node.

Return type:

Citation

scitex.clew.list_citations(manuscript_file=None, status=None, limit=1000)

List registered citation nodes with optional filters.

Return type:

List[Citation]

scitex.clew.verify_citations(entries)

Verify a set of cited keys against the clew citation ledger.

This is the primitive the compiler’s pre-flight calls. For each entry it returns the per-key verdict the writer gate branches on.

Parameters:

entries (list[dict] | list[str]) – Cited keys. Each dict carries at least "key" plus any bib fields the compiler extracted (doi/journal/note/title/ author/year). A bare string is treated as {"key": ...}.

Returns:

{cite_key: {"status", "doi", "source_id", "link", "reason"}} where status is one of {verified, stub, unverified, unknown} and link is the resolved source URL for an href (scholar-supplied url, else https://doi.org/<doi>, else None). The compiler treats anything other than "verified" as a gate hit and renders the marker from status (style) + link (href) + reason (tooltip).

Return type:

dict[str, dict]

scitex.clew.verify_all_citations(entries, *, strict=False, config=None)

Reduce a set of cited keys to a fail-loud VerificationResult.

Same aggregate contract as scitex_clew.verify_all_claims(), so the compiler gets a single result.ok DONE-gate covering citations. Per-key verdicts reduce onto the citation exit codes (CITATION_STUB / _UNRESOLVED / _UNLINKED, plus HASH_MISMATCH on drift), each config-tunable via .scitex/clew verify.severity.

Parameters:

• entries (list[dict] | list[str]) – Cited keys (see verify_citations()).

• strict (bool, optional) – Reserved for parity with the claim gate; currently a no-op for citations (every citation pattern already defaults to ERROR).

• config (str | pathlib.Path, optional) – Explicit .scitex/clew config overriding the resolved severity map.

Returns:

result.ok (exit 0) iff every cited key is verified.

Return type:

VerificationResult

scitex.clew.register_source(files, *, sources_path=None, root=None)

Register one or more files as trusted sources (idempotent).

Computes each file’s full sha256 and appends/updates a {path, sha256} entry in the manifest, creating it at the tier-3 path if absent. Re- registering a path updates its hash (idempotent).

Parameters:

• files (str | Path | list) – File(s) to register. Each must exist (its content is hashed now).

• sources_path (str | Path, optional) – Explicit manifest path (else tier-2 env / tier-3 default).

• root (str | Path, optional) – Project root that relpaths are stored against (default: cwd walk).

Returns:

The manifest path written to (absolute).

Return type:

Path

scitex.clew.unregister_source(files, *, sources_path=None, root=None)

Remove one or more registered sources (idempotent; no-op if absent).

Return type:

Path

scitex.clew.list_sources(*, sources_path=None, root=None)

Return the manifest entries with a per-entry validity check.

Each dict carries path, sha256, abspath, valid (bool), and reason (OK / TAMPERED / MISSING). Returns [] when no manifest exists.

Return type:

List[dict]

scitex.clew.is_grounded(claim, manifest, db)

Return True iff the claim’s chain reaches a VALID registered source.

Parameters:

• claim (Claim) – The claim (needs source_file, source_hash, source_session).

• manifest (SourcesManifest) – A loaded, tamper-checked manifest. When it has no VALID anchors the function returns True (defensive: nothing to demote against — the caller normally gates on manifest.active before calling).

• db (VerificationDB) – Provides the file-hash + producer lookups the chain walk needs.

Returns:

True (grounded) iff at least one chain candidate matches a valid anchor by absolute path AND hash-consistency; False (unsourced) when every root is unregistered.

Return type:

bool

scitex.clew.load_sources_manifest(sources_path=None, *, root=None)

Load + tamper-check the registered-source manifest.

Parameters:

• sources_path (str or Path, optional) – Explicit manifest path (tier 1). Falls through to $SCITEX_CLEW_SOURCES (tier 2) then the tier-3 default.

• root (str or Path, optional) – Project root the manifest relpaths resolve against. When None, derived from the manifest location (canonical layout) or the cwd project-root walk.

Returns:

None when the manifest file does not exist — the gate is then INACTIVE (opt-in: zero behavior change). A present manifest is parsed, schema-validated, and every entry tamper-checked (recompute each file’s sha256 vs the pinned value).

Return type:

SourcesManifest or None

Raises:

ValueError – On a malformed manifest (not JSON, wrong schema string, missing sources list, or a malformed entry). Fail-loud, never silent-empty.

scitex.clew.resolve_sources_path(sources_path=None)

Resolve the manifest path via the three-tier precedence.

Mirrors scitex_clew._db._core.resolve_db_path() exactly: tier1 explicit arg > tier2 $SCITEX_CLEW_SOURCES > tier3 <project_root>/.scitex/clew/sources.json.

Returns:

The resolved path and a human-readable label of the producing tier. This function only resolves — it neither creates nor requires the file.

Return type:

tuple of (Path, str)

class scitex.clew.SourcesManifest(schema, root, path, entries=<factory>, signature=None, signing_enforced=False, signature_valid=None)

Bases: object

A loaded, tamper-checked registered-source manifest.

active is the OPT-IN switch: the gate only fires when at least one VALID entry is present. An absent manifest loads as None (see load_sources_manifest()); a present-but-empty or all-invalid manifest is active is False so the gate stays dormant.

schema: str

root: Path

path: Path

entries: List[SourceEntry]

signature: Any | None = None

signing_enforced: bool = False

signature_valid: bool | None = None

property valid_entries: List[SourceEntry]

property invalid_entries: List[SourceEntry]

property trusted: bool

False iff signing is ENFORCED but the manifest’s signature is missing/invalid — an untrusted manifest anchors NOTHING (so a tampered or unsigned-under-an-enforcing-key manifest cannot ground any claim: “without the key it can’t be run/edited”).

property active: bool

Gate FIRES iff signing is enforced (a committed signing.pub) OR >=1 VALID anchor exists.

When signing is enforced the gate fires even for an UNTRUSTED manifest — so is_grounded blocks ALL its claims (an unsigned or tampered manifest must not silently pass by making the gate go dormant).

anchor_paths()

Resolved absolute paths of the VALID anchors (for grounding); EMPTY when the manifest is untrusted (unsigned/tampered under an enforcing key).

Return type:

Set[str]

pinned_for(abspath)

Pinned sha256 for a VALID anchor at abspath (else None); always None when the manifest is untrusted.

Return type:

Optional[str]

scitex.clew.stamp(backend='file', service_url=None, session_ids=None, output_dir=None)

Record root hash with external timestamp.

Parameters:

• backend (str) – One of: file, rfc3161, zenodo.

• service_url (str, optional) – URL for RFC 3161 TSA or Zenodo API.

• session_ids (list of str, optional) – Specific sessions to stamp. If None, stamps all successful runs.

• output_dir (str, optional) – Directory for file-based stamps (default: <db_dir>/stamps, i.e. .scitex/clew/runtime/stamps/).

Returns:

The timestamp proof record.

Return type:

Stamp

scitex.clew.list_stamps(limit=20)

List all stamps.

Return type:

List[Stamp]

scitex.clew.check_stamp(stamp_id=None)

Verify a stamp against current verification state.

Parameters:

stamp_id (str, optional) – Specific stamp to check. If None, checks the latest stamp.

Returns:

{stamp, current_root_hash, matches, details}

Return type:

dict

scitex.clew.hash_file(path, algorithm='sha256', chunk_size=8192, hash_cache=None)

Compute hash of a file.

Parameters:

• path (str or Path) – Path to the file to hash

• algorithm (str, optional) – Hash algorithm (default: sha256)

• chunk_size (int, optional) – Size of chunks to read (default: 8192)

• hash_cache (dict or None, optional) – Per-pass cache mapping resolved-path -> hash. When provided, the resolved path is looked up first; on a miss the file is hashed and the result is stored so subsequent calls within the same pass reuse the cached value. Pass None (default) to disable caching — direct calls to hash_file are unaffected.

Returns:

Hexadecimal hash string (first 32 characters)

Return type:

str

Examples

>>> hash_file("data.csv")
'a1b2c3d4e5f6...'

scitex.clew.hash_directory(path, pattern='*', recursive=True, algorithm='sha256')

Compute hashes for all files in a directory.

Parameters:

• path (str or Path) – Directory path

• pattern (str, optional) – Glob pattern for files (default: “*”)

• recursive (bool, optional) – Whether to search recursively (default: True)

• algorithm (str, optional) – Hash algorithm (default: sha256)

Returns:

Mapping of relative paths to hashes

Return type:

dict

Examples

>>> hash_directory("./data/")
{'input.csv': 'a1b2...', 'config.yaml': 'c3d4...'}

Notes

Transparently accepts a compressed session archive: if path is a <dir>.tar.gz file (or a directory whose <dir>.tar.gz sibling exists because it was archived away), the members are hashed in place and returned with the same {relpath: hash} shape a loose dir would yield.

scitex.clew.mermaid(session_id=None, target_file=None, target_files=None, claims=False, grouper=None, **kwargs)

Generate a Mermaid DAG diagram.

Parameters:

• session_id (str, optional) – Start from this session.

• target_file (str, optional) – Start from the session that produced this file.

• target_files (list of str, optional) – Multiple target files (multi-target DAG).

• claims (bool, optional) – If True, build DAG from all registered claims.

• grouper (callable | dict | None, optional) – File grouping strategy. Callable or JSON/dict spec (see scitex_clew.groupers.resolve_spec). If None, falls back to .scitex/clew/config.yaml (key grouper) if present.

scitex.clew.init_examples(dest, variant='sequential', *, find_examples_dir=<function _find_examples_dir>)

Copy Clew example scripts to a destination directory.

Copies only the runnable scripts (.py, .sh) and README — not the output directories. Users run 00_run_all.sh themselves to generate outputs and populate the verification database.

Parameters:

• dest (str or Path) – Destination directory. Created if it does not exist. Existing script files are overwritten.

• variant (str, optional) – Example variant: “sequential” (default) or “multi_parent”.

• find_examples_dir (callable, optional) – Locator callable (variant: str) -> Optional[Path] used to resolve the bundled examples source. Production callers should not pass this; it is the canonical PA-306 §1 DI seam — tests inject a hand-rolled fake that returns a tmp_path-rooted directory or None.

Returns:

{"path": str, "files": list[str], "file_count": int, "variant": str}

Return type:

dict

Raises:

• FileNotFoundError – If the bundled examples cannot be located.

• ValueError – If variant is not recognized.

scitex.clew.on_session_start(session_id, script_path=None, parent_session=None, verbose=False, metadata=None)

Hook called when a session starts.

Parameters:

• session_id (str) – Unique session identifier

• script_path (str, optional) – Path to the script being run

• parent_session (str, optional) – Parent session ID for chain tracking

• verbose (bool, optional) – Whether to log status messages

• metadata (dict, optional) – Additional metadata (e.g. notebook_path, cell_index)

Return type:

None

scitex.clew.on_session_close(status='success', exit_code=0, verbose=False, register=None)

Hook called when a session closes.

Parameters:

• status (str, optional) – Final status (success, failed, error)

• exit_code (int, optional) – Exit code of the script

• verbose (bool, optional) – Whether to log status messages

• register (bool, optional) – If True, register session hashes with remote Clew Registry. If None, checks SCITEX_AUTO_REGISTER environment variable.

Return type:

None