uchrom.auto_discovery

Multi-omics auto-discovery helpers for ChromData.

class uchrom.auto_discovery.AnalysisCodeResult(analysis_code: str, agent_records: list[BackendAgentRecord] = <factory>, extra_cells: list[dict[str, ~typing.Any]]=<factory>, artifact_manifest: list[dict[str, ~typing.Any]]=<factory>, warnings: list[str] = <factory>, notes: list[str] = <factory>)

Bases: object

Structured analysis code returned by a backend.

agent_records: list[BackendAgentRecord]

analysis_code: str

artifact_manifest: list[dict[str, Any]]

extra_cells: list[dict[str, Any]]

notes: list[str]

warnings: list[str]

class uchrom.auto_discovery.BackendAgentRecord(agent_name: str, role: str, prompt_path: str, content: Any)

Bases: object

Audit record for one backend invocation.

agent_name: str

content: Any

prompt_path: str

role: str

class uchrom.auto_discovery.BackendCapabilities(structured_output: bool, file_workspace: bool, prompt_via_stdin: bool, streaming: bool, native_skill_loading: bool = False, resume: bool = False, owns_notebook_lifecycle: bool = False)

Bases: object

Capabilities reported by an auto-discovery backend.

file_workspace: bool

native_skill_loading: bool = False

owns_notebook_lifecycle: bool = False

prompt_via_stdin: bool

resume: bool = False

streaming: bool

structured_output: bool

class uchrom.auto_discovery.BackendDetection(backend_id: str, executable_path: str | None, version: str | None = None, available: bool = False, auth_state: str = 'unknown', error: str | None = None, cli_flags: Mapping[str, bool]=<factory>)

Bases: object

Best-effort local CLI detection result.

auth_state: str = 'unknown'

available: bool = False

backend_id: str

cli_flags: Mapping[str, bool]

error: str | None = None

executable_path: str | None

version: str | None = None

exception uchrom.auto_discovery.BackendError(message: str, *, category: str, retryable: bool)

Bases: RuntimeError

A classified backend failure.

category is one of backend_unavailable (missing/exited binary or an auth failure that a retry will not fix), failed (ran but exited non-zero for another reason), bad_output (ran but produced output that could not be parsed), or timeout. retryable tells the run loop whether a transient retry is worthwhile.

class uchrom.auto_discovery.CLISpec(backend_id: str, display_name: str, executable: str, build_command: Any, stream_format: str, run_environment: Any = <function _default_run_environment>, fallback_bins: tuple[str, ...]=(), capability_probe: Mapping[str, str]=<factory>)

Bases: object

Data describing one stdin-driven coding-agent CLI backend.

Per-CLI differences are expressed as data here rather than as subclass overrides, mirroring open-design’s data-driven adapter model: the generic CLIBackend consumes a spec and the core never branches on backend id.

backend_id: str

build_command: Any

capability_probe: Mapping[str, str]

display_name: str

executable: str

fallback_bins: tuple[str, ...] = ()

run_environment() → Iterator[dict[str, str]]

stream_format: str

class uchrom.auto_discovery.ClaimRefreshResult(mode: str, claims_path: str | None, retrieval_log_path: str, n_claims: int, source_paths: list[str], notes: list[str])

Bases: object

Summary of one claim-refresh pass.

claims_path: str | None

mode: str

n_claims: int

notes: list[str]

retrieval_log_path: str

source_paths: list[str]

to_dict() → dict[str, Any]

class uchrom.auto_discovery.DiscoveryDirection(direction_id: str, direction_type: str, priority: float, title: str, prompt: str, rationale: str, target_facets: dict[str, ~typing.Any]=<factory>, parent_idea_ids: list[str] = <factory>, evidence_basis: list[dict[str, ~typing.Any]]=<factory>, novelty_notes: list[str] = <factory>, constraints: list[str] = <factory>)

Bases: object

A graph-derived search direction for the next idea-agent batch.

constraints: list[str]

direction_id: str

direction_type: str

evidence_basis: list[dict[str, Any]]

property frontier_id: str

Legacy alias for callers that have not migrated yet.

property frontier_type: str

Legacy alias for callers that have not migrated yet.

novelty_notes: list[str]

parent_idea_ids: list[str]

priority: float

prompt: str

rationale: str

target_facets: dict[str, Any]

title: str

to_dict() → dict[str, Any]

Return a JSON-serializable direction record.

class uchrom.auto_discovery.DiscoveryEnrichmentConfig(fasta: str | Path | None = None, sequence_features: list[str] | None = None, gtf: str | Path | None = None, annotation_features: list[str] | None = None, promoter_window: tuple[int, int]=(-2000, 500), structures: list[str] = <factory>, project_existing_structure: bool = False, chroms: list[str] | None = None, device: str = 'auto', peak_tracks: list[str] = <factory>, peak_control_tracks: list[str] = <factory>, peak_method: str = 'auto', peak_agg: str = 'mean', peak_threshold: float | None = None, peak_quantile: float = 0.95, peak_cutoff: float | None = None, peak_min_length: int = 200, peak_max_gap: int = 30, peak_qvalue: float | None = 0.05, peak_pvalue: float | None = None, peak_genome_size: float | None = None, peak_small_local_window_bins: int = 10, peak_large_local_window_bins: int = 100, peak_fragment_size_bins: int = 1, peak_min_width_bins: int = 1, peak_max_gap_bins: int = 0, peak_signal_scale: float = 1.0, peak_control_scale: float | None = None, peak_negative: str = 'clip', peak_nolambda: bool = False, project: bool = True, overwrite: bool = False, hash_sources: bool = True, verbose: bool = False)

Bases: object

Optional feature-enrichment inputs for an auto-discovery run.

annotation_features: list[str] | None = None

chroms: list[str] | None = None

device: str = 'auto'

enabled() → bool

Return true when at least one enrichment action is configured.

fasta: str | Path | None = None

gtf: str | Path | None = None

hash_sources: bool = True

overwrite: bool = False

peak_agg: str = 'mean'

peak_control_scale: float | None = None

peak_control_tracks: list[str]

peak_cutoff: float | None = None

peak_fragment_size_bins: int = 1

peak_genome_size: float | None = None

peak_large_local_window_bins: int = 100

peak_max_gap: int = 30

peak_max_gap_bins: int = 0

peak_method: str = 'auto'

peak_min_length: int = 200

peak_min_width_bins: int = 1

peak_negative: str = 'clip'

peak_nolambda: bool = False

peak_pvalue: float | None = None

peak_quantile: float = 0.95

peak_qvalue: float | None = 0.05

peak_signal_scale: float = 1.0

peak_small_local_window_bins: int = 10

peak_threshold: float | None = None

peak_tracks: list[str]

project: bool = True

project_existing_structure: bool = False

promoter_window: tuple[int, int] = (-2000, 500)

sequence_features: list[str] | None = None

structures: list[str]

verbose: bool = False

uchrom.auto_discovery.DiscoveryFrontier

alias of DiscoveryDirection

class uchrom.auto_discovery.DiscoveryIdea(idea_title: str, biological_hypothesis: str, computable_parameter: str, analysis_plan: str, modalities: list[str], idea_markdown: str = '', cell_types: list[str] = <factory>, required_fields: list[str] = <factory>, validation_checks: list[str] = <factory>, expected_direction: str = '', complexity: int = 3, idea_id: str = '', metadata: dict[str, ~typing.Any] = <factory>)

Bases: object

A computable multi-omics discovery idea.

analysis_plan: str

biological_hypothesis: str

cell_types: list[str]

complexity: int = 3

computable_parameter: str

expected_direction: str = ''

classmethod from_dict(data: Mapping[str, Any]) → DiscoveryIdea

get(key: str, default: Any = None) → Any

Return an idea field by name, matching dict.get semantics.

idea_id: str = ''

idea_markdown: str = ''

idea_title: str

metadata: dict[str, Any]

modalities: list[str]

required_fields: list[str]

to_dict(*, include_id: bool = True) → dict[str, Any]

validation_checks: list[str]

class uchrom.auto_discovery.DiscoveryRunConfig(h5cd_path: str | Path, output_dir: str | Path, max_ideas: int = 12, accepted_idea_target: int | None = None, max_generation_attempts: int = 3, ideas_path: str | Path | None = None, max_complexity: int = 5, idea_source: str = 'pantheon', code_source: str = 'pantheon', model: str | None = None, reasoning_effort: str | None = None, llm_timeout: int = 420, idea_agent_count: int = 3, notebook_agent_concurrency: int = 3, generate_schematic_image: bool = False, schematic_image_model: str | None = None, schematic_image_model_args: dict[str, ~typing.Any] | None=None, execute: bool = True, stop_on_error: bool = False, store_schema: bool = False, dataset_name: str | None = None, enrichment: dict[str, ~typing.Any] | None=None, prior_graph_path: str | Path | None = None, direction_context_path: str | Path | None = None, frontier_context_path: str | Path | None = None, claims_paths: list[str | Path] = <factory>)

Bases: object

Configuration for a local auto-discovery run.

accepted_idea_target: int | None = None

claims_paths: list[str | Path]

code_source: str = 'pantheon'

dataset_name: str | None = None

direction_context_path: str | Path | None = None

enrichment: dict[str, Any] | None = None

execute: bool = True

frontier_context_path: str | Path | None = None

generate_schematic_image: bool = False

h5cd_path: str | Path

idea_agent_count: int = 3

idea_source: str = 'pantheon'

ideas_path: str | Path | None = None

llm_timeout: int = 420

max_complexity: int = 5

max_generation_attempts: int = 3

max_ideas: int = 12

model: str | None = None

notebook_agent_concurrency: int = 3

output_dir: str | Path

prior_graph_path: str | Path | None = None

reasoning_effort: str | None = None

schematic_image_model: str | None = None

schematic_image_model_args: dict[str, Any] | None = None

stop_on_error: bool = False

store_schema: bool = False

class uchrom.auto_discovery.DiscoveryRunResult(output_dir: str, n_generated: int, n_accepted: int, n_executed: int, n_verified: int, report_path: str, ideas_path: str, reviews_path: str, results_path: str, notebooks: list[str] = <factory>, agent_records_path: str | None = None, graph_path: str | None = None, graph_summary_path: str | None = None, graph_html_path: str | None = None, directions_path: str | None = None, direction_summary_path: str | None = None, enriched_h5cd_path: str | None = None, enrichment_summary_path: str | None = None)

Bases: object

Summary of an auto-discovery run.

agent_records_path: str | None = None

direction_summary_path: str | None = None

directions_path: str | None = None

enriched_h5cd_path: str | None = None

enrichment_summary_path: str | None = None

property frontier_summary_path: str | None

Legacy alias for direction_summary_path.

property frontiers_path: str | None

Legacy alias for directions_path.

graph_html_path: str | None = None

graph_path: str | None = None

graph_summary_path: str | None = None

ideas_path: str

n_accepted: int

n_executed: int

n_generated: int

n_verified: int

notebooks: list[str]

output_dir: str

report_path: str

results_path: str

reviews_path: str

class uchrom.auto_discovery.EvidenceConclusion(notebook_status: str, hypothesis_status: str, direction_status: str, p_value: float | None, effect_size: float | None, summary: str)

Bases: object

Human-readable evidence classification for one explored idea.

direction_status: str

effect_size: float | None

hypothesis_status: str

notebook_status: str

p_value: float | None

summary: str

class uchrom.auto_discovery.IdeaGraph(graph_id: str = 'idea_graph', nodes: dict[str, dict[str, ~typing.Any]]=<factory>, edges: list[dict[str, ~typing.Any]]=<factory>)

Bases: object

A JSON-serializable graph of discovery ideas and evidence.

add_edge(source: str, relation: str, target: str, **attrs: Any) → dict[str, Any]

Add a typed edge unless the same edge already exists.

add_node(node_id: str, kind: str, **attrs: Any) → dict[str, Any]

Add or update a node and return the stored record.

edges: list[dict[str, Any]]

graph_id: str = 'idea_graph'

nodes: dict[str, dict[str, Any]]

summary() → dict[str, Any]

Return lightweight counts useful for planning and h5cd pointers.

to_dict() → dict[str, Any]

Return a JSON-serializable graph dict.

write_json(path: str | Path) → Path

Write graph JSON to path.

write_summary_markdown(path: str | Path) → Path

Write a human-readable graph summary.

class uchrom.auto_discovery.IdeaReview(accepted: bool, errors: list[str] = <factory>, warnings: list[str] = <factory>, missing_fields: list[str] = <factory>)

Bases: object

Result of reviewing an idea against a discovery schema.

accepted: bool

errors: list[str]

missing_fields: list[str]

to_dict() → dict[str, Any]

warnings: list[str]

class uchrom.auto_discovery.IterativeDiscoveryConfig(h5cd_path: str | Path, output_dir: str | Path, iterations: int = 2, ideas_per_iteration: int = 20, max_generation_attempts: int = 3, seed_run_dirs: list[str | Path] = <factory>, max_complexity: int = 5, idea_source: str = 'pantheon', code_source: str = 'pantheon', model: str | None = None, reasoning_effort: str | None = None, llm_timeout: int = 900, idea_agent_count: int = 4, notebook_agent_concurrency: int = 4, generate_schematic_image: bool = True, schematic_image_model: str | None = None, schematic_image_model_args: dict[str, ~typing.Any] | None=None, execute: bool = True, store_schema: bool = False, dataset_name: str | None = None, enrichment: dict[str, ~typing.Any] | None=None, knowledge_mode: str = 'knowledge_guided', claims_paths: list[str | Path] = <factory>)

Bases: object

Configuration for repeated auto-discovery iterations.

claims_paths: list[str | Path]

code_source: str = 'pantheon'

dataset_name: str | None = None

enrichment: dict[str, Any] | None = None

execute: bool = True

generate_schematic_image: bool = True

h5cd_path: str | Path

idea_agent_count: int = 4

idea_source: str = 'pantheon'

ideas_per_iteration: int = 20

iterations: int = 2

knowledge_mode: str = 'knowledge_guided'

llm_timeout: int = 900

max_complexity: int = 5

max_generation_attempts: int = 3

model: str | None = None

notebook_agent_concurrency: int = 4

output_dir: str | Path

reasoning_effort: str | None = None

schematic_image_model: str | None = None

schematic_image_model_args: dict[str, Any] | None = None

seed_run_dirs: list[str | Path]

store_schema: bool = False

class uchrom.auto_discovery.IterativeDiscoveryResult(output_dir: str, run_dirs: list[str], iteration_results: list[~uchrom.auto_discovery.runner.DiscoveryRunResult], graph_path: str, graph_summary_path: str, directions_path: str, direction_summary_path: str, html_path: str, claim_refresh_results: list[~uchrom.auto_discovery.claims.ClaimRefreshResult] = <factory>)

Bases: object

Summary of a multi-iteration auto-discovery run.

claim_refresh_results: list[ClaimRefreshResult]

direction_summary_path: str

directions_path: str

property frontier_summary_path: str

Legacy alias for direction_summary_path.

property frontiers_path: str

Legacy alias for directions_path.

graph_path: str

graph_summary_path: str

html_path: str

iteration_results: list[DiscoveryRunResult]

output_dir: str

run_dirs: list[str]

to_dict() → dict[str, Any]

Return a JSON-serializable summary.

uchrom.auto_discovery.allowed_required_fields(schema: Mapping[str, Any], *, max_items: int) → list[str]

Return schema field paths that agents may use in required_fields.

uchrom.auto_discovery.analysis_output_schema() → dict[str, Any]

Return the structured-output schema for analysis-code backends.

uchrom.auto_discovery.build_analysis_prompt(*, idea_path: Path, schema_path: Path, context_path: Path, h5cd_path: Path, output_dir: Path) → str

Build the structured analysis-code prompt used by CLI backends.

uchrom.auto_discovery.build_discovery_schema(cdata, *, dataset_name: str | None = None, include_linked_adata: bool = True, max_catalog_items: int = 500) → dict[str, Any]

Build an agent-readable schema from a ChromData object.

The returned dict is JSON-serializable and can be persisted via pack_schema() under cd.uns['auto_discovery_schema'].

uchrom.auto_discovery.build_idea_graph_from_run(run_dir: str | Path, *, graph_id: str | None = None, claims_paths: list[str | Path] | None = None) → IdeaGraph

Build an IdeaGraph from a completed auto-discovery run.

The function reads ideas.jsonl, reviews.jsonl, and results.jsonl when present. Missing files are tolerated so interrupted runs can still produce partial graph snapshots.

uchrom.auto_discovery.build_idea_graph_from_runs(run_dirs: list[str | Path], *, graph_id: str = 'iterative_idea_graph', claims_paths: list[str | Path] | None = None) → IdeaGraph

Build one graph by merging several auto-discovery runs.

uchrom.auto_discovery.build_idea_prompt(schema: Mapping[str, Any], *, max_ideas: int, prior_graph_path: str | Path | None = None, direction_context_path: str | Path | None = None) → str

Build the structured idea-generation prompt used by CLI backends.

uchrom.auto_discovery.build_required_fields_prompt_block(schema: Mapping[str, Any], *, max_items: int = 80) → str

Build the legacy required-field guardrails shared by all idea backends.

uchrom.auto_discovery.classify_hypothesis_evidence(idea: DiscoveryIdea | Mapping[str, Any], verification: Mapping[str, Any] | None, *, alpha: float = 0.05) → EvidenceConclusion

Classify whether a verified notebook supports the biological hypothesis.

verification.status == "pass" means U-Chrom could rerun the notebook and validate required fields, finite outputs, and an explicit statistical test. This function separately classifies the hypothesis evidence from p-value and effect direction so “verified” is not confused with “biologically true”.

uchrom.auto_discovery.create_exploration_notebook(idea: DiscoveryIdea | Mapping[str, Any], output_path: str | Path, *, h5cd_path: str | Path | None = None, run_output_dir: str | Path | None = None, analysis_code: str | None = None, verification_code: str | None = None, kernel_name: str = 'python3') → Path

Create a standard exploration notebook for one idea.

The code agent is expected to edit and execute this notebook freely. The scaffold only defines the audit trail and verification contract.

uchrom.auto_discovery.directions_to_agent_context(directions: list[DiscoveryDirection]) → str

Render directions as a Markdown prompt block for idea agents.

uchrom.auto_discovery.enrich_for_discovery(cdata, config: DiscoveryEnrichmentConfig | dict[str, Any] | None = None, **kwargs) → dict[str, Any]

Apply configured enrichment steps to cdata in place and summarize them.

uchrom.auto_discovery.execute_notebook_python(notebook_path: str | Path, *, stop_on_error: bool = False) → dict[str, Any]

Execute Python code cells in a notebook JSON file.

This lightweight executor is intentionally small: it keeps a shared Python namespace across code cells, captures stdout/stderr/error text, writes outputs back into the notebook, and returns the final namespace entries commonly used by the auto-discovery runner. It is meant for deterministic smoke tests; Pantheon/Jupyter can still execute the same notebooks in richer interactive runs.

uchrom.auto_discovery.frontiers_to_agent_context(frontiers: list[DiscoveryDirection]) → str

Legacy alias for directions_to_agent_context().

async uchrom.auto_discovery.generate_pantheon_ideas(schema: Mapping[str, Any], *, output_dir: str | Path, max_ideas: int, model: str | None = None, timeout: int = 420, idea_agent_count: int = 3, prior_graph_path: str | Path | None = None, direction_context_path: str | Path | None = None, frontier_context_path: str | Path | None = None) → tuple[list[DiscoveryIdea], list[PantheonAgentRecord]]

Generate ideas by running multiple Pantheon idea agents in parallel.

Each idea agent receives only a file-access toolset. The schema and prompt are written to disk, and agents are instructed to read those files before returning DiscoveryIdea-compatible JSON.

uchrom.auto_discovery.get_backend(backend_id: str) → DiscoveryBackend

Return a registered backend or raise a user-facing error.

uchrom.auto_discovery.graph_summary_markdown(graph: IdeaGraph) → str

Render a compact Markdown summary for humans and agents.

uchrom.auto_discovery.idea_output_schema(*, max_ideas: int | None = None) → dict[str, Any]

Return the structured-output schema for idea-generation backends.

uchrom.auto_discovery.idea_signature(idea: DiscoveryIdea | Mapping[str, Any]) → dict[str, Any]

Return structured facets used for novelty and coverage review.

uchrom.auto_discovery.idea_to_markdown(idea: DiscoveryIdea | Mapping[str, Any]) → str

Return a readable Markdown brief for a discovery idea.

uchrom.auto_discovery.infer_parameter_family(idea: DiscoveryIdea | Mapping[str, Any]) → str

Infer a coarse parameter family from idea text.

uchrom.auto_discovery.ingest_literature_claims(graph: IdeaGraph, claims_path: str | Path) → int

Ingest browser-agent literature claims into an IdeaGraph.

claims_path is a JSONL file. Rows may contain claim_id, claim or claim_text, source/source_title, url, doi, pmid, entities/genes, cell_types, markers, modalities, supports_idea_ids, contradicts_idea_ids, and related_idea_ids. Extra keys are kept on the claim node for auditability.

uchrom.auto_discovery.list_backends() → list[str]

Return registered backend ids.

uchrom.auto_discovery.load_idea_graph(path: str | Path) → IdeaGraph

Load an IdeaGraph previously written with write_json.

uchrom.auto_discovery.pack_schema(schema: Mapping[str, Any]) → dict[str, str]

Pack a schema as an HDF5-friendly uns entry.

uchrom.auto_discovery.plan_discovery_directions(graph: IdeaGraph, schema: Mapping[str, Any], *, max_directions: int = 8, min_priority: float = 0.0) → list[DiscoveryDirection]

Plan graph-aware directions for the next auto-discovery iteration.

The planner reads tested idea signatures, hypothesis evidence, and schema catalogs. It then proposes flexible search directions rather than fixed hard-coded buckets. The direction prompts tell idea agents what evidence to build on or what coverage gaps to fill, while still allowing free-form idea generation and notebook exploration.

uchrom.auto_discovery.plan_discovery_frontiers(graph: IdeaGraph, schema: Mapping[str, Any], *, max_frontiers: int = 8, min_priority: float = 0.0) → list[DiscoveryDirection]

Legacy alias for plan_discovery_directions().

uchrom.auto_discovery.refresh_literature_claims_for_iteration(*, run_dir: str | Path, schema: Mapping[str, Any], seed_claim_paths: Sequence[str | Path] | None = None, mode: str = 'knowledge_guided') → ClaimRefreshResult

Materialize per-iteration literature/user claims.

knowledge_guided keeps the run closed to network access and only normalizes existing source-backed claim caches plus h5cd references and user annotations. browser_refresh currently records that a network refresh was requested, then falls back to the same cached behavior; this keeps the iterative orchestrator ready for a real browser worker without silently inventing literature claims.

uchrom.auto_discovery.register_backend(backend: DiscoveryBackend) → None

Register or replace one backend adapter.

uchrom.auto_discovery.review_idea_against_schema(idea: DiscoveryIdea | Mapping[str, Any], schema: Mapping[str, Any], *, min_complexity: int = 1, max_complexity: int = 5) → IdeaReview

Check whether an idea is compatible with a discovery schema.

uchrom.auto_discovery.run_auto_discovery(config: DiscoveryRunConfig | dict[str, Any]) → DiscoveryRunResult

Run schema → idea → notebook → verification for one .h5cd.

uchrom.auto_discovery.run_iterative_auto_discovery(config: IterativeDiscoveryConfig | dict[str, Any]) → IterativeDiscoveryResult

Run several graph-guided discovery iterations.

Each iteration runs ideas_per_iteration ideas. Before iteration 2 and later, the orchestrator builds a cumulative idea graph from seed and prior iteration runs, plans direction prompts, and passes those artifacts to the idea agents.

async uchrom.auto_discovery.run_pantheon_notebook_agents(ideas: Sequence[DiscoveryIdea], *, schema: Mapping[str, Any], h5cd_path: str | Path, output_dir: str | Path, notebooks_dir: str | Path, model: str | None = None, timeout: int = 420, concurrency: int = 3, generate_schematic_image: bool = False, schematic_image_model: str | None = None, schematic_image_model_args: Mapping[str, Any] | None = None) → list[PantheonAgentRecord]

Run notebook exploration agents in parallel for accepted ideas.

The caller is responsible for creating scaffold notebooks first. Each Pantheon notebook agent receives file-access and notebook toolsets, edits its assigned notebook, executes exploration cells, and returns a JSON status summary.

uchrom.auto_discovery.schema_to_agent_context(schema: Mapping[str, Any], *, max_items: int = 40) → str

Render a compact, prompt-ready schema summary.

uchrom.auto_discovery.schematic_coverage_for_run(run_dir: str | Path, *, verified_only: bool = True, max_images: int | None = None) → dict[str, Any]

Return graphical-abstract coverage for a completed discovery run.

uchrom.auto_discovery.structured_conclusion_markdown(idea: DiscoveryIdea | Mapping[str, Any], verification: Mapping[str, Any] | None) → str

Build the standard final interpretation Markdown for a notebook.

uchrom.auto_discovery.unpack_schema(raw: Any) → dict[str, Any]

Unpack a schema from cd.uns['auto_discovery_schema'].

uchrom.auto_discovery.unregister_backend(backend_id: str) → None

Remove a backend adapter if it is registered.

uchrom.auto_discovery.upsert_structured_conclusion(notebook_path: str | Path, idea: DiscoveryIdea | Mapping[str, Any], verification: Mapping[str, Any] | None) → Path

Insert or replace the notebook’s final interpretation with standard text.

uchrom.auto_discovery.validate_discovery_schema(schema: Mapping[str, Any], cdata=None) → list[str]

Return validation issues for a discovery schema.

uchrom.auto_discovery.write_direction_artifacts(directions: list[DiscoveryDirection], output_dir: str | Path, *, json_name: str = 'next_directions.json', markdown_name: str = 'next_directions.md', directory_name: str = 'directions') → dict[str, str]

Write direction JSON and Markdown artifacts into output_dir.

uchrom.auto_discovery.write_frontier_artifacts(frontiers: list[DiscoveryDirection], output_dir: str | Path, *, json_name: str = 'next_frontiers.json', markdown_name: str = 'next_frontiers.md') → dict[str, str]

Legacy writer that preserves the historical artifact keys and path.

uchrom.auto_discovery.write_idea_graph_artifacts(graph: IdeaGraph, output_dir: str | Path, *, json_name: str = 'idea_graph.json', summary_name: str = 'graph_summary.md') → dict[str, str]

Write graph JSON and Markdown summary into a run artifact directory.

uchrom.auto_discovery.write_idea_graph_html(graph: IdeaGraph | str | Path, output_path: str | Path, *, title: str = 'U-Chrom Idea Graph', notebook_base_url: str | None = None) → Path

Write a self-contained Vue-powered interactive idea-graph viewer.

Schema

Agent-readable discovery schema for uchrom.core.ChromData.

The schema is intentionally stored inside cd.uns as a JSON payload so it round-trips through .h5cd without requiring a new HDF5 layout.

uchrom.auto_discovery.schema.build_discovery_schema(cdata, *, dataset_name: str | None = None, include_linked_adata: bool = True, max_catalog_items: int = 500) → dict[str, Any]

Build an agent-readable schema from a ChromData object.

The returned dict is JSON-serializable and can be persisted via pack_schema() under cd.uns['auto_discovery_schema'].

uchrom.auto_discovery.schema.pack_schema(schema: Mapping[str, Any]) → dict[str, str]

Pack a schema as an HDF5-friendly uns entry.

uchrom.auto_discovery.schema.schema_to_agent_context(schema: Mapping[str, Any], *, max_items: int = 40) → str

Render a compact, prompt-ready schema summary.

uchrom.auto_discovery.schema.unpack_schema(raw: Any) → dict[str, Any]

Unpack a schema from cd.uns['auto_discovery_schema'].

uchrom.auto_discovery.schema.validate_discovery_schema(schema: Mapping[str, Any], cdata=None) → list[str]

Return validation issues for a discovery schema.

Ideas

Idea records and schema-based review for auto-discovery.

class uchrom.auto_discovery.ideas.DiscoveryIdea(idea_title: str, biological_hypothesis: str, computable_parameter: str, analysis_plan: str, modalities: list[str], idea_markdown: str = '', cell_types: list[str] = <factory>, required_fields: list[str] = <factory>, validation_checks: list[str] = <factory>, expected_direction: str = '', complexity: int = 3, idea_id: str = '', metadata: dict[str, ~typing.Any] = <factory>)

Bases: object

A computable multi-omics discovery idea.

analysis_plan: str

biological_hypothesis: str

cell_types: list[str]

complexity: int = 3

computable_parameter: str

expected_direction: str = ''

classmethod from_dict(data: Mapping[str, Any]) → DiscoveryIdea

get(key: str, default: Any = None) → Any

Return an idea field by name, matching dict.get semantics.

idea_id: str = ''

idea_markdown: str = ''

idea_title: str

metadata: dict[str, Any]

modalities: list[str]

required_fields: list[str]

to_dict(*, include_id: bool = True) → dict[str, Any]

validation_checks: list[str]

class uchrom.auto_discovery.ideas.IdeaReview(accepted: bool, errors: list[str] = <factory>, warnings: list[str] = <factory>, missing_fields: list[str] = <factory>)

Bases: object

Result of reviewing an idea against a discovery schema.

accepted: bool

errors: list[str]

missing_fields: list[str]

to_dict() → dict[str, Any]

warnings: list[str]

uchrom.auto_discovery.ideas.review_idea_against_schema(idea: DiscoveryIdea | Mapping[str, Any], schema: Mapping[str, Any], *, min_complexity: int = 1, max_complexity: int = 5) → IdeaReview

Check whether an idea is compatible with a discovery schema.

uchrom.auto_discovery.ideas.stable_idea_id(idea: Mapping[str, Any]) → str

Return a stable short id for an idea dict.

Prompt contracts

Provider-agnostic prompt builders for U-Chrom auto-discovery.

uchrom.auto_discovery.llm.allowed_required_fields(schema: Mapping[str, Any], *, max_items: int) → list[str]

Return schema field paths that agents may use in required_fields.

uchrom.auto_discovery.llm.analysis_output_schema() → dict[str, Any]

Return the structured-output schema for analysis-code backends.

uchrom.auto_discovery.llm.build_analysis_prompt(*, idea_path: Path, schema_path: Path, context_path: Path, h5cd_path: Path, output_dir: Path) → str

Build the structured analysis-code prompt used by CLI backends.

uchrom.auto_discovery.llm.build_idea_prompt(schema: Mapping[str, Any], *, max_ideas: int, prior_graph_path: str | Path | None = None, direction_context_path: str | Path | None = None) → str

Build the structured idea-generation prompt used by CLI backends.

uchrom.auto_discovery.llm.build_required_fields_prompt_block(schema: Mapping[str, Any], *, max_items: int = 80) → str

Build the legacy required-field guardrails shared by all idea backends.

uchrom.auto_discovery.llm.idea_output_schema(*, max_ideas: int | None = None) → dict[str, Any]

Return the structured-output schema for idea-generation backends.

Backend adapters

Backend adapters for U-Chrom auto-discovery.

Backends may use CLI agents and scratch files internally, but the runner owns the final notebook lifecycle. Adapter outputs are normalized into structured Python objects that the runner can audit, write, execute, and verify.

class uchrom.auto_discovery.backends.AnalysisCodeResult(analysis_code: str, agent_records: list[BackendAgentRecord] = <factory>, extra_cells: list[dict[str, ~typing.Any]]=<factory>, artifact_manifest: list[dict[str, ~typing.Any]]=<factory>, warnings: list[str] = <factory>, notes: list[str] = <factory>)

Bases: object

Structured analysis code returned by a backend.

agent_records: list[BackendAgentRecord]

analysis_code: str

artifact_manifest: list[dict[str, Any]]

extra_cells: list[dict[str, Any]]

notes: list[str]

warnings: list[str]

class uchrom.auto_discovery.backends.BackendAgentRecord(agent_name: str, role: str, prompt_path: str, content: Any)

Bases: object

Audit record for one backend invocation.

agent_name: str

content: Any

prompt_path: str

role: str

class uchrom.auto_discovery.backends.BackendCapabilities(structured_output: bool, file_workspace: bool, prompt_via_stdin: bool, streaming: bool, native_skill_loading: bool = False, resume: bool = False, owns_notebook_lifecycle: bool = False)

Bases: object

Capabilities reported by an auto-discovery backend.

file_workspace: bool

native_skill_loading: bool = False

owns_notebook_lifecycle: bool = False

prompt_via_stdin: bool

resume: bool = False

streaming: bool

structured_output: bool

class uchrom.auto_discovery.backends.BackendDetection(backend_id: str, executable_path: str | None, version: str | None = None, available: bool = False, auth_state: str = 'unknown', error: str | None = None, cli_flags: Mapping[str, bool]=<factory>)

Bases: object

Best-effort local CLI detection result.

auth_state: str = 'unknown'

available: bool = False

backend_id: str

cli_flags: Mapping[str, bool]

error: str | None = None

executable_path: str | None

version: str | None = None

exception uchrom.auto_discovery.backends.BackendError(message: str, *, category: str, retryable: bool)

Bases: RuntimeError

A classified backend failure.

category is one of backend_unavailable (missing/exited binary or an auth failure that a retry will not fix), failed (ran but exited non-zero for another reason), bad_output (ran but produced output that could not be parsed), or timeout. retryable tells the run loop whether a transient retry is worthwhile.

class uchrom.auto_discovery.backends.CLIBackend(spec: CLISpec)

Bases: object

Generic adapter for stdin-driven coding-agent CLIs, driven by a spec.

capabilities() → BackendCapabilities

detect() → BackendDetection

generate_analysis_code(idea: DiscoveryIdea, schema: Mapping[str, Any], *, output_dir: str | Path, h5cd_path: str | Path, model: str | None = None, reasoning_effort: str | None = None, timeout: int = 420) → AnalysisCodeResult

generate_ideas(schema: Mapping[str, Any], *, output_dir: str | Path, max_ideas: int, model: str | None = None, reasoning_effort: str | None = None, timeout: int = 420, idea_agent_count: int = 1, prior_graph_path: str | Path | None = None, direction_context_path: str | Path | None = None) → tuple[list[DiscoveryIdea], list[BackendAgentRecord]]

class uchrom.auto_discovery.backends.CLISpec(backend_id: str, display_name: str, executable: str, build_command: Any, stream_format: str, run_environment: Any = <function _default_run_environment>, fallback_bins: tuple[str, ...]=(), capability_probe: Mapping[str, str]=<factory>)

Bases: object

Data describing one stdin-driven coding-agent CLI backend.

Per-CLI differences are expressed as data here rather than as subclass overrides, mirroring open-design’s data-driven adapter model: the generic CLIBackend consumes a spec and the core never branches on backend id.

backend_id: str

build_command: Any

capability_probe: Mapping[str, str]

display_name: str

executable: str

fallback_bins: tuple[str, ...] = ()

run_environment() → Iterator[dict[str, str]]

stream_format: str

class uchrom.auto_discovery.backends.ClaudeBackend

Bases: CLIBackend

Claude Code CLI adapter (thin spec-backed wrapper).

class uchrom.auto_discovery.backends.CodexBackend

Bases: CLIBackend

Codex CLI adapter (thin spec-backed wrapper).

class uchrom.auto_discovery.backends.DiscoveryBackend(*args, **kwargs)

Bases: Protocol

Protocol implemented by all auto-discovery backends.

backend_id: str

capabilities() → BackendCapabilities

detect() → BackendDetection

display_name: str

generate_analysis_code(idea: DiscoveryIdea, schema: Mapping[str, Any], *, output_dir: str | Path, h5cd_path: str | Path, model: str | None = None, reasoning_effort: str | None = None, timeout: int = 420) → AnalysisCodeResult

generate_ideas(schema: Mapping[str, Any], *, output_dir: str | Path, max_ideas: int, model: str | None = None, reasoning_effort: str | None = None, timeout: int = 420, idea_agent_count: int = 1, prior_graph_path: str | Path | None = None, direction_context_path: str | Path | None = None) → tuple[list[DiscoveryIdea], list[BackendAgentRecord]]

class uchrom.auto_discovery.backends.PantheonBackend

Bases: object

Adapter around the existing Pantheon implementation.

backend_id = 'pantheon'

capabilities() → BackendCapabilities

detect() → BackendDetection

display_name = 'PantheonOS'

generate_analysis_code(idea: DiscoveryIdea, schema: Mapping[str, Any], **kwargs: Any) → AnalysisCodeResult

generate_ideas(schema: Mapping[str, Any], **kwargs: Any) → tuple[list[DiscoveryIdea], list[BackendAgentRecord]]

uchrom.auto_discovery.backends.extract_structured_json(text: str) → dict[str, Any]

Extract the first structured JSON object from backend text.

uchrom.auto_discovery.backends.get_backend(backend_id: str) → DiscoveryBackend

Return a registered backend or raise a user-facing error.

uchrom.auto_discovery.backends.list_backends() → list[str]

Return registered backend ids.

uchrom.auto_discovery.backends.register_backend(backend: DiscoveryBackend) → None

Register or replace one backend adapter.

uchrom.auto_discovery.backends.unregister_backend(backend_id: str) → None

Remove a backend adapter if it is registered.

Notebooks

Notebook scaffolding for auto-discovery idea exploration.

uchrom.auto_discovery.notebooks.create_exploration_notebook(idea: DiscoveryIdea | Mapping[str, Any], output_path: str | Path, *, h5cd_path: str | Path | None = None, run_output_dir: str | Path | None = None, analysis_code: str | None = None, verification_code: str | None = None, kernel_name: str = 'python3') → Path

Create a standard exploration notebook for one idea.

The code agent is expected to edit and execute this notebook freely. The scaffold only defines the audit trail and verification contract.

uchrom.auto_discovery.notebooks.execute_notebook_python(notebook_path: str | Path, *, stop_on_error: bool = False) → dict[str, Any]

Execute Python code cells in a notebook JSON file.

This lightweight executor is intentionally small: it keeps a shared Python namespace across code cells, captures stdout/stderr/error text, writes outputs back into the notebook, and returns the final namespace entries commonly used by the auto-discovery runner. It is meant for deterministic smoke tests; Pantheon/Jupyter can still execute the same notebooks in richer interactive runs.

uchrom.auto_discovery.notebooks.idea_to_markdown(idea: DiscoveryIdea | Mapping[str, Any]) → str

Return a readable Markdown brief for a discovery idea.

uchrom.auto_discovery.notebooks.upsert_structured_conclusion(notebook_path: str | Path, idea: DiscoveryIdea | Mapping[str, Any], verification: Mapping[str, Any] | None) → Path

Insert or replace the notebook’s final interpretation with standard text.

Idea graph

Lightweight idea graph for iterative auto-discovery.

The graph is intentionally stored as plain JSON-friendly nodes and edges so it can be written to run directories without adding a hard graph dependency. It is the shared memory layer between discovery iterations: ideas, reviews, notebook runs, evidence, data facets, and source priors are represented as typed nodes with explicit relationships.

class uchrom.auto_discovery.graph.IdeaGraph(graph_id: str = 'idea_graph', nodes: dict[str, dict[str, ~typing.Any]]=<factory>, edges: list[dict[str, ~typing.Any]]=<factory>)

Bases: object

A JSON-serializable graph of discovery ideas and evidence.

add_edge(source: str, relation: str, target: str, **attrs: Any) → dict[str, Any]

Add a typed edge unless the same edge already exists.

add_node(node_id: str, kind: str, **attrs: Any) → dict[str, Any]

Add or update a node and return the stored record.

edges: list[dict[str, Any]]

graph_id: str = 'idea_graph'

nodes: dict[str, dict[str, Any]]

summary() → dict[str, Any]

Return lightweight counts useful for planning and h5cd pointers.

to_dict() → dict[str, Any]

Return a JSON-serializable graph dict.

write_json(path: str | Path) → Path

Write graph JSON to path.

write_summary_markdown(path: str | Path) → Path

Write a human-readable graph summary.

uchrom.auto_discovery.graph.build_idea_graph_from_run(run_dir: str | Path, *, graph_id: str | None = None, claims_paths: list[str | Path] | None = None) → IdeaGraph

Build an IdeaGraph from a completed auto-discovery run.

The function reads ideas.jsonl, reviews.jsonl, and results.jsonl when present. Missing files are tolerated so interrupted runs can still produce partial graph snapshots.

uchrom.auto_discovery.graph.build_idea_graph_from_runs(run_dirs: list[str | Path], *, graph_id: str = 'iterative_idea_graph', claims_paths: list[str | Path] | None = None) → IdeaGraph

Build one graph by merging several auto-discovery runs.

uchrom.auto_discovery.graph.graph_summary_markdown(graph: IdeaGraph) → str

Render a compact Markdown summary for humans and agents.

uchrom.auto_discovery.graph.idea_signature(idea: DiscoveryIdea | Mapping[str, Any]) → dict[str, Any]

Return structured facets used for novelty and coverage review.

uchrom.auto_discovery.graph.infer_parameter_family(idea: DiscoveryIdea | Mapping[str, Any]) → str

Infer a coarse parameter family from idea text.

uchrom.auto_discovery.graph.ingest_literature_claims(graph: IdeaGraph, claims_path: str | Path) → int

Ingest browser-agent literature claims into an IdeaGraph.

claims_path is a JSONL file. Rows may contain claim_id, claim or claim_text, source/source_title, url, doi, pmid, entities/genes, cell_types, markers, modalities, supports_idea_ids, contradicts_idea_ids, and related_idea_ids. Extra keys are kept on the claim node for auditability.

uchrom.auto_discovery.graph.load_idea_graph(path: str | Path) → IdeaGraph

Load an IdeaGraph previously written with write_json.

uchrom.auto_discovery.graph.write_idea_graph_artifacts(graph: IdeaGraph, output_dir: str | Path, *, json_name: str = 'idea_graph.json', summary_name: str = 'graph_summary.md') → dict[str, str]

Write graph JSON and Markdown summary into a run artifact directory.

Iterative follow-up directions

The module name keeps the original internal term frontier for API compatibility, while the graph viewer presents these records as follow-up directions.

Backward-compatible aliases for the renamed direction planner.

uchrom.auto_discovery.frontier.frontiers_to_agent_context(frontiers: list[DiscoveryDirection]) → str

Legacy alias for directions_to_agent_context().

uchrom.auto_discovery.frontier.plan_discovery_frontiers(graph: IdeaGraph, schema: Mapping[str, Any], *, max_frontiers: int = 8, min_priority: float = 0.0) → list[DiscoveryDirection]

Legacy alias for plan_discovery_directions().

uchrom.auto_discovery.frontier.write_frontier_artifacts(frontiers: list[DiscoveryDirection], output_dir: str | Path, *, json_name: str = 'next_frontiers.json', markdown_name: str = 'next_frontiers.md') → dict[str, str]

Legacy writer that preserves the historical artifact keys and path.

Iterative orchestration

Multi-iteration orchestration for U-Chrom auto-discovery.

class uchrom.auto_discovery.iterative.IterativeDiscoveryConfig(h5cd_path: str | Path, output_dir: str | Path, iterations: int = 2, ideas_per_iteration: int = 20, max_generation_attempts: int = 3, seed_run_dirs: list[str | Path] = <factory>, max_complexity: int = 5, idea_source: str = 'pantheon', code_source: str = 'pantheon', model: str | None = None, reasoning_effort: str | None = None, llm_timeout: int = 900, idea_agent_count: int = 4, notebook_agent_concurrency: int = 4, generate_schematic_image: bool = True, schematic_image_model: str | None = None, schematic_image_model_args: dict[str, ~typing.Any] | None=None, execute: bool = True, store_schema: bool = False, dataset_name: str | None = None, enrichment: dict[str, ~typing.Any] | None=None, knowledge_mode: str = 'knowledge_guided', claims_paths: list[str | Path] = <factory>)

Bases: object

Configuration for repeated auto-discovery iterations.

claims_paths: list[str | Path]

code_source: str = 'pantheon'

dataset_name: str | None = None

enrichment: dict[str, Any] | None = None

execute: bool = True

generate_schematic_image: bool = True

h5cd_path: str | Path

idea_agent_count: int = 4

idea_source: str = 'pantheon'

ideas_per_iteration: int = 20

iterations: int = 2

knowledge_mode: str = 'knowledge_guided'

llm_timeout: int = 900

max_complexity: int = 5

max_generation_attempts: int = 3

model: str | None = None

notebook_agent_concurrency: int = 4

output_dir: str | Path

reasoning_effort: str | None = None

schematic_image_model: str | None = None

schematic_image_model_args: dict[str, Any] | None = None

seed_run_dirs: list[str | Path]

store_schema: bool = False

class uchrom.auto_discovery.iterative.IterativeDiscoveryResult(output_dir: str, run_dirs: list[str], iteration_results: list[~uchrom.auto_discovery.runner.DiscoveryRunResult], graph_path: str, graph_summary_path: str, directions_path: str, direction_summary_path: str, html_path: str, claim_refresh_results: list[~uchrom.auto_discovery.claims.ClaimRefreshResult] = <factory>)

Bases: object

Summary of a multi-iteration auto-discovery run.

claim_refresh_results: list[ClaimRefreshResult]

direction_summary_path: str

directions_path: str

property frontier_summary_path: str

Legacy alias for direction_summary_path.

property frontiers_path: str

Legacy alias for directions_path.

graph_path: str

graph_summary_path: str

html_path: str

iteration_results: list[DiscoveryRunResult]

output_dir: str

run_dirs: list[str]

to_dict() → dict[str, Any]

Return a JSON-serializable summary.

uchrom.auto_discovery.iterative.run_iterative_auto_discovery(config: IterativeDiscoveryConfig | dict[str, Any]) → IterativeDiscoveryResult

Run several graph-guided discovery iterations.

Each iteration runs ideas_per_iteration ideas. Before iteration 2 and later, the orchestrator builds a cumulative idea graph from seed and prior iteration runs, plans direction prompts, and passes those artifacts to the idea agents.

Graph visualization

HTML visualization entrypoint for U-Chrom idea graphs.

uchrom.auto_discovery.visualization.write_idea_graph_html(graph: IdeaGraph | str | Path, output_path: str | Path, *, title: str = 'U-Chrom Idea Graph', notebook_base_url: str | None = None) → Path

Write a self-contained Vue-powered interactive idea-graph viewer.

Runner

Runnable auto-discovery pipeline for ChromData.

class uchrom.auto_discovery.runner.DiscoveryRunConfig(h5cd_path: str | Path, output_dir: str | Path, max_ideas: int = 12, accepted_idea_target: int | None = None, max_generation_attempts: int = 3, ideas_path: str | Path | None = None, max_complexity: int = 5, idea_source: str = 'pantheon', code_source: str = 'pantheon', model: str | None = None, reasoning_effort: str | None = None, llm_timeout: int = 420, idea_agent_count: int = 3, notebook_agent_concurrency: int = 3, generate_schematic_image: bool = False, schematic_image_model: str | None = None, schematic_image_model_args: dict[str, ~typing.Any] | None=None, execute: bool = True, stop_on_error: bool = False, store_schema: bool = False, dataset_name: str | None = None, enrichment: dict[str, ~typing.Any] | None=None, prior_graph_path: str | Path | None = None, direction_context_path: str | Path | None = None, frontier_context_path: str | Path | None = None, claims_paths: list[str | Path] = <factory>)

Bases: object

Configuration for a local auto-discovery run.

accepted_idea_target: int | None = None

claims_paths: list[str | Path]

code_source: str = 'pantheon'

dataset_name: str | None = None

direction_context_path: str | Path | None = None

enrichment: dict[str, Any] | None = None

execute: bool = True

frontier_context_path: str | Path | None = None

generate_schematic_image: bool = False

h5cd_path: str | Path

idea_agent_count: int = 3

idea_source: str = 'pantheon'

ideas_path: str | Path | None = None

llm_timeout: int = 420

max_complexity: int = 5

max_generation_attempts: int = 3

max_ideas: int = 12

model: str | None = None

notebook_agent_concurrency: int = 3

output_dir: str | Path

prior_graph_path: str | Path | None = None

reasoning_effort: str | None = None

schematic_image_model: str | None = None

schematic_image_model_args: dict[str, Any] | None = None

stop_on_error: bool = False

store_schema: bool = False

class uchrom.auto_discovery.runner.DiscoveryRunResult(output_dir: str, n_generated: int, n_accepted: int, n_executed: int, n_verified: int, report_path: str, ideas_path: str, reviews_path: str, results_path: str, notebooks: list[str] = <factory>, agent_records_path: str | None = None, graph_path: str | None = None, graph_summary_path: str | None = None, graph_html_path: str | None = None, directions_path: str | None = None, direction_summary_path: str | None = None, enriched_h5cd_path: str | None = None, enrichment_summary_path: str | None = None)

Bases: object

Summary of an auto-discovery run.

agent_records_path: str | None = None

direction_summary_path: str | None = None

directions_path: str | None = None

enriched_h5cd_path: str | None = None

enrichment_summary_path: str | None = None

property frontier_summary_path: str | None

Legacy alias for direction_summary_path.

property frontiers_path: str | None

Legacy alias for directions_path.

graph_html_path: str | None = None

graph_path: str | None = None

graph_summary_path: str | None = None

ideas_path: str

n_accepted: int

n_executed: int

n_generated: int

n_verified: int

notebooks: list[str]

output_dir: str

report_path: str

results_path: str

reviews_path: str

uchrom.auto_discovery.runner.run_auto_discovery(config: DiscoveryRunConfig | dict[str, Any]) → DiscoveryRunResult

Run schema → idea → notebook → verification for one .h5cd.

PantheonOS backend

PantheonOS-backed auto-discovery orchestration.

class uchrom.auto_discovery.pantheon.PantheonAgentRecord(agent_name: str, role: str, prompt_path: str, content: Any)

Bases: object

Audit record for one Pantheon agent call.

agent_name: str

content: Any

prompt_path: str

role: str

class uchrom.auto_discovery.pantheon.PantheonSchematicRecord(idea_id: str, notebook: str, prompt_path: str, image_path: str | None, status: str, model: str | None = None, attempt: int = 1, visual_qa: Any = None, error: str | None = None)

Bases: object

Audit record for one post-hoc Pantheon schematic generation.

attempt: int = 1

error: str | None = None

idea_id: str

image_path: str | None

model: str | None = None

notebook: str

prompt_path: str

status: str

visual_qa: Any = None

async uchrom.auto_discovery.pantheon.generate_pantheon_ideas(schema: Mapping[str, Any], *, output_dir: str | Path, max_ideas: int, model: str | None = None, timeout: int = 420, idea_agent_count: int = 3, prior_graph_path: str | Path | None = None, direction_context_path: str | Path | None = None, frontier_context_path: str | Path | None = None) → tuple[list[DiscoveryIdea], list[PantheonAgentRecord]]

Generate ideas by running multiple Pantheon idea agents in parallel.

Each idea agent receives only a file-access toolset. The schema and prompt are written to disk, and agents are instructed to read those files before returning DiscoveryIdea-compatible JSON.

async uchrom.auto_discovery.pantheon.generate_pantheon_schematic_images_for_run(run_dir: str | Path, *, model: str | None = None, model_args: Mapping[str, Any] | None = None, timeout: int = 420, concurrency: int = 1, max_images: int | None = None, verified_only: bool = True, force: bool = False, visual_qa: bool = False, retries: int = 2, strict: bool = False) → list[PantheonSchematicRecord]

Generate and insert graphical abstracts for a completed discovery run.

This is intentionally separate from notebook execution. Image generation is slow and provider-dependent, so completed/verified notebooks can be exported quickly first and then decorated with generated schematics in a bounded pass.

async uchrom.auto_discovery.pantheon.run_pantheon_notebook_agents(ideas: Sequence[DiscoveryIdea], *, schema: Mapping[str, Any], h5cd_path: str | Path, output_dir: str | Path, notebooks_dir: str | Path, model: str | None = None, timeout: int = 420, concurrency: int = 3, generate_schematic_image: bool = False, schematic_image_model: str | None = None, schematic_image_model_args: Mapping[str, Any] | None = None) → list[PantheonAgentRecord]

Run notebook exploration agents in parallel for accepted ideas.

The caller is responsible for creating scaffold notebooks first. Each Pantheon notebook agent receives file-access and notebook toolsets, edits its assigned notebook, executes exploration cells, and returns a JSON status summary.

uchrom.auto_discovery.pantheon.schematic_coverage_for_run(run_dir: str | Path, *, verified_only: bool = True, max_images: int | None = None) → dict[str, Any]

Return graphical-abstract coverage for a completed discovery run.