compass.pipeline.jurisdiction.SingleJurisdictionRun#

class SingleJurisdictionRun(runtime, jurisdiction, extractor, *, usage_tracker=None, known_local_docs=None, known_doc_urls=None, known_se_results=None, perform_se_search=True, perform_website_search=True, num_search_results_to_crawl=0)[source]#

Bases: object

Application service that orchestrates one jurisdiction run

Parameters:

runtime (compass.pipeline.runtime.PipelineRuntime) – Runtime context containing shared services, concurrency controls, output directories, and request settings for the current pipeline run.
jurisdiction (compass.utilities.jurisdictions.Jurisdiction) – Jurisdiction to process, including identifying metadata such as its full name, code, and website URL.
extractor (compass.plugin.base.BaseExtractionPlugin) – Configured extraction plugin instance responsible for parsing collected documents and persisting structured output for this jurisdiction.
usage_tracker (LLMUsageTracker, optional) – Optional tracker instance used to accumulate token usage and cost information for LLM calls made during the jurisdiction workflow. By default, None.
known_local_docs (list of dict, optional) – Optional local document descriptors that should be seeded into collection for this jurisdiction before any search or crawl steps are run. By default, None.
known_doc_urls (list of dict, optional) – Optional URL-based document descriptors that should be seeded into collection for this jurisdiction before any search or crawl steps are run. By default, None.
known_se_results (list of dict, optional) – Optional search engine result descriptors that should be seeded into collection for this jurisdiction before any search or crawl steps are run. By default, None.
perform_se_search (bool, optional) – Whether search-engine-driven discovery should be performed for this jurisdiction. By default, True.
perform_website_search (bool, optional) – Whether website-specific search and crawl steps should be performed for this jurisdiction. By default, True.
num_search_results_to_crawl (int, default 0) – Number of ranked search results to inspect for HTML crawl seeds. PDF results count toward this limit but are not crawled. Zero disables the extra crawl. By default, 0.

Methods

`collect`()	Run collection mode for one jurisdiction
`extract_from_collection_info`(collection_info)	Run extraction mode for one jurisdiction
`load_existing_collection_shard`()	Load saved collection shard, if any
`process`()	Run process mode for one jurisdiction
`reset_collection_shard`()	Reset this jurisdiction's collection checkpoint metadata
`run_collection_with_logging`()	Collect one jurisdiction under location-scoped logging
`run_extraction_with_logging`(collection_info)	Extract one jurisdiction under location-scoped logging
`run_process_with_logging`()	Run one jurisdiction under location-scoped logging
`run_search_with_logging`()	Search one jurisdiction under location-scoped logging
`search`()	Run search-only mode for one jurisdiction
`write_collection_shard_no_fail`(docs, ...)	Safely write a collection manifest shard

Attributes

perform_search_based_crawl

Determine if search-based crawl should be performed

property perform_search_based_crawl#: Determine if search-based crawl should be performed

async process()[source]#

Run process mode for one jurisdiction

Returns:: compass.pipeline.data_classes.JurisdictionResult – The result of running the jurisdiction, including any structured data found and related information.

async search()[source]#

Run search-only mode for one jurisdiction

Returns:: dict – Ranked search results and jurisdiction metadata.

async collect()[source]#

Run collection mode for one jurisdiction

Returns:: dict – A dictionary containing collection information, including the jurisdiction’s full name, county, state, subdivision, type, FIPS code, and a list of collected documents with their associated metadata.

async extract_from_collection_info(collection_info)[source]#

Run extraction mode for one jurisdiction

Parameters:: collection_info (dict) – Dictionary containing information about the collected documents for the jurisdiction, including the jurisdiction’s full name, county, state, subdivision, type, FIPS code, and a list of collected documents with their associated metadata.
Returns:: compass.pipeline.data_classes.JurisdictionResult – The result of running the jurisdiction, including any structured data found and related information.

async run_process_with_logging()[source]#

Run one jurisdiction under location-scoped logging

Returns:: compass.pipeline.data_classes.JurisdictionResult – The result of running the jurisdiction, including any structured data found and related information.

async run_search_with_logging()[source]#

Search one jurisdiction under location-scoped logging

Returns:: dict or None – Ranked results, or None if the workflow failed.

async run_collection_with_logging()[source]#

Collect one jurisdiction under location-scoped logging

Returns:: dict – A dictionary containing collection information, including the jurisdiction’s full name, county, state, subdivision, type, FIPS code, and a list of collected documents with their associated metadata.

async run_extraction_with_logging(collection_info)[source]#

Extract one jurisdiction under location-scoped logging

Parameters:: collection_info (dict) – Dictionary containing information about the collected documents for the jurisdiction, including the jurisdiction’s full name, county, state, subdivision, type, FIPS code, and a list of collected documents with their associated metadata.
Returns:: compass.pipeline.data_classes.JurisdictionResult – The result of running the jurisdiction, including any structured data found and related information.

async write_collection_shard_no_fail(docs, completed_steps)[source]#

Safely write a collection manifest shard

Parameters:

docs (dict) – Dictionary where values are documents obtained from the collection step.
completed_steps (Iterable of str) – Iterable of collection step names completed during collection.

Returns:

dict – A dictionary containing collection information, including the jurisdiction’s full name, county, state, subdivision, type, FIPS code, and a list of collected documents with their associated metadata.

Raises:

Exception – If writing the collection manifest shard fails, the exception will be logged and no shard will be written.

async load_existing_collection_shard()[source]#

Load saved collection shard, if any

Returns:: dict or None – A dictionary containing collection information, including the jurisdiction’s full name, county, state, subdivision, type, FIPS code, and a list of collected documents with their associated metadata, or None if no shard exists.

async reset_collection_shard()[source]#

Reset this jurisdiction’s collection checkpoint metadata

Saved source and parsed files are not removed.