Format a context section.

Generate a short unique ID with prefix.

Add an evidence node under a claim. Links to a source_id in the sources table. evidence_type: paper, book, report, legal_doc

Get an API key by environment variable name. If required=True and key is missing, logs a clear warning. Returns empty string if not set.

Add a claim node under a question.

Route LLM call with automatic fallback. Priority: 1. Claude API (primary model for agent) 2. Claude API

Add a sub-question node under a parent (usually root).

Format a list of sources into readable text.

Summary statistics of the tree.

Run a single pipeline step with error handling. Returns True on success, False on failure.

Generic insert into any table.

Generic fetch from any table.

Infer whether an agent already ran for this run by checking for data in the table it writes to. Used to skip re-running agents on resume.

Exponential backoff after a failed request. Call this when you get a 429 or 5xx response.

Get all nodes of a specific type.

Block until it is safe to make a call to source_id. Respects min_delay between calls. Prints a countdown if waiting more than

Add an audit note from the Historian. Optionally updates the target node's status and confidence.

Get all direct children of a node.

Convert 'First Last' to 'Last, F.' for APA.

Create the root node from the research question.

Serialize the tree into a structured text context for LLM prompts.

Save each result to all_sources and build tree nodes.

Get argument tree context if tree exists for this run.

Load config.json — theme bank and source stack.

Lowercase, strip punctuation, collapse whitespace.

Add an external factor node — events, policies, wars, institutional changes that shaped the intellectual trajectory but aren't publis

Find structural gaps in the tree: - Questions with no claims - Claims with no evidence - Claims with low confidence

Get a single node as a dict.

Rate-limited GET with backoff on 429/5xx.

Generate a short title from the problem.

Generic update on any table.

Check if any author surname appears in both lists.

Check if instructions contradict prior agent outputs. Returns a list of contradiction notices to inject into the next agent's context.

Check if instructions contradict prior agent outputs. Returns a list of contradiction notices to inject into the next agent's context.

Normalize DOI — accept raw DOI or URL form. Returns bare DOI.

Wait for the human to upload an instruction file. Polls every 10 seconds. Press Ctrl+C to abort.

Wait for the human to upload an instruction file. Polls every 10 seconds. Press Ctrl+C to abort.

Add a bridge node connecting two distant parts of the tree. bridge_type: temporal (fills a time gap), disciplinary (connects fields),

Add a historical context node.

Find pairs of evidence nodes under the same question that have a large temporal gap — these need bridge papers.

Context for Synthesizer — tree + everything.

Context for the Understanding Map — the core mandatory Scribe output. Provides the richest possible context: seminal works, historical timeli

Context for Vision — tree + gaps + social + Break 1.

Configure logging — file + console.

Check if a URL is alive. Returns: active / dead / redirected.

Check if a model is available in Ollama.

Collect papers for a single theme from its configured sources.

Extract structural gaps directly from the argument tree.

Load .env file into os.environ if not already set.

Load .env before initializing clients — keys.py may not have run yet.

Return a clean export dict for one paper.

Return a clean export dict for one paper.

Robust JSON extraction — handles fences and partial truncation.

Print a visible wait notice with countdown.

Split a comma-separated key list from inside a single [..] bracket.

Best-effort surname extraction. Handles 'Last, First' and 'First Last'.

Pydantic v2: use mode='json' to convert AnyUrl → plain strings.

Add a counter-argument to a claim. Updates parent status to contested.

Extract the human-readable term from a ConceptNet URI. /c/en/artificial_intelligence/n -> "artificial intelligence" /c/en/mind_body_probl

Context for Rude — tree + proposals + dead ends + social.

Context for Theorist — tree + all prior outputs.

Context for Thinker — tree + synthesis + pipeline.

Get all unique source_ids referenced in the tree.

Get the full tree as a nested dict. Efficient: one query, then build in memory.

Fallback: load all sources for a run if no tree exists.

Print a clear table of which keys are set and which are missing.

Recheck all active links in the database. Move dead links to dead_links archive. Returns summary dict.

Synchronous entry point. First call triggers registration + browser login.