python-api.md

Python Implementation Reference

Generated inventory: 23 modules and 211 class/function/method declarations.

Modules

Module	Lines	Declarations	Responsibility
flyto_blueprint/__init__.py:1	22	1	flyto-blueprint — Self-evolving workflow pattern engine.
flyto_blueprint/availability.py:1	169	7	Host-supplied module availability gating for blueprints.
flyto_blueprint/benchmark.py:1	1700	42	Reproducible scorecards for host-executed Blueprint benchmarks.
flyto_blueprint/compose.py:1	307	6	Compose block expansion for blueprints.
flyto_blueprint/engine.py:1	384	15	BlueprintEngine — orchestrator for loading, searching, expanding, and evolving blueprints.
flyto_blueprint/execution_verification.py:1	152	3	Validate host-supplied execution-verification receipts.
flyto_blueprint/fingerprint.py:1	21	1	Structural fingerprinting for blueprint deduplication.
flyto_blueprint/intent.py:1	1003	48	Intent-based blueprint matcher — system-level routing that replaces prompt reliance.
flyto_blueprint/learn.py:1	257	4	Learn reusable blueprints from concrete workflows.
flyto_blueprint/loader.py:1	61	2	YAML loader for builtin blueprints and compose blocks.
flyto_blueprint/longitudinal.py:1	402	10	Real SQLite evidence for the complete Blueprint learning lifecycle.
flyto_blueprint/models.py:1	67	3	Pydantic models for blueprints.
flyto_blueprint/scoring.py:1	478	11	Blueprint scoring: outcome reporting, boosting, use tracking, auto-retire.
flyto_blueprint/search.py:1	166	5	Blueprint listing and search with relevance+quality blending + synonym expansion.
flyto_blueprint/sharing.py:1	311	10	Portable, integrity-checked Blueprint bundles for explicit sharing.
flyto_blueprint/storage/__init__.py:1	6	0	Internal package module.
flyto_blueprint/storage/base.py:1	51	7	Abstract storage backend for blueprints.
flyto_blueprint/storage/firestore.py:1	79	10	Google Firestore storage backend for blueprints (flyto-cloud adapter).
flyto_blueprint/storage/memory.py:1	51	8	In-memory storage backend for tests and ephemeral use.
flyto_blueprint/storage/sqlite.py:1	171	11	SQLite storage backend for blueprints.
flyto_blueprint/template.py:1	103	4	Template substitution for {{arg}} placeholders.
flyto_blueprint/tools.py:1	153	1	MCP tool definitions for blueprint operations.
flyto_blueprint/validate.py:1	48	2	Optional flyto-core module validation for expanded steps.

flyto_blueprint/__init__.py

Kind	Signature	Responsibility	Source
function	def get_engine(storage: StorageBackend=None) -> BlueprintEngine	Get or create the default BlueprintEngine singleton. On first call, storage sets the backend. Subsequent calls return the same instance regardless of the storage argument.	flyto_blueprint/__init__.py:13

flyto_blueprint/availability.py

Kind	Signature	Responsibility	Source
function	def normalize_available_module_ids(available_module_ids: Optional[Iterable[str]]) -> Optional[FrozenSet[str]]	Normalize host input to one frozen set; None means "not supplied". Raises TypeError for a str/bytes-like or non-iterable input and for a non-string entry, and ValueError for a blank or whitespace-padded entry.	flyto_blueprint/availability.py:23
function	def step_module_ids(steps: Iterable[dict]) -> List[str]	Return ordered, unique module IDs of steps without step parameters.	flyto_blueprint/availability.py:83
function	def _gated_steps(bp: dict, blocks: Optional[Dict[str, dict]]) -> List[dict]	Return the composition block steps and own steps of a blueprint.	flyto_blueprint/availability.py:98
function	def required_module_ids(bp: dict, blocks: Optional[Dict[str, dict]]=None, args: Optional[dict]=None) -> List[str]	Return ordered, unique module IDs a blueprint needs in order to expand.	flyto_blueprint/availability.py:109
function	def missing_module_ids(bp: dict, available_module_ids: Optional[FrozenSet[str]], blocks: Optional[Dict[str, dict]]=None, args: Optional[dict]=None) -> List[str]	Return the sorted required module IDs the host cannot provide.	flyto_blueprint/availability.py:132
function	def is_blueprint_available(bp: dict, available_module_ids: Optional[FrozenSet[str]], blocks: Optional[Dict[str, dict]]=None) -> bool	Return whether every module required by bp is available on the host.	flyto_blueprint/availability.py:151
function	def module_unavailable_error(blueprint_id: str, missing: List[str]) -> dict	Build the deterministic module-availability failure for expand.	flyto_blueprint/availability.py:160

flyto_blueprint/benchmark.py

Kind	Signature	Responsibility	Source
class	class BenchmarkValidationError(ValueError)	Raised when benchmark evidence is malformed or cannot be compared.	flyto_blueprint/benchmark.py:149
class	class _UniqueKeyLoader(yaml.SafeLoader)	Safe YAML loader that rejects ambiguous duplicate mapping keys.	flyto_blueprint/benchmark.py:153
function	def _construct_unique_mapping(loader: _UniqueKeyLoader, node: yaml.MappingNode, deep: bool=False) -> dict	See the linked implementation.	flyto_blueprint/benchmark.py:157
function	def canonical_digest(value: Any) -> str	Return a stable SHA-256 digest for JSON-compatible data.	flyto_blueprint/benchmark.py:182
function	def task_digest(task: Mapping[str, Any]) -> str	Return the public task digest or an opaque sealed-task commitment.	flyto_blueprint/benchmark.py:194
function	def suite_digest(suite: Mapping[str, Any]) -> str	Validate and bind a benchmark suite to its exact contents.	flyto_blueprint/benchmark.py:210
function	def load_suite(path: str | Path) -> dict	Load and validate a versioned YAML benchmark suite.	flyto_blueprint/benchmark.py:216
function	def load_runs(path: str | Path) -> list[dict]	Load benchmark-run.v1 JSON objects from a JSON Lines file.	flyto_blueprint/benchmark.py:229
function	def validate_suite(suite: Mapping[str, Any]) -> None	Reject ambiguous suites before any score is calculated.	flyto_blueprint/benchmark.py:258
function	def _validate_measurement(measurement: Mapping[str, Any]) -> None	See the linked implementation.	flyto_blueprint/benchmark.py:344
function	def describe_suite(suite: Mapping[str, Any]) -> dict	Return the identities a host must copy into raw run records.	flyto_blueprint/benchmark.py:385
function	def build_scorecard(suite: Mapping[str, Any], raw_records: Sequence[Mapping[str, Any]]) -> dict	Validate paired evidence and build a deterministic benchmark scorecard.	flyto_blueprint/benchmark.py:408
function	def verify_result_directory(suite: Mapping[str, Any], results_dir: str | Path) -> dict	Rebuild every committed scorecard and report missing or stale evidence.	flyto_blueprint/benchmark.py:535
function	def _verify_diversity_and_history(scorecards: Sequence[Mapping[str, Any]], measurement: Mapping[str, Any]) -> tuple[dict, list[str]]	See the linked implementation.	flyto_blueprint/benchmark.py:638
function	def write_scorecard(scorecard: Mapping[str, Any], path: str | Path) -> None	Write canonical, reviewable scorecard JSON.	flyto_blueprint/benchmark.py:746
function	def main(argv: Sequence[str] | None=None) -> int	Run the scorecard, suite-description, or repository verification CLI.	flyto_blueprint/benchmark.py:763
function	def _validate_task(task: Any, index: int) -> None	See the linked implementation.	flyto_blueprint/benchmark.py:813
function	def _validate_run(raw_record: Mapping[str, Any], suite: Mapping[str, Any], task_map: Mapping[str, Mapping[str, Any]], expected_suite_digest: str) -> dict	See the linked implementation.	flyto_blueprint/benchmark.py:857
function	def _validate_full_scope_run(record: Mapping[str, Any]) -> None	See the linked implementation.	flyto_blueprint/benchmark.py:972
function	def _validate_global_identity(records: Sequence[Mapping[str, Any]]) -> None	See the linked implementation.	flyto_blueprint/benchmark.py:1045
function	def _validate_pairs(records: Sequence[Mapping[str, Any]]) -> int	See the linked implementation.	flyto_blueprint/benchmark.py:1066
function	def _aggregate(records: Sequence[Mapping[str, Any]]) -> dict	See the linked implementation.	flyto_blueprint/benchmark.py:1100
function	def _compare_modes(baseline_mode: str, baseline: Mapping[str, Any], candidate_mode: str, candidate: Mapping[str, Any], records: Sequence[Mapping[str, Any]]) -> dict	See the linked implementation.	flyto_blueprint/benchmark.py:1196
function	def _build_gate(suite: Mapping[str, Any], records: Sequence[Mapping[str, Any]], by_mode: Mapping[str, Mapping[str, Any]], comparisons: Mapping[str, Mapping[str, Any]]) -> dict	See the linked implementation.	flyto_blueprint/benchmark.py:1285
function	def _check(check_id: str, passed: bool, actual: Any, expected: Any) -> dict	See the linked implementation.	flyto_blueprint/benchmark.py:1490
function	def _wilson_interval(successes: int, total: int) -> tuple[float, float]	See the linked implementation.	flyto_blueprint/benchmark.py:1499
function	def _percentile(values: Sequence[float], quantile: float) -> float | None	See the linked implementation.	flyto_blueprint/benchmark.py:1516
function	def _median(values: Sequence[float]) -> float | None	See the linked implementation.	flyto_blueprint/benchmark.py:1532
function	def _paired_token_reductions(records: Sequence[Mapping[str, Any]], baseline_mode: str, candidate_mode: str, *, token_fields: tuple[str, str]=('planner_input_tokens', 'planner_output_tokens')) -> list[float]	See the linked implementation.	flyto_blueprint/benchmark.py:1536
function	def _median_confidence_interval(values: Sequence[float], confidence: float=0.95) -> tuple[float | None, float | None]	Return an exact distribution-free confidence interval for a median.	flyto_blueprint/benchmark.py:1566
function	def _relative_reduction(candidate: float | None, baseline: float | None) -> float | None	See the linked implementation.	flyto_blueprint/benchmark.py:1590
function	def _relative_increase(candidate: float | None, baseline: float | None) -> float | None	See the linked implementation.	flyto_blueprint/benchmark.py:1596
function	def _round_ratio(numerator: int, denominator: int) -> float	See the linked implementation.	flyto_blueprint/benchmark.py:1602
function	def _round_optional(value: float | None) -> float | None	See the linked implementation.	flyto_blueprint/benchmark.py:1606
function	def _reject_unknown_fields(value: Mapping[str, Any], allowed: set[str], label: str) -> None	See the linked implementation.	flyto_blueprint/benchmark.py:1610
function	def _require_id(value: Any, label: str) -> str	See the linked implementation.	flyto_blueprint/benchmark.py:1625
function	def _require_text(value: Any, label: str) -> str	See the linked implementation.	flyto_blueprint/benchmark.py:1631
function	def _require_int(value: Any, label: str, *, minimum: int, maximum: int | None=None) -> int	See the linked implementation.	flyto_blueprint/benchmark.py:1637
function	def _require_number(value: Any, label: str, *, minimum: float, maximum: float | None=None) -> float	See the linked implementation.	flyto_blueprint/benchmark.py:1651
function	def _reject_json_constant(value: str) -> None	See the linked implementation.	flyto_blueprint/benchmark.py:1670
function	def _reject_duplicate_keys(pairs: Sequence[tuple[str, Any]]) -> dict	See the linked implementation.	flyto_blueprint/benchmark.py:1674
function	def _print_json(value: Mapping[str, Any], stream: Any | None=None) -> None	See the linked implementation.	flyto_blueprint/benchmark.py:1685

flyto_blueprint/compose.py

Kind	Signature	Responsibility	Source
function	def expand_compose(bp: dict, blocks: Dict[str, dict]) -> List[dict]	Expand compose blocks into a flat step list, followed by the blueprint's own steps.	flyto_blueprint/compose.py:16
function	def expand_blueprint(bp: dict, args: dict, blocks: Dict[str, dict]) -> dict	Expand a blueprint: validate args, substitute templates, skip optional steps. Returns a dict with ok, data (workflow + yaml), and optionally warnings.	flyto_blueprint/compose.py:29
function	def compose_chain(blueprint_ids: List[str], args: Dict[str, Any], blueprints: Dict[str, dict], blocks: Dict[str, dict]) -> dict	Expand and chain multiple blueprints into a single workflow. 1. Expand each blueprint via expand_blueprint() 2. Deconflict step IDs across blueprints 3. Wire cross-blueprint variable references 4. Generate edges (intra + cross-blueprint)...	flyto_blueprint/compose.py:108
function	def _deconflict_step_ids(steps: List[Dict[str, Any]], edges: List[Dict[str, Any]], seen_ids: Set[str], bp_index: int) -> Dict[str, str]	Prefix colliding step IDs with bp{idx}_ and update edges + param refs.	flyto_blueprint/compose.py:207
function	def _strip_unresolved_placeholders(steps: List[Dict[str, Any]], optional_args: Optional[Set[str]]=None) -> None	Remove params whose value is an unresolved {{X}} placeholder where X is a known optional arg. If optional_args is None, strips ALL unresolved {{X}} placeholders.	flyto_blueprint/compose.py:255
function	def _wire_cross_blueprint_refs(steps: List[Dict[str, Any]], prev_last_step_id: str, output_field: str, optional_args: Optional[Set[str]]=None) -> None	Replace unresolved {{X}} placeholders with refs to previous blueprint's output. Only wires params where the ENTIRE value is a single {{X}} placeholder and X is NOT a declared optional arg (those will be stripped instead).	flyto_blueprint/compose.py:280

flyto_blueprint/engine.py

Kind	Signature	Responsibility	Source
class	class BlueprintEngine	High-level orchestrator that wires together all blueprint subsystems. Parameters ---------- storage : StorageBackend, optional Where to persist learned blueprints. When None, the engine runs in builtin-only mode (no persistence for lea...	flyto_blueprint/engine.py:36
method	def BlueprintEngine.__init__(self, storage: Optional[StorageBackend]=None) -> None	Initialize the engine with an optional storage backend and load all blueprints.	flyto_blueprint/engine.py:46
method	def BlueprintEngine._load_all(self) -> None	Load builtin blueprints, compose blocks, and learned blueprints.	flyto_blueprint/engine.py:57
method	def BlueprintEngine._load_learned(self) -> None	Load learned blueprints from storage (skip retired).	flyto_blueprint/engine.py:64
method	def BlueprintEngine._maybe_refresh_learned(self) -> None	Reload learned blueprints from storage if the TTL has expired.	flyto_blueprint/engine.py:89
method	def BlueprintEngine._runnable_blueprints(self, available: Optional[FrozenSet[str]]) -> Dict[str, dict]	Return the blueprints whose required modules the host can execute.	flyto_blueprint/engine.py:96
method	def BlueprintEngine.list_blueprints(self, available_module_ids: Optional[Iterable[str]]=None) -> List[dict]	Return summaries of all non-retired blueprints, sorted by score desc. Host-supplied available_module_ids keeps only runnable blueprints; None lists everything and an empty collection lists nothing.	flyto_blueprint/engine.py:112
method	def BlueprintEngine.search(self, query: str, available_module_ids: Optional[Iterable[str]]=None) -> List[dict]	Search blueprints by query. Empty query returns all. available_module_ids filters results like :meth:list_blueprints.	flyto_blueprint/engine.py:130
method	def BlueprintEngine.expand(self, blueprint_id: str, args: dict, available_module_ids: Optional[Iterable[str]]=None) -> dict	Expand a blueprint with args. Returns {ok, data, warnings?}. A step module that args resolve to an unavailable module fails before any use or scoring, with BLUEPRINT_MODULE_UNAVAILABLE.	flyto_blueprint/engine.py:143
method	def BlueprintEngine.learn_from_workflow(self, workflow: dict, blueprint_id: Optional[str]=None, name: Optional[str]=None, tags: Optional[List[str]]=None, verified: bool=False, compatibility: Optional[dict]=None, verification: Optional[di...	Learn an explicitly community/unverified reusable workflow.	flyto_blueprint/engine.py:188
method	def BlueprintEngine._learn_and_persist(self, workflow: dict, blueprint_id: Optional[str]=None, name: Optional[str]=None, tags: Optional[List[str]]=None, verified: bool=False, compatibility: Optional[dict]=None, verification: Optional[dic...	Run the shared learning path after its public trust gate.	flyto_blueprint/engine.py:213
method	def BlueprintEngine.learn_from_execution(self, workflow: dict, blueprint_id: Optional[str]=None, name: Optional[str]=None, tags: Optional[List[str]]=None, compatibility: Optional[dict]=None, verification: Optional[dict]=None) -> dict	Learn from a host-verified execution receipt (initial score 70). Blueprint validates only the receipt contract; it does not prove the underlying event or grant execution authority.	flyto_blueprint/engine.py:252
method	def BlueprintEngine.report_outcome(self, blueprint_id: str, success: bool, execution_id: str='', evidence_tier: str='local_verified', evidence: Optional[dict]=None, verification: Optional[dict]=None) -> dict	Report an outcome; trusted tiers require an outcome-bound receipt.	flyto_blueprint/engine.py:286
method	def BlueprintEngine.export_blueprint(self, blueprint_id: str, *, publisher: str='', claimed_tier: Optional[str]=None, evidence: Optional[dict]=None, signing_key: Optional[SigningKey]=None) -> dict	Create an integrity-checked portable bundle without uploading it.	flyto_blueprint/engine.py:304
method	def BlueprintEngine.import_blueprint(self, bundle: dict, *, trusted_keys: Optional[Mapping[str, SigningKey]]=None) -> dict	Validate and persist a portable bundle with trust quarantine.	flyto_blueprint/engine.py:326

flyto_blueprint/execution_verification.py

Kind	Signature	Responsibility	Source
function	def _canonicalize_evidence(evidence: Any) -> tuple[Dict[str, Any], bytes]	Validate and detach one bounded, exact-JSON evidence object.	flyto_blueprint/execution_verification.py:31
function	def _canonicalize_evidence.visit(value: Any, depth: int) -> None	See the linked implementation.	flyto_blueprint/execution_verification.py:38
function	def validate_execution_verification_receipt(receipt: Any, *, expected_outcome_success: Any=None, require_outcome_success: bool=False) -> Dict[str, Any]	Return a detached canonical receipt or raise ValueError. The v1 envelope is deliberately exact, while evidence is one nested, bounded, detached JSON object. Unknown fields, non-JSON containers, contradictory success/status values...	flyto_blueprint/execution_verification.py:85

flyto_blueprint/fingerprint.py

Kind	Signature	Responsibility	Source
function	def compute_fingerprint(steps: List[dict]) -> str	Compute an MD5 fingerprint of a workflow's module+param-key structure. Two workflows with the same modules and the same parameter keys (regardless of values) produce the same fingerprint. Returns a 12-character hex string.	flyto_blueprint/fingerprint.py:8

flyto_blueprint/intent.py

Kind	Signature	Responsibility	Source
class	class CapabilitySearchBoundaryError(ValueError)	Stable content-free rejection at the capability-search trust boundary.	flyto_blueprint/intent.py:42
method	def CapabilitySearchBoundaryError.__init__(self, code: str='CAPABILITY_SEARCH_INVALID') -> None	See the linked implementation.	flyto_blueprint/intent.py:45
function	def _reject(code: str='CAPABILITY_SEARCH_INVALID') -> None	See the linked implementation.	flyto_blueprint/intent.py:82
function	def _snapshot_json(value: Any, *, max_nodes: int=_MAX_NODES, max_bytes: int=_MAX_JSON_BYTES) -> Any	Detach recursively bounded exact JSON while redacting hostile faults.	flyto_blueprint/intent.py:86
function	def _snapshot_json.visit(item: Any, depth: int) -> Any	See the linked implementation.	flyto_blueprint/intent.py:90
function	def _plain_mapping(value: Any, fields: frozenset[str], *, max_nodes: int=_MAX_NODES, max_bytes: int=_MAX_JSON_BYTES) -> dict	See the linked implementation.	flyto_blueprint/intent.py:126
function	def _text(value: Any, *, identifier: bool=False, maximum: Optional[int]=None, empty: bool=False) -> str	See the linked implementation.	flyto_blueprint/intent.py:133
function	def _projection_text(value: Any) -> str	Validate producer-canonical display text without trimming it.	flyto_blueprint/intent.py:146
function	def _digest(value: Any) -> str	See the linked implementation.	flyto_blueprint/intent.py:155
function	def _boolean(value: Any) -> bool	See the linked implementation.	flyto_blueprint/intent.py:161
function	def _integer(value: Any, minimum: int, maximum: int) -> int	See the linked implementation.	flyto_blueprint/intent.py:167
function	def _string_list(value: Any, *, maximum: int=_MAX_LIST, identifier_maximum: int=128, canonical: bool=False) -> list[str]	See the linked implementation.	flyto_blueprint/intent.py:173
function	def _canonical_json(value: Any, *, max_bytes: int=_MAX_JSON_BYTES) -> bytes	See the linked implementation.	flyto_blueprint/intent.py:183
function	def _sha(value: Any, *, max_bytes: int=_MAX_JSON_BYTES) -> str	See the linked implementation.	flyto_blueprint/intent.py:193
function	def validate_capability_search_projection(value: Any) -> dict	Return the exact safe projection or reject it without echoing content.	flyto_blueprint/intent.py:197
function	def capability_projection_is_indexable(value: Any) -> bool	Report eligibility; validation failures still reject instead of becoming false.	flyto_blueprint/intent.py:251
function	def _validate_model(value: Any) -> dict	See the linked implementation.	flyto_blueprint/intent.py:263
function	def _validate_filters(value: Any, tenant_id: str, space_id: str, *, document: bool=False) -> dict	See the linked implementation.	flyto_blueprint/intent.py:273
function	def build_capability_search_document(projection: Any, model: Any, filters: Any) -> dict	Build a deterministic JSON-native document without computing a vector.	flyto_blueprint/intent.py:296
function	def validate_capability_search_document(value: Any) -> dict	Rebuild and compare every derived field and digest on document read.	flyto_blueprint/intent.py:325
function	def build_capability_search_mutation(document: Any, operation: str='upsert') -> dict	Build an exact deterministic upsert mutation.	flyto_blueprint/intent.py:340
function	def validate_capability_search_mutation(value: Any) -> dict	Validate an upsert mutation and its document on read.	flyto_blueprint/intent.py:350
function	def build_capability_search_tombstone(source: Any, reason: str, operation: str='retire', prior_document_digest: Optional[str]=None) -> dict	Build a content-free tombstone from ineligible source or prior identity.	flyto_blueprint/intent.py:371
function	def validate_capability_search_tombstone(value: Any) -> dict	Validate a bounded tombstone without requiring retained search content.	flyto_blueprint/intent.py:404
function	def build_capability_search_request(query: str, top_k: int, filters: Any, model: Any, index_digest: str, snapshot_digest: str, lexical_weight: int=50, vector_weight: int=50, page_size: Optional[int]=None, cursor: Optional[str]=None, inte...	Build a backend-neutral request whose hard filters precede retrieval.	flyto_blueprint/intent.py:429
function	def validate_capability_search_request(value: Any, integrity_key: Optional[bytes]=None) -> dict	Detach and rebuild every request field before cursor or page use.	flyto_blueprint/intent.py:467
function	def encode_capability_search_cursor(request: Any, last_score: int, last_capability_id: str, integrity_key: bytes, emitted_count: int) -> str	Create a versioned opaque keyset cursor bound to the complete request.	flyto_blueprint/intent.py:492
function	def decode_capability_search_cursor(cursor: str, request: Any, integrity_key: bytes) -> dict	Verify cursor integrity and reject cross-request reuse.	flyto_blueprint/intent.py:509
function	def validate_capability_search_page(value: Any, request: Any, integrity_key: Optional[bytes]=None) -> dict	Validate a deterministically ordered candidate-only backend page.	flyto_blueprint/intent.py:538
function	def expand_query(query: str) -> List[str]	Expand query words with synonyms. Returns unique expanded word list.	flyto_blueprint/intent.py:648
function	def _pack_vector(vec: List[float]) -> bytes	Serialize a float list to compact binary (4 bytes per float).	flyto_blueprint/intent.py:660
function	def _unpack_vector(data: bytes) -> List[float]	Deserialize binary data back to a list of floats.	flyto_blueprint/intent.py:665
function	def _cosine_similarity(a: List[float], b: List[float]) -> float	Compute cosine similarity between two float vectors.	flyto_blueprint/intent.py:671
function	def _bp_text(bp: dict) -> str	Build searchable text from blueprint metadata.	flyto_blueprint/intent.py:681
function	def _score_candidate(words: List[str], tags: List[str], id_words: List[str], name_words: List[str], desc: str) -> float	Score how well words match a single blueprint's metadata. Weights: exact tag 3.0, id word 2.0, name word 1.5, partial tag substring 1.0, description substring 0.5.	flyto_blueprint/intent.py:692
class	class IntentMatcher	System-level blueprint matcher with embedding + keyword + tag fallback.	flyto_blueprint/intent.py:721
method	def IntentMatcher.__init__(self, blueprints: Dict[str, dict]) -> None	Initialize the matcher with a dict of blueprint_id to blueprint data.	flyto_blueprint/intent.py:724
method	async def IntentMatcher.build_index(self, api_key: Optional[str]=None) -> bool	Build embedding index for all blueprints. Cached to disk.	flyto_blueprint/intent.py:730
method	async def IntentMatcher.match(self, query: str, api_key: Optional[str]=None, top_k: int=5, threshold: float=0.3) -> List[Dict[str, Any]]	Match user intent to blueprints. Returns ranked results. Cascading strategy: 1. If embedding index exists → semantic similarity 2. Always → keyword BM25 with synonym expansion 3. Merge and deduplicate	flyto_blueprint/intent.py:794
method	async def IntentMatcher._match_embedding(self, query: str, api_key: Optional[str], top_k: int, threshold: float) -> List[Dict[str, Any]]	Semantic matching via embedding cosine similarity.	flyto_blueprint/intent.py:833
method	def IntentMatcher._match_keywords(self, query: str, top_k: int) -> List[Dict[str, Any]]	Keyword matching with synonym expansion and BM25-like scoring.	flyto_blueprint/intent.py:858
class	class QueryTracker	Track query → blueprint mappings for learning which blueprints users prefer. Stores in SQLite for persistence. Used to: 1. Boost frequently-used blueprints in search results 2. Train better intent classifiers over time 3. Detect gaps (qu...	flyto_blueprint/intent.py:903
method	def QueryTracker.__init__(self, db_path: Optional[str]=None) -> None	Initialize the tracker with an optional SQLite database path.	flyto_blueprint/intent.py:912
method	async def QueryTracker.init(self) -> None	Create the SQLite tables if they do not already exist.	flyto_blueprint/intent.py:919
method	async def QueryTracker.record_match(self, query: str, blueprint_id: str, success: bool) -> None	Record that a query was matched to a blueprint.	flyto_blueprint/intent.py:947
method	async def QueryTracker.record_gap(self, query: str) -> None	Record a query that had no blueprint match — identifies coverage gaps.	flyto_blueprint/intent.py:959
method	async def QueryTracker.get_popular_mappings(self, limit: int=50) -> List[Dict[str, Any]]	Get most popular query→blueprint mappings for training data.	flyto_blueprint/intent.py:971
method	async def QueryTracker.get_gaps(self, limit: int=50) -> List[Dict[str, Any]]	Get queries with no blueprint match — candidates for new blueprints.	flyto_blueprint/intent.py:990

flyto_blueprint/learn.py

Kind	Signature	Responsibility	Source
function	def learn_from_workflow(workflow: dict, blueprints: Dict[str, dict], blocks: Dict[str, dict], *, blueprint_id: Optional[str]=None, name: Optional[str]=None, tags: Optional[List[str]]=None, verified: bool=False, compatibility: Optional[di...	Abstract a concrete workflow into a reusable blueprint. Concrete values become {{arg}} templates; structural constants stay fixed. Detects compose opportunities (browser.launch + browser.goto → browser_init). Dedup: if a blueprint wi...	flyto_blueprint/learn.py:18
function	def _find_by_fingerprint(fingerprint: str, context_fingerprint: Optional[str], blueprints: Dict[str, dict]) -> Optional[str]	Find an existing learned blueprint with the same fingerprint.	flyto_blueprint/learn.py:127
function	def _build_blueprint_dict(*, steps: List[dict], blocks: Dict[str, dict], blueprint_id: str, name: Optional[str], tags: Optional[List[str]], verified: bool, description: str, fingerprint: str, context_fingerprint: Optional[str], compatibi...	Construct a learned blueprint dict from abstracted workflow steps. Handles parameter abstraction, compose detection, auto-generated name/tags, and metadata initialization.	flyto_blueprint/learn.py:143
function	def _compute_context_fingerprint(compatibility: Optional[dict]) -> Optional[str]	See the linked implementation.	flyto_blueprint/learn.py:247

flyto_blueprint/loader.py

Kind	Signature	Responsibility	Source
function	def load_builtins() -> Dict[str, dict]	Load all builtin blueprint YAML files. Returns a dict mapping blueprint ID → blueprint dict. Each blueprint gets _source = "builtin" added.	flyto_blueprint/loader.py:16
function	def load_blocks() -> Dict[str, dict]	Load all compose block YAML files. Returns a dict mapping block ID → block dict.	flyto_blueprint/loader.py:41

flyto_blueprint/longitudinal.py

Kind	Signature	Responsibility	Source
function	def run_longitudinal_evidence(db_path: str | Path, *, repository_commit: str, run_id: str, reuse_trials: int=20, success_reports: int=4) -> dict	Exercise learn, reuse, downgrade, retirement, and reload via SQLite.	flyto_blueprint/longitudinal.py:34
function	def verify_longitudinal_evidence(evidence: Mapping[str, Any]) -> dict	Fail closed when lifecycle evidence is malformed, edited, or regressed.	flyto_blueprint/longitudinal.py:256
function	def write_longitudinal_evidence(evidence: Mapping[str, Any], path: str | Path) -> None	Write canonical lifecycle evidence without prompts or workflow outputs.	flyto_blueprint/longitudinal.py:293
function	def main(argv: Optional[Sequence[str]]=None) -> int	Run or verify the real longitudinal lifecycle from the command line.	flyto_blueprint/longitudinal.py:313
function	def _required_record(storage: SQLiteBackend, blueprint_id: str) -> dict	See the linked implementation.	flyto_blueprint/longitudinal.py:351
function	def _score(record: Mapping[str, Any]) -> int	See the linked implementation.	flyto_blueprint/longitudinal.py:358
function	def _verification_receipt(evidence_id: str, evidence: Mapping[str, Any]) -> dict	Bind one bounded longitudinal outcome to a canonical host receipt.	flyto_blueprint/longitudinal.py:365
function	def _execution_evidence(*, success: bool) -> dict	See the linked implementation.	flyto_blueprint/longitudinal.py:382
function	def _file_digest(path: Path) -> str	See the linked implementation.	flyto_blueprint/longitudinal.py:393
function	def _utc_now() -> str	See the linked implementation.	flyto_blueprint/longitudinal.py:397

flyto_blueprint/models.py

Kind	Signature	Responsibility	Source
class	class BlueprintArg(BaseModel)	Definition of a blueprint argument.	flyto_blueprint/models.py:9
class	class Blueprint(BaseModel)	Full blueprint document.	flyto_blueprint/models.py:16
class	class BlueprintSummary(BaseModel)	Summary view returned by list/search.	flyto_blueprint/models.py:51

flyto_blueprint/scoring.py

Kind	Signature	Responsibility	Source
function	def evidence_card(blueprint: dict) -> dict	Summarize trusted outcomes without inventing token-savings estimates.	flyto_blueprint/scoring.py:29
function	def report_outcome(blueprint_id: str, success: bool, blueprints: Dict[str, dict], storage: Optional[StorageBackend]=None, execution_id: str='', recent_reports: Optional[Dict[str, float]]=None, evidence_tier: str='local_verified', evidenc...	Report whether a blueprint-generated workflow succeeded or failed. Trusted success: +5 (cap 100). Trusted failure: -10 (floor 0). Community observations update separate Bayesian counters and can influence ranking within a small cap, but ...	flyto_blueprint/scoring.py:127
function	def _normalize_evidence(evidence: Optional[dict], *, success: bool, evidence_tier: str, execution_id: str, observed_at: str) -> Optional[dict]	Keep a small allowlist of execution facts and discard arbitrary payloads.	flyto_blueprint/scoring.py:272
function	def _is_bounded_number(value: Any, *, maximum: float) -> bool	See the linked implementation.	flyto_blueprint/scoring.py:332
function	def _is_bounded_int(value: Any, *, maximum: int) -> bool	See the linked implementation.	flyto_blueprint/scoring.py:341
function	def _wilson_lower_bound(successes: int, total: int) -> Optional[float]	See the linked implementation.	flyto_blueprint/scoring.py:349
function	def _percentile(values: List[float], quantile: float) -> Optional[float]	See the linked implementation.	flyto_blueprint/scoring.py:363
function	def effective_quality_score(blueprint: dict) -> float	Blend trusted score with a capped, confidence-weighted community signal.	flyto_blueprint/scoring.py:377
function	def _record_community_observation(blueprint_id: str, success: bool, blueprint: dict, storage: Optional[StorageBackend]) -> dict	See the linked implementation.	flyto_blueprint/scoring.py:393
function	def boost_score(blueprint_id: str, delta: int, blueprints: Dict[str, dict], storage: Optional[StorageBackend]=None) -> dict	Reject arbitrary score mutation; use receipt-bound report_outcome.	flyto_blueprint/scoring.py:439
function	def record_use(blueprint_id: str, blueprints: Dict[str, dict], storage: Optional[StorageBackend]=None) -> None	Record that a blueprint was used (expand). Only tracks count — no score change. Score should only change from verified outcomes.	flyto_blueprint/scoring.py:455

flyto_blueprint/search.py

Kind	Signature	Responsibility	Source
function	def _module_ids(bp: dict) -> List[str]	Return ordered, unique module IDs without exposing step parameters.	flyto_blueprint/search.py:11
function	def bp_summary(bp: dict) -> dict	Build a summary dict for a blueprint.	flyto_blueprint/search.py:16
function	def list_blueprints(blueprints: Dict[str, dict]) -> List[dict]	Return summaries of all non-retired blueprints, sorted by score desc.	flyto_blueprint/search.py:53
function	def search_blueprints(query: str, blueprints: Dict[str, dict]) -> List[dict]	Search blueprints with two-pass scoring: exact words first, synonym fallback. Pass 1: Score using original query words (high confidence). Pass 2: If top score < threshold, boost with synonym-expanded words (lower weight).	flyto_blueprint/search.py:64
function	def _score_blueprint(query_words: List[str], synonym_words: List[str], bp: dict) -> float	Score a single blueprint against query words and synonym expansions. Two-pass scoring: - Pass 1: original query words at full weight. - Pass 2: synonym words at half weight (only when pass 1 has gaps). Returns 0.0 when there are no match...	flyto_blueprint/search.py:99

flyto_blueprint/sharing.py

Kind	Signature	Responsibility	Source
function	def export_blueprint_bundle(blueprint: dict, *, publisher: str='', claimed_tier: Optional[str]=None, evidence: Optional[dict]=None, signing_key: Optional[SigningKey]=None) -> dict	Create a portable Blueprint bundle without uploading it anywhere. A SHA-256 digest always protects integrity. When signing_key is supplied, an HMAC signature lets a receiving host preserve the claimed trust tier if it has the matchin...	flyto_blueprint/sharing.py:52
function	def import_blueprint_bundle(bundle: dict, *, trusted_keys: Optional[Mapping[str, SigningKey]]=None) -> dict	Validate a portable bundle and prepare a quarantined learned Blueprint. Unsigned bundles, unknown publishers, and invalid signatures are always downgraded to community. A digest proves integrity, not publisher identity; only a signat...	flyto_blueprint/sharing.py:116
function	def blueprint_definition_digest(blueprint: dict) -> str	Return a stable semantic digest, excluding labels and mutable evidence.	flyto_blueprint/sharing.py:207
function	def _canonical_bytes(value: dict) -> bytes	See the linked implementation.	flyto_blueprint/sharing.py:217
function	def _key_bytes(key: SigningKey) -> bytes	See the linked implementation.	flyto_blueprint/sharing.py:227
function	def _verify_signature(signature: object, payload: bytes, publisher: str, trusted_keys: Mapping[str, SigningKey]) -> bool	See the linked implementation.	flyto_blueprint/sharing.py:234
function	def _shared_sensitive_paths(definition: dict, evidence: object) -> list	See the linked implementation.	flyto_blueprint/sharing.py:253
function	def _validate_blueprint_definition(blueprint: object) -> Optional[str]	See the linked implementation.	flyto_blueprint/sharing.py:270
function	def _find_sensitive_paths(value: object, path: tuple) -> list	See the linked implementation.	flyto_blueprint/sharing.py:288
function	def _is_parameterized(value: object) -> bool	See the linked implementation.	flyto_blueprint/sharing.py:302

flyto_blueprint/storage/base.py

Kind	Signature	Responsibility	Source
class	class StorageBackend(ABC)	Abstract base class for blueprint persistence.	flyto_blueprint/storage/base.py:8
method	def StorageBackend.load_all(self) -> List[dict]	Load all stored blueprints. Returns list of raw dicts.	flyto_blueprint/storage/base.py:12
method	def StorageBackend.save(self, blueprint_id: str, data: dict) -> None	Save or overwrite a blueprint.	flyto_blueprint/storage/base.py:16
method	def StorageBackend.update(self, blueprint_id: str, fields: dict) -> None	Update specific fields of a blueprint.	flyto_blueprint/storage/base.py:20
method	def StorageBackend.load_one(self, blueprint_id: str) -> Optional[dict]	Load a single blueprint by ID. Returns None if not found.	flyto_blueprint/storage/base.py:24
method	def StorageBackend.delete(self, blueprint_id: str) -> None	Delete a blueprint by ID.	flyto_blueprint/storage/base.py:28
method	def StorageBackend.atomic_update(self, blueprint_id: str, update_fn: Callable[[dict], Optional[dict]]) -> Optional[dict]	Read-modify-write a blueprint atomically. The update_fn receives the current data dict and returns the updated dict, or None to abort. This default implementation is non-atomic (load + save) and is safe only for a single writer; SQLiteBa...	flyto_blueprint/storage/base.py:31

flyto_blueprint/storage/firestore.py

Kind	Signature	Responsibility	Source
class	class FirestoreBackend(StorageBackend)	Persists blueprints in Google Firestore. Requires google-cloud-firestore and a Firestore client instance.	flyto_blueprint/storage/firestore.py:14
method	def FirestoreBackend.__init__(self, db, collection: str=_DEFAULT_COLLECTION) -> None	Initialize with a Firestore client and optional collection name.	flyto_blueprint/storage/firestore.py:20
method	def FirestoreBackend._col(self)	Return the Firestore collection reference.	flyto_blueprint/storage/firestore.py:25
method	def FirestoreBackend.load_all(self) -> List[dict]	Stream all documents from the collection as dicts.	flyto_blueprint/storage/firestore.py:29
method	def FirestoreBackend.save(self, blueprint_id: str, data: dict) -> None	Set (create or overwrite) a Firestore document.	flyto_blueprint/storage/firestore.py:38
method	def FirestoreBackend.update(self, blueprint_id: str, fields: dict) -> None	Partially update fields on an existing Firestore document.	flyto_blueprint/storage/firestore.py:42
method	def FirestoreBackend.load_one(self, blueprint_id: str) -> Optional[dict]	Fetch a single document by ID, or return None.	flyto_blueprint/storage/firestore.py:46
method	def FirestoreBackend.delete(self, blueprint_id: str) -> None	Delete a Firestore document by ID.	flyto_blueprint/storage/firestore.py:53
method	def FirestoreBackend.atomic_update(self, blueprint_id: str, update_fn: Callable[[dict], Optional[dict]]) -> Optional[dict]	Run update_fn inside a Firestore transaction.	flyto_blueprint/storage/firestore.py:57
function	def FirestoreBackend.atomic_update._txn(txn, ref)	See the linked implementation.	flyto_blueprint/storage/firestore.py:69

flyto_blueprint/storage/memory.py

Kind	Signature	Responsibility	Source
class	class MemoryBackend(StorageBackend)	Stores blueprints in a plain dict. Data is lost on process exit.	flyto_blueprint/storage/memory.py:10
method	def MemoryBackend.__init__(self) -> None	Initialize with an empty in-memory dict.	flyto_blueprint/storage/memory.py:13
method	def MemoryBackend.load_all(self) -> List[dict]	Return deep copies of all stored blueprints.	flyto_blueprint/storage/memory.py:17
method	def MemoryBackend.save(self, blueprint_id: str, data: dict) -> None	Store a deep copy of data under blueprint_id.	flyto_blueprint/storage/memory.py:21
method	def MemoryBackend.update(self, blueprint_id: str, fields: dict) -> None	Merge fields into the stored blueprint if it exists.	flyto_blueprint/storage/memory.py:25
method	def MemoryBackend.load_one(self, blueprint_id: str) -> Optional[dict]	Return a deep copy of a single blueprint, or None.	flyto_blueprint/storage/memory.py:30
method	def MemoryBackend.delete(self, blueprint_id: str) -> None	Remove the blueprint if it exists; no-op otherwise.	flyto_blueprint/storage/memory.py:35
method	def MemoryBackend.atomic_update(self, blueprint_id: str, update_fn: Callable[[dict], Optional[dict]]) -> Optional[dict]	Apply update_fn in-place and return a deep copy of the result.	flyto_blueprint/storage/memory.py:39

flyto_blueprint/storage/sqlite.py

Kind	Signature	Responsibility	Source
class	class SQLiteBackend(StorageBackend)	Persists blueprints in a local SQLite database. Safe across threads and processes. That distinction is the reason this class looks the way it does: the default database path is shared, and the host that uses it opens one per process....	flyto_blueprint/storage/sqlite.py:20
method	def SQLiteBackend.__init__(self, db_path: Optional[str]=None) -> None	Initialize SQLite backend, creating the database file if needed.	flyto_blueprint/storage/sqlite.py:49
method	def SQLiteBackend._connect(self) -> sqlite3.Connection	Open a connection with cross-process settings applied. isolation_level=None turns off the driver's implicit transaction handling so this module can state its own boundaries; without it the BEGIN IMMEDIATE below would be issued in...	flyto_blueprint/storage/sqlite.py:56
method	def SQLiteBackend._write_transaction(self) -> Iterator[sqlite3.Connection]	Run a block as one exclusive read-modify-write transaction. BEGIN IMMEDIATE acquires the write lock up front, so a concurrent writer waits at the BEGIN instead of reading a value this block is about to replace. A deferred transac...	flyto_blueprint/storage/sqlite.py:76
method	def SQLiteBackend._init_db(self) -> None	Create the blueprints table if it does not exist.	flyto_blueprint/storage/sqlite.py:93
method	def SQLiteBackend.load_all(self) -> List[dict]	Load and deserialize all blueprints from the database.	flyto_blueprint/storage/sqlite.py:103
method	def SQLiteBackend.save(self, blueprint_id: str, data: dict) -> None	Serialize and upsert a blueprint row.	flyto_blueprint/storage/sqlite.py:109
method	def SQLiteBackend.update(self, blueprint_id: str, fields: dict) -> None	Merge fields into the stored JSON blob for blueprint_id.	flyto_blueprint/storage/sqlite.py:118
method	def SQLiteBackend.load_one(self, blueprint_id: str) -> Optional[dict]	Load a single blueprint by ID, or return None if not found.	flyto_blueprint/storage/sqlite.py:133
method	def SQLiteBackend.delete(self, blueprint_id: str) -> None	Delete the blueprint row for blueprint_id.	flyto_blueprint/storage/sqlite.py:141
method	def SQLiteBackend.atomic_update(self, blueprint_id: str, update_fn: Callable[[dict], Optional[dict]]) -> Optional[dict]	Read-modify-write inside one exclusive transaction. Atomic against other threads and other processes. update_fn runs while the write lock is held, so it must not block on anything slow -- it is expected to be pure bookkeeping on th...	flyto_blueprint/storage/sqlite.py:146

flyto_blueprint/template.py

Kind	Signature	Responsibility	Source
function	def substitute(value: str, args: dict) -> str	Replace {{arg_name}} placeholders in a string.	flyto_blueprint/template.py:23
function	def substitute.replacer(match: re.Match) -> str	See the linked implementation.	flyto_blueprint/template.py:28
function	def substitute_deep(obj: Any, args: dict) -> Any	Recursively substitute {{arg_name}} in dicts, lists, and strings. When an entire string is a single {{arg}} placeholder and the arg value is non-string (int, dict, list, bool), the original type is preserved instead of being stri...	flyto_blueprint/template.py:35
function	def abstract_params(params: dict, args_def: Dict[str, dict]) -> dict	Replace concrete param values with {{arg}} templates where appropriate. Builds up args_def as a side effect — each new arg is registered there.	flyto_blueprint/template.py:57

flyto_blueprint/tools.py

Kind	Signature	Responsibility	Source
function	def get_blueprint_tools() -> List[dict]	Return all blueprint MCP tool definitions.	flyto_blueprint/tools.py:144

flyto_blueprint/validate.py

Kind	Signature	Responsibility	Source
function	def _get_core_validator()	Get flyto-core's validate_params. Returns None if unavailable.	flyto_blueprint/validate.py:10
function	def validate_steps(steps: List[dict]) -> List[str]	Check expanded steps against the flyto-core module registry. Returns a list of warning strings. Empty list = all good. Non-blocking: if flyto-core is unavailable, returns no warnings. Skips "module not found" errors since blueprints may ...	flyto_blueprint/validate.py:19