generated from coulomb/repo-seed
397 lines
58 KiB
Markdown
397 lines
58 KiB
Markdown
# Markitect API Reference
|
|
|
|
Generated from `markitect_tool.__all__`.
|
|
|
|
## `markitect_tool`
|
|
|
|
- `BACKEND_CAPABILITIES` - object. set() -> new empty set object
|
|
- `DEFAULT_BACKEND_PATHS` - object. Built-in immutable sequence.
|
|
- `DEFAULT_LOCAL_INDEX_PATH` - object. str(object='') -> str
|
|
- `DOCUMENT_VALUE_KINDS` - object. set() -> new empty set object
|
|
- `EMPTY_PARSE_OPTIONS_HASH` - object. str(object='') -> str
|
|
- `EXPLODE_MANIFEST_NAME` - object. str(object='') -> str
|
|
- `LOCAL_INDEX_SCHEMA_VERSION` - object. str(object='') -> str
|
|
- `MAX_FUNCTION_PIPELINE_DEPTH` - object. int([x]) -> integer
|
|
- `NORMALIZED_SOURCE_SCHEMA_VERSION` - object. str(object='') -> str
|
|
- `SOURCE_ADAPTER_ENTRY_POINT_GROUP` - object. str(object='') -> str
|
|
|
|
## `markitect_tool.backend.engine`
|
|
|
|
- `BackendCapabilityCheck(backend_id: 'str', required: 'list[str]', supported: 'list[str]', missing: 'list[str]') -> None` - class. Compatibility result for a backend against required capabilities.
|
|
- `BackendManifest(id: 'str', kind: 'str' = 'cache-backend', name: 'str | None' = None, version: 'str' = '1', capabilities: 'list[str]' = <factory>, storage: 'dict[str, Any]' = <factory>, policy: 'dict[str, Any]' = <factory>, description: 'str | None' = None, manifest_path: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Declarative manifest for an optional backend.
|
|
- `BackendRegistry(manifests: 'list[BackendManifest] | None' = None) -> 'None'` - class. Read-only registry of backend manifests.
|
|
- `BackendRegistryError` - class. Raised when backend manifests or registry operations fail.
|
|
- `DependencyEdge(source_id: 'str', target: 'str', kind: 'str', target_snapshot_id: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Dependency edge between a snapshot/unit and another addressable target.
|
|
- `DocumentSnapshot(identity: 'SnapshotIdentity', document: 'dict[str, Any]', units: 'list[dict[str, Any]]' = <factory>, dependencies: 'list[DependencyEdge]' = <factory>, provenance: 'ProvenanceEnvelope | None' = None) -> None` - class. A parsed document snapshot that optional backends may persist.
|
|
- `ProvenanceEnvelope(operation: 'str', snapshot_id: 'str | None' = None, source_path: 'str | None' = None, content_hash: 'str | None' = None, dependencies: 'list[DependencyEdge]' = <factory>, backend_id: 'str | None' = None, policy_decision_id: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Shared provenance metadata for backend-derived objects.
|
|
- `SnapshotIdentity(source_path: 'str', content_hash: 'str', parser: 'str' = 'markdown-it-py/commonmark', parser_version: 'str' = 'markitect-tool:1', parse_options_hash: 'str' = 'sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a', contract_hash: 'str | None' = None) -> None` - class. Content-addressed identity for a parsed document snapshot.
|
|
- `capability_check(manifest: 'BackendManifest', required: 'list[str]') -> 'BackendCapabilityCheck'` - function.
|
|
- `load_backend_manifest(path: 'str | Path') -> 'BackendManifest'` - function. Load one backend manifest from YAML or Markdown fenced YAML.
|
|
- `load_backend_registry(paths: 'list[str | Path] | None' = None) -> 'BackendRegistry'` - function. Load backend manifests from files or directories without importing backends.
|
|
- `snapshot_identity_for_file(path: 'str | Path', *, parse_options: 'dict[str, Any] | None' = None, contract_hash: 'str | None' = None) -> 'SnapshotIdentity'` - function. Build a content-addressed snapshot identity for a file.
|
|
|
|
## `markitect_tool.backend.interfaces`
|
|
|
|
- `AccessPolicyGateway(*args, **kwargs)` - class. Authorization and filtering gateway for backend results.
|
|
- `ContextPackageRegistry(*args, **kwargs)` - class. Agent-ready context package registry.
|
|
- `IndexBackend(*args, **kwargs)` - class. Derived index backend for snapshots.
|
|
- `ProcessorResultStore(*args, **kwargs)` - class. Optional store for deterministic or assisted processor outputs.
|
|
- `QueryAdapter(*args, **kwargs)` - class. Adapter from stable Markitect requests to backend execution.
|
|
- `SnapshotBackend(*args, **kwargs)` - class. Durable parsed-document snapshot backend.
|
|
|
|
## `markitect_tool.backend.local_store`
|
|
|
|
- `LocalIndexBuildResult(index_path: 'str', root: 'str', paths: 'list[str]', planned: 'dict[str, Any]', parsed: 'list[str]' = <factory>, indexed: 'list[str]' = <factory>, metadata_updated: 'list[str]' = <factory>, deleted: 'list[str]' = <factory>) -> None` - class. Summary of a local index build or refresh.
|
|
- `LocalSearchResult(path: 'str', snapshot_id: 'str', unit_kind: 'str', unit_index: 'int', heading: 'str | None', text: 'str', rank: 'float', line_start: 'int | None' = None, line_end: 'int | None' = None) -> None` - class. One FTS search match from the local index.
|
|
- `LocalSnapshotStore(path: 'str | Path' = '.markitect/cache/index.sqlite3') -> 'None'` - class. SQLite-backed local snapshot store for parsed Markdown documents.
|
|
- `local_index_path_for(root: 'str | Path', index_path: 'str | Path | None' = None) -> 'Path'` - function. Return the local SQLite index path for a root and optional override.
|
|
|
|
## `markitect_tool.backend.planning`
|
|
|
|
- `SnapshotPlanEntry(path: 'str', actions: 'list[str]', reason: 'str', size: 'int | None' = None, mtime_ns: 'int | None' = None, previous_snapshot_id: 'str | None' = None, content_hash: 'str | None' = None, invalidated_by: 'list[str]' = <factory>) -> None` - class. One source-path decision in a refresh plan.
|
|
- `SnapshotRefreshPlan(root: 'str', parser: 'str', parser_version: 'str', parse_options_hash: 'str', contract_hash: 'str | None', verify_hashes: 'bool', entries: 'list[SnapshotPlanEntry]') -> None` - class. A cheap-first plan for refreshing snapshots and derived indexes.
|
|
- `SnapshotState(path: 'str', size: 'int', mtime_ns: 'int', content_hash: 'str', snapshot_id: 'str', parser: 'str' = 'markdown-it-py/commonmark', parser_version: 'str' = 'markitect-tool:1', parse_options_hash: 'str' = 'sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a', contract_hash: 'str | None' = None, indexed: 'bool' = True, dependencies: 'list[DependencyEdge]' = <factory>) -> None` - class. Previously known source state from a snapshot/index backend.
|
|
- `load_snapshot_state_file(path: 'str | Path') -> 'list[SnapshotState]'` - function. Load a portable snapshot-state fixture from JSON or YAML.
|
|
- `plan_snapshot_refresh(paths: 'list[str | Path]', *, previous: 'list[SnapshotState] | dict[str, SnapshotState] | None' = None, root: 'str | Path' = '.', recursive: 'bool' = True, parse_options: 'dict[str, Any] | None' = None, contract_hash: 'str | None' = None, verify_hashes: 'bool' = False) -> 'SnapshotRefreshPlan'` - function. Plan snapshot/index refresh work using cheap metadata before hashing.
|
|
|
|
## `markitect_tool.cache.engine`
|
|
|
|
- `CacheEntry(path: 'str', content_hash: 'str', size: 'int', mtime_ns: 'int', parser: 'str' = 'markdown-it-py/commonmark', headings: 'int' = 0, sections: 'int' = 0, blocks: 'int' = 0) -> None` - class. One cached source-file fingerprint and parse summary.
|
|
- `CacheManifest(schema_version: 'str' = '1.0', root: 'str' = '.', entries: 'dict[str, CacheEntry]' = <factory>) -> None` - class. A file-backed cache manifest.
|
|
- `CacheStatus(new: 'list[str]' = <factory>, changed: 'list[str]' = <factory>, unchanged: 'list[str]' = <factory>, deleted: 'list[str]' = <factory>) -> None` - class. Change detection result against a cache manifest.
|
|
- `build_cache(paths: 'list[str | Path]', *, root: 'str | Path' = '.', recursive: 'bool' = True) -> 'CacheManifest'` - function. Build a cache manifest for Markdown files under paths.
|
|
- `cache_path_for(root: 'str | Path', cache_path: 'str | Path | None' = None) -> 'Path'` - function. Return the manifest path for a root and optional cache path.
|
|
- `detect_changes(manifest: 'CacheManifest', paths: 'list[str | Path]', *, root: 'str | Path' = '.', recursive: 'bool' = True) -> 'CacheStatus'` - function. Compare current Markdown files against a cache manifest.
|
|
- `fingerprint_file(path: 'str | Path', *, root: 'str | Path | None' = None) -> 'CacheEntry'` - function. Fingerprint one Markdown file and record a small parse summary.
|
|
- `load_cache(path: 'str | Path') -> 'CacheManifest'` - function. Load a cache manifest. Missing manifests produce an empty manifest.
|
|
- `save_cache(manifest: 'CacheManifest', path: 'str | Path') -> 'None'` - function. Write a cache manifest.
|
|
- `scan_markdown_files(paths: 'list[str | Path]', *, recursive: 'bool' = True) -> 'list[Path]'` - function. Return Markdown files for a set of files or directories.
|
|
|
|
## `markitect_tool.content_class.engine`
|
|
|
|
- `ClassCompositionResult(class_name: 'str', linearization: 'list[str]', slots: 'dict[str, Any]', diagnostics: 'list[Diagnostic]' = <factory>) -> None` - class. Resolved content class slots plus diagnostics.
|
|
- `ContentClass(name: 'str', extends: 'list[str]' = <factory>, slots: 'dict[str, Any]' = <factory>, merge_policies: 'dict[str, str]' = <factory>) -> None` - class. A data-defined content class.
|
|
- `ContentClassRegistry(classes: 'dict[str, ContentClass] | None' = None) -> 'None'` - class. Registry and resolver for content classes.
|
|
- `ContentClassResolutionError` - class. Raised when content class definitions cannot be loaded.
|
|
- `load_content_class_file(path: 'str | Path') -> 'ContentClassRegistry'` - function. Load content class definitions from YAML.
|
|
- `load_content_classes(data: 'dict[str, Any]') -> 'ContentClassRegistry'` - function. Load content class definitions from a mapping.
|
|
|
|
## `markitect_tool.contract.checker`
|
|
|
|
- `ContractCheckResult(valid: 'bool', diagnostics: 'list[Diagnostic]', document_path: 'str | None' = None, contract_path: 'str | None' = None, metrics: 'dict[str, Any]' = <factory>, runtime: 'dict[str, Any]' = <factory>) -> None` - class. Check result for one document and one contract.
|
|
- `ContractValidationResult(valid: 'bool', diagnostics: 'list[Diagnostic]', contract_path: 'str | None' = None) -> None` - class. Validation result for a contract definition.
|
|
- `check_document_contract(document: 'Document', contract: 'DocumentContract', *, runtime_context: 'RuntimeContext | None' = None) -> 'ContractCheckResult'` - function. Check a parsed Markdown document against a document contract.
|
|
- `check_markdown_file(markdown_path: 'str | Path', contract_path: 'str | Path', *, context_path: 'str | Path | None' = None, runtime_context: 'RuntimeContext | None' = None) -> 'ContractCheckResult'` - function. Parse and check a Markdown file against a contract file.
|
|
- `validate_contract(contract: 'DocumentContract') -> 'ContractValidationResult'` - function. Validate the contract definition itself.
|
|
- `validate_contract_file(contract_path: 'str | Path') -> 'ContractValidationResult'` - function. Load and validate a Markdown contract file.
|
|
|
|
## `markitect_tool.contract.loader`
|
|
|
|
- `load_contract_file(path: 'str | Path') -> 'DocumentContract'` - function. Load a Markdown-native document contract file.
|
|
|
|
## `markitect_tool.contract.metrics`
|
|
|
|
- `collect_metrics(document: 'Document') -> 'DocumentMetrics'` - function. Collect document-level and section-level metrics.
|
|
|
|
## `markitect_tool.contract.model`
|
|
|
|
- `DocumentContract(id: 'str | None', document_type: 'str | None', title: 'str | None' = None, version: 'str | None' = None, description: 'str | None' = None, sections: 'list[SectionSpec]' = <factory>, fields: 'list[FieldSpec]' = <factory>, metrics: 'list[MetricBand]' = <factory>, assertions: 'list[AssertionSpec]' = <factory>, forms: 'list[dict[str, Any]]' = <factory>, context: 'dict[str, Any]' = <factory>, rules: 'list[dict[str, Any]]' = <factory>, rubrics: 'list[dict[str, Any]]' = <factory>, metadata: 'dict[str, Any]' = <factory>, raw: 'dict[str, Any]' = <factory>, source_path: 'str | None' = None, source_line: 'int | None' = None) -> None` - class. A contract for a typed Markdown document.
|
|
|
|
## `markitect_tool.core.document`
|
|
|
|
- `ContentBlock(type: 'str', text: 'str', line_start: 'int | None' = None, line_end: 'int | None' = None, heading_level: 'int | None' = None) -> None` - class. A top-level Markdown content block.
|
|
- `Document(source_path: 'str | None', frontmatter: 'dict[str, Any]', body: 'str', blocks: 'list[ContentBlock]', headings: 'list[Heading]', sections: 'list[Section]', tokens: 'list[dict[str, Any]]') -> None` - class. Structured representation of a Markdown document.
|
|
- `Heading(level: 'int', text: 'str', line: 'int') -> None` - class. A Markdown heading with source location.
|
|
- `Section(heading: 'Heading', blocks: 'list[ContentBlock]' = <factory>) -> None` - class. A heading-led section.
|
|
|
|
## `markitect_tool.core.parser`
|
|
|
|
- `MarkdownParseError` - class. Raised when Markdown metadata cannot be parsed safely.
|
|
- `parse_markdown(markdown: 'str', source_path: 'str | None' = None) -> 'Document'` - function. Parse Markdown text into frontmatter, blocks, headings, sections, and tokens.
|
|
- `parse_markdown_file(path: 'str | Path') -> 'Document'` - function. Parse a Markdown file into a structured document.
|
|
|
|
## `markitect_tool.diagnostics`
|
|
|
|
- `Diagnostic(severity: 'str', code: 'str', message: 'str', source: 'SourceLocation | None' = None, contract: 'SourceLocation | None' = None, rule_id: 'str | None' = None, guidance: 'str | None' = None, details: 'dict[str, Any]' = <factory>) -> None` - class. A structured validation or assessment finding.
|
|
- `ProcessingDiagnostic(severity: 'str', code: 'str', message: 'str', source: 'SourceLocation | None' = None, contract: 'SourceLocation | None' = None, rule_id: 'str | None' = None, guidance: 'str | None' = None, details: 'dict[str, Any]' = <factory>) -> None` - class. A structured validation or assessment finding.
|
|
- `SourceLocation(path: 'str | None' = None, line: 'int | None' = None, column: 'int | None' = None) -> None` - class. A source location inside a document or contract.
|
|
|
|
## `markitect_tool.document_function`
|
|
|
|
- `DocumentFunctionCall(function_id: 'str', args: 'list[Any]' = <factory>, kwargs: 'dict[str, Any]' = <factory>, body: 'str | None' = None, raw: 'str' = '', inline: 'bool' = True, line: 'int | None' = None, pipeline: "list['DocumentFunctionCall']" = <factory>) -> None` - class. Parsed document function call.
|
|
- `DocumentFunctionDescriptor(id: 'str', summary: 'str', parameters: 'list[DocumentFunctionParameter]' = <factory>, output_type: 'str' = 'markdown', execution: 'str' = 'deterministic', capabilities: 'list[ProcessingCapability]' = <factory>, safety: 'dict[str, Any]' = <factory>, examples: 'list[str]' = <factory>, metadata: 'dict[str, Any]' = <factory>, implementation: 'FunctionImplementation | None' = None) -> None` - class. Inspectable descriptor for a document function.
|
|
- `DocumentFunctionError` - class. Raised when document function parsing or evaluation fails.
|
|
- `DocumentFunctionEvaluationResult(content: 'str', calls: 'list[DocumentFunctionRun]' = <factory>, diagnostics: 'list[Diagnostic]' = <factory>, provenance: 'list[ProcessingProvenance]' = <factory>, trace: 'list[ProcessingTrace]' = <factory>) -> None` - class. Result of expanding document functions in a Markdown document.
|
|
- `DocumentFunctionParameter(name: 'str', kind: 'str' = 'string', required: 'bool' = True, default: 'Any' = None, variadic: 'bool' = False, description: 'str | None' = None) -> None` - class. One declared document function parameter.
|
|
- `DocumentFunctionRegistry(descriptors: 'list[DocumentFunctionDescriptor] | None' = None) -> 'None'` - class. Registry and evaluator for document functions.
|
|
- `DocumentFunctionRun(call: 'DocumentFunctionCall', output: 'Any' = None, value: 'DocumentValue | None' = None, diagnostics: 'list[Diagnostic]' = <factory>, provenance: 'list[ProcessingProvenance]' = <factory>, trace: 'list[ProcessingTrace]' = <factory>) -> None` - class. One function call result.
|
|
- `DocumentValue(kind: 'str', value: 'Any' = None, items: "list['DocumentValue']" = <factory>, fields: "dict[str, 'DocumentValue']" = <factory>, metadata: 'dict[str, Any]' = <factory>, provenance: 'list[dict[str, Any]]' = <factory>) -> None` - class. Typed value produced by a document function.
|
|
- `coerce_document_value(value: 'Any', *, declared_kind: 'str' = 'dynamic') -> 'DocumentValue'` - function. Coerce a Python value into a typed document value.
|
|
- `default_document_function_registry() -> 'DocumentFunctionRegistry'` - function. Return built-in deterministic document functions.
|
|
- `document_value_to_json(value: 'DocumentValue | Any') -> 'dict[str, Any]'` - function. Return the stable JSON-compatible representation of a document value.
|
|
- `format_document_value(value: 'DocumentValue | Any', *, inline: 'bool') -> 'str'` - function. Map a typed document value to deterministic Markdown text.
|
|
- `parse_document_function_calls(text: 'str') -> 'list[DocumentFunctionCall]'` - function. Parse inline and fenced document function calls.
|
|
- `render_document_functions(text: 'str', *, registry: 'DocumentFunctionRegistry | None' = None, context: 'ProcessingContext | None' = None) -> 'DocumentFunctionEvaluationResult'` - function. Expand deterministic document functions in Markdown content.
|
|
- `validate_document_functions(text: 'str', *, registry: 'DocumentFunctionRegistry | None' = None, allowed: 'list[str] | None' = None, forbidden: 'list[str] | None' = None) -> 'DocumentFunctionEvaluationResult'` - function. Validate function calls without rendering the document.
|
|
|
|
## `markitect_tool.explode.engine`
|
|
|
|
- `ExplodeEntry(kind: 'str', file: 'str', order: 'int', unit_id: 'str', line_start: 'int', line_end: 'int', heading_level: 'int | None' = None, heading_text: 'str | None' = None, content_hash: 'str' = '') -> None` - class. One file entry in an exploded Markdown directory.
|
|
- `ExplodeError` - class. Raised when explode or implode cannot preserve a safe roundtrip.
|
|
- `ExplodeManifest(version: 'int', source_path: 'str', source_hash: 'str', variant: 'str', frontmatter_raw: 'str' = '', entries: 'list[ExplodeEntry]' = <factory>) -> None` - class. Manifest used to implode an exploded Markdown directory.
|
|
- `ExplodeResult(manifest_path: 'str', output_dir: 'str', manifest: 'ExplodeManifest', written_files: 'list[str]') -> None` - class. Result of exploding a Markdown file into a directory.
|
|
- `ImplodeResult(markdown: 'str', manifest_path: 'str', source_hash: 'str', current_hash: 'str', entries: 'list[str]') -> None` - class. Result of rebuilding Markdown from an explode manifest.
|
|
- `explode_markdown_file(path: 'str | Path', output_dir: 'str | Path', *, variant: 'str' = 'flat', overwrite: 'bool' = False) -> 'ExplodeResult'` - function. Explode a Markdown file into section files plus a roundtrip manifest.
|
|
- `implode_markdown_directory(directory: 'str | Path', *, manifest_path: 'str | Path | None' = None) -> 'ImplodeResult'` - function. Implode a Markdown directory created by :func:`explode_markdown_file`.
|
|
- `load_explode_manifest(path: 'str | Path') -> 'ExplodeManifest'` - function. Load an explode manifest from YAML.
|
|
|
|
## `markitect_tool.extension`
|
|
|
|
- `builtin_extension_registry()` - function. Return built-in extension descriptors without import-cycle pressure.
|
|
|
|
## `markitect_tool.extension.execution`
|
|
|
|
- `ExtensionExecutor(registry: 'ExtensionRegistry', *, lifecycle: 'ExtensionLifecycle | None' = None) -> 'None'` - class. Execute registered extensions with deterministic lifecycle callbacks.
|
|
- `ExtensionLifecycle(before: 'list[BeforeCallback]' = <factory>, after_success: 'list[AfterCallback]' = <factory>, after_failure: 'list[AfterCallback]' = <factory>, after: 'list[AfterCallback]' = <factory>) -> None` - class. Explicit callbacks around extension execution.
|
|
|
|
## `markitect_tool.extension.processing`
|
|
|
|
- `ProcessingCapability(id: 'str', kind: 'str' = 'feature', required: 'bool' = True, description: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. A declared capability or permission needed by an extension.
|
|
- `ProcessingContext(root: 'Path' = PosixPath('.'), source_path: 'Path | None' = None, namespaces: 'dict[str, str]' = <factory>, variables: 'dict[str, Any]' = <factory>, policy: 'dict[str, Any]' = <factory>, backend_handles: 'dict[str, Any]' = <factory>, caller: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Shared execution context available to extension implementations.
|
|
- `ProcessingProvenance(operation: 'str', source_path: 'str | None' = None, snapshot_id: 'str | None' = None, content_hash: 'str | None' = None, dependencies: 'list[str]' = <factory>, backend_id: 'str | None' = None, provider_id: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Cross-extension provenance envelope.
|
|
- `ProcessingRequest(operation: 'str', input: 'Any', context: 'ProcessingContext' = <factory>, options: 'dict[str, Any]' = <factory>, scope: 'str | None' = None, capabilities: 'list[ProcessingCapability]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Canonical request passed to an internal extension.
|
|
- `ProcessingResult(output: 'Any' = None, diagnostics: 'list[Diagnostic]' = <factory>, provenance: 'list[ProcessingProvenance]' = <factory>, dependencies: 'list[str]' = <factory>, trace: 'list[ProcessingTrace]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Canonical result returned by an internal extension.
|
|
- `ProcessingTrace(event: 'str', message: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. One optional execution trace event.
|
|
|
|
## `markitect_tool.extension.registry`
|
|
|
|
- `ExtensionDependencyCheck(extension_id: 'str', missing: 'list[str]' = <factory>, optional_missing: 'list[str]' = <factory>) -> None` - class. Result of checking required extension dependencies.
|
|
- `ExtensionDescriptor(id: 'str', kind: 'str', version: 'str' = '1', summary: 'str | None' = None, factory: 'ExtensionFactory | None' = None, capabilities: 'list[ProcessingCapability]' = <factory>, optional_dependencies: 'list[OptionalDependency]' = <factory>, safety: 'dict[str, Any]' = <factory>, input_contract: 'str | None' = None, output_contract: 'str | None' = None, diagnostics_namespace: 'str | None' = None, provenance_prefix: 'str | None' = None, cli: 'dict[str, Any]' = <factory>, docs: 'list[str]' = <factory>, examples: 'list[str]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Inspectable descriptor for one internal extension.
|
|
- `ExtensionRegistry(descriptors: 'Iterable[ExtensionDescriptor] | None' = None) -> 'None'` - class. Registry of internal extension descriptors.
|
|
- `ExtensionRegistryError` - class. Raised when extension descriptors or registries are invalid.
|
|
- `OptionalDependency(name: 'str', package: 'str | None' = None, extra: 'str | None' = None, required: 'bool' = False, purpose: 'str | None' = None) -> None` - class. An optional runtime dependency declared by an extension.
|
|
|
|
## `markitect_tool.generation.engine`
|
|
|
|
- `GeneratedDocument(markdown: 'str', output_path: 'str | None' = None, source_template: 'str | None' = None, data: 'dict[str, Any]' = <factory>, missing_variables: 'list[str]' = <factory>) -> None` - class. One generated Markdown document.
|
|
- `GenerationHookRequest(prompt: 'str', data: 'dict[str, Any]' = <factory>, template: 'str | None' = None, contract_id: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Provider-neutral request for optional assisted generation.
|
|
- `GenerationHookResult(markdown: 'str', provider: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Provider-neutral response from an assisted generation hook.
|
|
- `GenerationPlan(documents: 'list[dict[str, Any]]', source_path: 'str | None' = None) -> None` - class. Markdown/YAML rule-based generation plan.
|
|
- `GenerationResult(documents: 'list[GeneratedDocument]', plan_path: 'str | None' = None) -> None` - class. Result of a deterministic generation run.
|
|
- `generate_stub_from_contract(contract: 'DocumentContract', *, data: 'dict[str, Any] | None' = None, include_optional: 'bool' = False) -> 'GeneratedDocument'` - function. Generate a Markdown stub from a document contract.
|
|
- `generate_with_hook(request: 'GenerationHookRequest', hook: 'GenerationHook') -> 'GenerationHookResult'` - function. Run optional assisted generation through an external hook.
|
|
- `load_generation_plan_file(path: 'str | Path') -> 'GenerationPlan'` - function. Load a generation plan from a Markdown file with a fenced YAML block.
|
|
- `run_generation_plan(plan: 'GenerationPlan', *, base_dir: 'str | Path | None' = None, output_dir: 'str | Path | None' = None, dry_run: 'bool' = False) -> 'GenerationResult'` - function. Render every document described by a generation plan.
|
|
|
|
## `markitect_tool.literate.engine`
|
|
|
|
- `CodeChunk(chunk_id: 'str', content: 'str', language: 'str | None' = None, target_path: 'str | None' = None, references: 'list[str]' = <factory>, source_path: 'str | None' = None, line_start: 'int | None' = None, line_end: 'int | None' = None, content_hash: 'str' = '') -> None` - class. A named fenced code chunk.
|
|
- `LiterateFile(path: 'str', content: 'str', chunk_ids: 'list[str]') -> None` - class. One generated file from tangling.
|
|
- `TangleResult(files: 'list[LiterateFile]', chunks: 'list[CodeChunk]', diagnostics: 'list[Diagnostic]' = <factory>, provenance: 'list[OperationProvenance]' = <factory>) -> None` - class. Result of tangling Markdown code chunks.
|
|
- `WeaveResult(markdown: 'str', chunks: 'list[CodeChunk]') -> None` - class. Result of weaving Markdown documentation with a chunk index.
|
|
- `discover_code_chunks(markdown: 'str', *, source_path: 'str | Path | None' = None) -> 'list[CodeChunk]'` - function. Discover named fenced code chunks in Markdown order.
|
|
- `tangle_markdown(markdown: 'str', *, source_path: 'str | Path | None' = None) -> 'TangleResult'` - function. Tangle named chunks into target files.
|
|
- `weave_markdown(markdown: 'str', *, source_path: 'str | Path | None' = None) -> 'WeaveResult'` - function. Append a deterministic chunk index to human-readable Markdown.
|
|
- `write_tangle_files(result: 'TangleResult', output_dir: 'str | Path') -> 'list[str]'` - function. Write tangled files under an output directory.
|
|
|
|
## `markitect_tool.memory.engine`
|
|
|
|
- `ContextActivation(id: 'str', package_id: 'str', status: 'str', target: 'str', content: 'str', items: 'list[ContextPackageItem]', summaries: 'list[SummaryLayer]' = <factory>, token_estimate: 'int' = 0, created_at: 'str' = <factory>, policy: 'dict[str, Any]' = <factory>, policy_decisions: 'list[dict[str, Any]]' = <factory>, diagnostics: 'list[dict[str, Any]]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Result of activating or deactivating a context package.
|
|
- `ContextBudget(max_tokens: 'int | None' = None, max_items: 'int | None' = None, reserve_tokens: 'int' = 0, strategy: 'str' = 'first-fit') -> None` - class. Token and item budget applied while creating or activating context.
|
|
- `ContextPackage(id: 'str', title: 'str', intent: 'str', namespace: 'MemoryNamespace', items: 'list[ContextPackageItem]', retrieval_recipes: 'list[RetrievalRecipe]' = <factory>, summaries: 'list[SummaryLayer]' = <factory>, budget: 'ContextBudget' = <factory>, activation_state: 'str' = 'inactive', created_at: 'str' = <factory>, updated_at: 'str' = <factory>, freshness: 'dict[str, Any]' = <factory>, policy: 'dict[str, Any]' = <factory>, provenance: 'list[dict[str, Any]]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Portable, inspectable context package for agent working memory.
|
|
- `ContextPackageError` - class. Raised when a context package cannot be created, loaded, or activated.
|
|
- `ContextPackageItem(id: 'str', source: 'SourceSpan', text: 'str', summary: 'str', token_estimate: 'int', score: 'float | None' = None, policy: 'dict[str, Any]' = <factory>, provenance: 'dict[str, Any]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. One item included in an agent-ready context package.
|
|
- `LocalContextPackageRegistry(root: 'str | Path' = '.') -> 'None'` - class. Filesystem-backed local context package registry.
|
|
- `MemoryNamespace(project: 'str | None' = None, user: 'str | None' = None, agent: 'str | None' = None, thread: 'str | None' = None, task: 'str | None' = None, custom: 'dict[str, Any]' = <factory>) -> None` - class. Stable namespace coordinates for agent memory packages.
|
|
- `MemorySourceSpan(path: 'str', snapshot_id: 'str | None' = None, unit_kind: 'str | None' = None, unit_index: 'int | None' = None, line_start: 'int | None' = None, line_end: 'int | None' = None, selector: 'str | None' = None, engine: 'str | None' = None) -> None` - class. Source range represented in a memory package.
|
|
- `RetrievalRecipe(kind: 'str', query: 'str', engine: 'str' = 'selector', sources: 'list[str]' = <factory>, paths: 'list[str]' = <factory>, root: 'str' = '.', index_path: 'str | None' = None, limit: 'int | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Recipe that can refresh memory package contents.
|
|
- `SummaryLayer(name: 'str', kind: 'str', text: 'str', token_estimate: 'int', generated_by: 'str' = 'markitect.deterministic', metadata: 'dict[str, Any]' = <factory>) -> None` - class. One deterministic or assisted summary layer.
|
|
- `activate_context_package(package: 'ContextPackage', *, target: 'str' = 'default', policy_gateway: 'LocalLabelPolicyGateway | None' = None, subject: 'str' = 'anonymous', action: 'str' = 'read', budget: 'ContextBudget | None' = None) -> 'ContextActivation'` - function. Activate a package into a Markdown context bundle.
|
|
- `create_context_package_from_index(query: 'str', *, root: 'str | Path' = '.', index_path: 'str | Path | None' = None, engine: 'str' = 'selector', paths: 'list[str] | None' = None, search: 'bool' = False, limit: 'int' = 20, title: 'str | None' = None, intent: 'str | None' = None, namespace: 'MemoryNamespace | None' = None, budget: 'ContextBudget | None' = None, policy_gateway: 'LocalLabelPolicyGateway | None' = None, subject: 'str' = 'anonymous', action: 'str' = 'package', package_id: 'str | None' = None) -> 'ContextPackage'` - function. Create a context package from the local SQLite index.
|
|
- `create_context_package_from_manifest(manifest_path: 'str | Path', *, root: 'str | Path' = '.', budget: 'ContextBudget | None' = None, policy_gateway: 'LocalLabelPolicyGateway | None' = None, subject: 'str' = 'anonymous', action: 'str' = 'package') -> 'ContextPackage'` - function. Create a context package from a YAML/JSON manifest file.
|
|
- `create_context_package_from_sources(query: 'str', sources: 'list[str | Path]', *, root: 'str | Path' = '.', engine: 'str' = 'selector', title: 'str | None' = None, intent: 'str | None' = None, namespace: 'MemoryNamespace | None' = None, budget: 'ContextBudget | None' = None, policy_gateway: 'LocalLabelPolicyGateway | None' = None, subject: 'str' = 'anonymous', action: 'str' = 'package', package_id: 'str | None' = None) -> 'ContextPackage'` - function. Create a context package by querying Markdown source files directly.
|
|
- `deactivate_context_package(activation: 'ContextActivation') -> 'ContextActivation'` - function. Return a deactivated activation envelope.
|
|
- `explain_context_package(package: 'ContextPackage') -> 'dict[str, Any]'` - function. Return provenance, budget, policy, namespace, and retrieval details.
|
|
- `load_context_package_file(path: 'str | Path') -> 'ContextPackage'` - function. Load a context package from YAML or JSON.
|
|
- `refresh_context_package(package: 'ContextPackage', *, policy_gateway: 'LocalLabelPolicyGateway | None' = None, subject: 'str' = 'anonymous', action: 'str' = 'package') -> 'ContextPackage'` - function. Refresh a package by re-running its retrieval recipes.
|
|
|
|
## `markitect_tool.ops.engine`
|
|
|
|
- `ComposeResult(markdown: 'str', sources: 'list[str]' = <factory>) -> None` - class. Result of composing multiple Markdown sources.
|
|
- `IncludeError` - class. Raised when include resolution cannot continue.
|
|
- `IncludeResult(markdown: 'str', included_paths: 'list[str]' = <factory>, provenance: 'list[OperationProvenance]' = <factory>) -> None` - class. Result of resolving include markers in Markdown.
|
|
- `OperationProvenance(operation: 'str', source_path: 'str | None' = None, line_start: 'int | None' = None, line_end: 'int | None' = None, target_path: 'str | None' = None, dependencies: 'list[str]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Structured provenance for deterministic Markdown operations.
|
|
- `TransformResult(markdown: 'str', operations: 'list[str]' = <factory>, provenance: 'list[OperationProvenance]' = <factory>) -> None` - class. Result of a deterministic Markdown transform.
|
|
- `compose_files(paths: 'list[str | Path]', *, title: 'str | None' = None, heading_delta: 'int' = 0, include_frontmatter: 'bool' = False, separator: 'str' = '\n\n---\n\n') -> 'ComposeResult'` - function. Compose Markdown files into one Markdown output.
|
|
- `resolve_includes(markdown: 'str', *, base_dir: 'str | Path', current_path: 'str | Path | None' = None, max_depth: 'int' = 10) -> 'IncludeResult'` - function. Resolve Markdown include markers recursively.
|
|
- `transform_markdown(markdown: 'str', *, strip_frontmatter: 'bool' = False, set_frontmatter: 'dict[str, Any] | None' = None, heading_delta: 'int' = 0, extract_selector: 'str | None' = None, source_path: 'str | None' = None) -> 'TransformResult'` - function. Apply deterministic operations to one Markdown document.
|
|
|
|
## `markitect_tool.policy.adapters`
|
|
|
|
- `DecisionLogStore(*args, **kwargs)` - class. Persistent audit boundary for policy decisions.
|
|
- `DirectoryGroupResolution(groups: 'list[str]' = <factory>, source: 'str | None' = None, refreshed_at: 'str | None' = None, overage: 'bool' = False, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Directory group resolution result with freshness and source provenance.
|
|
- `DirectoryGroupResolutionRequest(subject_id: 'str', issuer: 'str', groups: 'list[str]' = <factory>, claims: 'dict[str, Any]' = <factory>, context: 'dict[str, Any]' = <factory>) -> None` - class. Request for resolving group claims that are stale, partial, or overlarge.
|
|
- `DirectoryGroupResolver(*args, **kwargs)` - class. Adapter boundary for SCIM/LDAP/Graph/Keycloak group resolution.
|
|
- `EnterpriseIdentity(issuer: 'str', subject: 'str', identity_scheme: 'str' = 'oidc', principal_type: 'str' = 'human', audience: 'list[str]' = <factory>, authorized_party: 'str | None' = None, preferred_username: 'str | None' = None, roles: 'list[str]' = <factory>, scopes: 'list[str]' = <factory>, groups: 'list[str]' = <factory>, assurance: 'dict[str, Any]' = <factory>, directory: 'dict[str, Any]' = <factory>, claims: 'dict[str, Any]' = <factory>, provenance: 'dict[str, Any]' = <factory>) -> None` - class. Verified enterprise identity claims normalized for policy mapping.
|
|
- `EnterprisePolicyMapRequest(identity: 'EnterpriseIdentity | dict[str, Any]', policy_map: 'dict[str, Any]' = <factory>, groups: 'list[str]' = <factory>, context: 'dict[str, Any]' = <factory>) -> None` - class. Request to map enterprise claims onto Markitect policy vocabulary.
|
|
- `EnterprisePolicyMapper(*args, **kwargs)` - class. Adapter boundary for mapping IAM roles/groups/scopes to policy subjects.
|
|
- `IdentityClaimsAdapter(*args, **kwargs)` - class. Adapter boundary for OIDC/JWT/SAML verification and normalization.
|
|
- `RelationshipPolicyAdapter(*args, **kwargs)` - class. Adapter boundary for relationship authorization systems.
|
|
- `RelationshipPolicyRequest(subject: 'str', relation: 'str', object_id: 'str', namespace: 'str | None' = None, context: 'dict[str, Any]' = <factory>) -> None` - class. Relationship-based authorization request.
|
|
- `RulePolicyAdapter(*args, **kwargs)` - class. Adapter boundary for rule/attribute policy systems.
|
|
- `RulePolicyRequest(subject: 'dict[str, Any]', action: 'str', object: 'dict[str, Any]', context: 'dict[str, Any]' = <factory>, policy_id: 'str | None' = None) -> None` - class. Attribute/rule policy evaluation request.
|
|
|
|
## `markitect_tool.policy.enterprise`
|
|
|
|
- `EnterprisePolicyError` - class. Raised when enterprise identity or policy mapping is invalid.
|
|
- `EnterprisePolicyMap(id: 'str' = 'enterprise-policy-map', issuer: 'str | None' = None, audiences: 'list[str]' = <factory>, defaults: 'dict[str, Any]' = <factory>, groups: 'dict[str, dict[str, Any]]' = <factory>, roles: 'dict[str, dict[str, Any]]' = <factory>, scopes: 'dict[str, dict[str, Any]]' = <factory>, trust_zones: 'dict[str, dict[str, Any]]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Versioned Markitect-side mapping from IAM claims to policy subjects.
|
|
- `FlexAuthResource(id: 'str', type: 'str', path: 'str | None' = None, parent: 'str | None' = None, labels: 'list[str]' = <factory>, trust_zone: 'str | None' = None, owner: 'str | None' = None, attributes: 'dict[str, Any]' = <factory>) -> None` - class. Resource record Markitect can register with flex-auth.
|
|
- `FlexAuthResourceManifest(id: 'str', system: 'str' = 'markitect-tool', resources: 'list[FlexAuthResource]' = <factory>, actions: 'list[str]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Manifest of Markitect resources intended for flex-auth registration.
|
|
- `LocalDecisionLogStore(path: 'Path | None' = None) -> None` - class. Local JSONL decision sink for development and tests.
|
|
- `LocalEnterprisePolicyMapper(policy_map: 'EnterprisePolicyMap') -> None` - class. Map verified enterprise identity into Markitect's PolicySubject shape.
|
|
- `NetKingdomIdentityClaimsAdapter(issuer: 'str | None' = None, audiences: 'list[str]' = <factory>, clock_skew_seconds: 'int' = 60, reject_local_issuers_in_production: 'bool' = True) -> None` - class. Validate NetKingdom/key-cape-compatible claims and normalize identity.
|
|
- `StaticDirectoryGroupResolver(groups_by_subject: 'dict[str, list[str]]' = <factory>, source: 'str' = 'static', refreshed_at: 'str | None' = None) -> None` - class. Deterministic group resolver for fixtures and local development.
|
|
- `load_enterprise_identity_file(path: 'str | Path', *, issuer: 'str | None' = None, audiences: 'list[str] | None' = None, environment: 'str | None' = None) -> 'EnterpriseIdentity'` - function. Load and validate deterministic NetKingdom/key-cape-style claims.
|
|
- `load_enterprise_policy_subject(claims_file: 'str | Path', policy_map_file: 'str | Path', *, extra_groups: 'list[str] | None' = None, environment: 'str | None' = None) -> 'PolicySubject'` - function. Load claims and policy map files and return a gateway-ready subject.
|
|
|
|
## `markitect_tool.policy.local`
|
|
|
|
- `LocalLabelPolicy(id: 'str' = 'local-label-policy', mode: 'str' = 'enforce', default_labels: 'list[str]' = <factory>, default_trust_zone: 'str | None' = None, default_subject: 'str' = 'anonymous', on_denied: 'str' = 'drop', subjects: 'dict[str, PolicySubject]' = <factory>, path_rules: 'list[LocalPathPolicyRule]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Declarative local policy for labels, trust zones, and path ACLs.
|
|
- `LocalLabelPolicyGateway(policy: 'LocalLabelPolicy | dict[str, Any] | None' = None, *, mode: 'str | None' = None) -> 'None'` - class. AccessPolicyGateway implementation for local label policies.
|
|
- `LocalPathPolicyRule(pattern: 'str', labels: 'list[str]' = <factory>, trust_zone: 'str | None' = None, deny: 'bool' = False, id: 'str | None' = None) -> None` - class. Path rule that can add labels, set trust zone, or deny directly.
|
|
- `policy_metadata_from_document(document: 'dict[str, Any]', *, path: 'str | None' = None) -> 'dict[str, Any]'` - function. Extract stable policy metadata from parsed document frontmatter.
|
|
|
|
## `markitect_tool.policy.models`
|
|
|
|
- `PolicyDecision(subject: 'str', action: 'str', object_id: 'str', effect: 'str', reason: 'str', mode: 'str' = 'enforce', rule_id: 'str | None' = None, labels: 'list[str]' = <factory>, trust_zone: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Explainable policy decision for one subject/action/object tuple.
|
|
- `PolicyFilterResult(results: 'list[dict[str, Any]]', decisions: 'list[PolicyDecision]' = <factory>, diagnostics: 'list[Any]' = <factory>, mode: 'str' = 'enforce', subject: 'str | None' = None, action: 'str | None' = None) -> None` - class. Results after policy filtering plus decision and diagnostic metadata.
|
|
- `PolicyObject(id: 'str', path: 'str | None' = None, labels: 'list[str]' = <factory>, trust_zone: 'str | None' = None, attributes: 'dict[str, Any]' = <factory>) -> None` - class. Knowledge object considered by a policy decision.
|
|
- `PolicySubject(id: 'str', allowed_labels: 'list[str]' = <factory>, trust_zones: 'list[str]' = <factory>, roles: 'list[str]' = <factory>, allowed_actions: 'list[str]' = <factory>, path_allow: 'list[str]' = <factory>, path_deny: 'list[str]' = <factory>, attributes: 'dict[str, Any]' = <factory>) -> None` - class. Actor asking to read, query, search, or package knowledge.
|
|
|
|
## `markitect_tool.processor.engine`
|
|
|
|
- `FencedProcessorBlock(processor: 'str', content: 'str', unit_id: 'str', attrs: 'dict[str, str]', language: 'str | None' = None, source_path: 'str | None' = None, line_start: 'int | None' = None, line_end: 'int | None' = None, content_hash: 'str' = '') -> None` - class. A fenced Markdown block that opted into processor handling.
|
|
- `ProcessorContext(root: 'Path' = PosixPath('.'), current_path: 'Path | None' = None, namespaces: 'dict[str, str]' = <factory>, variables: 'dict[str, Any]' = <factory>, policy: 'dict[str, Any]' = <factory>) -> None` - class. Execution context passed to deterministic processors.
|
|
- `ProcessorOutputFile(path: 'str', content: 'str') -> None` - class. A generated file requested by a processor.
|
|
- `ProcessorRegistry() -> 'None'` - class. Explicit registry for deterministic fenced-block processors.
|
|
- `ProcessorRequest(block: 'FencedProcessorBlock', context: 'ProcessorContext') -> None` - class. One processor invocation.
|
|
- `ProcessorResult(content: 'str | None' = None, files: 'list[ProcessorOutputFile]' = <factory>, diagnostics: 'list[Diagnostic]' = <factory>, dependencies: 'list[str]' = <factory>, provenance: 'list[OperationProvenance]' = <factory>) -> None` - class. Deterministic processor result envelope.
|
|
- `ProcessorRun(source_path: 'str | None', blocks: 'list[FencedProcessorBlock]', results: 'list[ProcessorResult]') -> None` - class. Results from running all processor blocks in a document.
|
|
- `default_processor_registry() -> 'ProcessorRegistry'` - function. Create the default deterministic processor registry.
|
|
- `discover_fenced_processors(markdown: 'str', *, source_path: 'str | Path | None' = None) -> 'list[FencedProcessorBlock]'` - function. Discover fenced blocks that explicitly opt into processor handling.
|
|
- `run_fenced_processors(markdown: 'str', *, context: 'ProcessorContext', registry: 'ProcessorRegistry | None' = None, source_path: 'str | Path | None' = None) -> 'ProcessorRun'` - function. Run all processor-marked fenced blocks in document order.
|
|
|
|
## `markitect_tool.query.engine`
|
|
|
|
- `InvalidQueryError` - class. Raised when a selector cannot be parsed or evaluated.
|
|
- `QueryMatch(kind: 'str', path: 'str', value: 'Any', text: 'str | None' = None, line: 'int | None' = None) -> None` - class. One match returned by a selector.
|
|
- `extract_document(document: 'Document', selector: 'str') -> 'list[str]'` - function. Extract text content from query matches.
|
|
- `extract_document_jsonpath(document: 'Document', expression: 'str') -> 'list[str]'` - function. Extract textual JSONPath matches from a parsed document.
|
|
- `extract_document_with_engine(document: 'Document', selector: 'str', *, engine: 'str' = 'selector') -> 'list[str]'` - function. Extract textual query matches through a registered query engine.
|
|
- `query_document(document: 'Document', selector: 'str') -> 'list[QueryMatch]'` - function. Query a parsed document with a small Markitect selector.
|
|
- `query_document_jsonpath(document: 'Document', expression: 'str') -> 'list[QueryMatch]'` - function. Query a parsed document with JSONPath over ``Document.to_dict()``.
|
|
- `query_document_with_engine(document: 'Document', selector: 'str', *, engine: 'str' = 'selector') -> 'list[QueryMatch]'` - function. Query a parsed document through a registered query engine.
|
|
|
|
## `markitect_tool.query.registry`
|
|
|
|
- `QueryEngine(descriptor: 'ExtensionDescriptor', query: 'QueryCallable') -> None` - class. Registered query engine implementation.
|
|
- `QueryEngineRegistry(engines: 'list[QueryEngine] | None' = None) -> 'None'` - class. Registry of query engines keyed by short engine id.
|
|
- `default_query_engine_registry() -> 'QueryEngineRegistry'` - function. Return the built-in query engine registry.
|
|
|
|
## `markitect_tool.reference.engine`
|
|
|
|
- `ContentUnit(kind: 'str', unit_id: 'str', text: 'str', source_path: 'str', span: 'SourceSpan | None' = None, name: 'str | None' = None, content_hash: 'str' = '', metadata: 'dict[str, Any]' = <factory>) -> None` - class. One addressable content unit resolved from Markdown.
|
|
- `ReferenceAddress(raw: 'str', namespace: 'str | None' = None, address: 'str' = '', fragment: 'str | None' = None, selector: 'str | None' = None) -> None` - class. Parsed content reference address.
|
|
- `ReferenceContext(root: 'Path' = PosixPath('.'), current_path: 'Path | None' = None, namespaces: 'dict[str, str]' = <factory>) -> None` - class. Inputs used to resolve namespaced and relative content references.
|
|
- `ReferenceResolution(reference: 'ReferenceAddress', source_path: 'str', target_path: 'str', units: 'list[ContentUnit]') -> None` - class. Resolved content reference and its dependency edge.
|
|
- `ReferenceResolutionError` - class. Raised when a content reference cannot be resolved.
|
|
- `ReferenceSourceSpan(line_start: 'int | None' = None, line_end: 'int | None' = None) -> None` - class. Line span for a resolved unit in its source file.
|
|
- `load_namespaces(frontmatter: 'dict[str, Any]') -> 'dict[str, str]'` - function. Load namespace mappings from Markdown frontmatter.
|
|
- `parse_reference(reference: 'str') -> 'ReferenceAddress'` - function. Parse a compact Markitect content reference.
|
|
- `resolve_reference(reference: 'str | ReferenceAddress', *, context: 'ReferenceContext') -> 'ReferenceResolution'` - function. Resolve a content reference to one or more content units.
|
|
|
|
## `markitect_tool.runtime.assessment`
|
|
|
|
- `AssessmentRequest(contract_id: 'str | None', rule_id: 'str', scope: 'str', text: 'str', criteria: 'Any', context: 'dict[str, Any]' = <factory>, structured_inputs: 'dict[str, Any]' = <factory>, severity: 'str' = 'error', threshold: 'float | None' = None, provider: 'str | None' = None, model: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. A provider-neutral request for rubric assessment.
|
|
- `AssessmentResult(rule_id: 'str', passed: 'bool', score: 'float | None' = None, reason: 'str | None' = None, diagnostics: 'list[Diagnostic]' = <factory>, provider: 'str | None' = None, model: 'str | None' = None, cache_key: 'str | None' = None, cached: 'bool' = False, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Normalized result returned by an assessment adapter.
|
|
- `AssessmentRunResult(assessments: 'list[AssessmentResult]' = <factory>, diagnostics: 'list[Diagnostic]' = <factory>) -> None` - class. Result of executing one or more rubric assessments.
|
|
- `AssessmentRunner(adapter: 'AssessmentAdapter', *, cache: 'AssessmentCache | None' = None) -> 'None'` - class. Invoke an injected assessment adapter and normalize diagnostics.
|
|
- `MemoryAssessmentCache() -> 'None'` - class. Transparent in-memory cache useful for tests and short workflow runs.
|
|
- `assessment_requests_for_contract(document: 'Document', contract: 'DocumentContract', runtime_context: 'RuntimeContext | None' = None) -> 'list[AssessmentRequest]'` - function. Create assessment requests for contract rubric declarations.
|
|
- `run_contract_assessments(document: 'Document', contract: 'DocumentContract', adapter: 'AssessmentAdapter', *, runtime_context: 'RuntimeContext | None' = None, cache: 'AssessmentCache | None' = None) -> 'AssessmentRunResult'` - function. Run all rubrics in a contract with an injected assessment adapter.
|
|
|
|
## `markitect_tool.runtime.context`
|
|
|
|
- `RuntimeContext(data: 'dict[str, Any]' = <factory>, metadata: 'dict[str, Any]' = <factory>, source_path: 'str | None' = None, sources: 'list[RuntimeContextSource]' = <factory>, schemas: 'dict[str, Any]' = <factory>, diagnostics: 'list[Diagnostic]' = <factory>) -> None` - class. Named external data available to contract checks and generation.
|
|
- `RuntimeContextLoadResult(context: 'RuntimeContext') -> None` - class. Context load result that can carry diagnostics instead of raising.
|
|
- `RuntimeContextSource(name: 'str | None' = None, path: 'str | None' = None, kind: 'str' = 'file', metadata: 'dict[str, Any]' = <factory>) -> None` - class. Origin metadata for one loaded context object.
|
|
- `load_runtime_context_file(path: 'str | Path') -> 'RuntimeContext'` - function. Load a runtime context from JSON or YAML.
|
|
- `load_runtime_context_file_result(path: 'str | Path') -> 'RuntimeContextLoadResult'` - function. Load a runtime context and represent malformed input as diagnostics.
|
|
|
|
## `markitect_tool.runtime.forms`
|
|
|
|
- `FieldState(id: 'str', path: 'str | None' = None, source: 'str | None' = None, type: 'str | None' = None, label: 'str | None' = None, description: 'str | None' = None, value: 'Any' = None, exists: 'bool' = False, origin: 'str' = 'missing', required: 'bool' = False, visible: 'bool' = True, enabled: 'bool' = True, allowed_values: 'list[Any] | None' = None, diagnostics: 'list[Diagnostic]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. UI-neutral runtime state for one contract field.
|
|
- `FormState(contract_id: 'str | None', document_path: 'str | None' = None, context_path: 'str | None' = None, fields: 'list[FieldState]' = <factory>, diagnostics: 'list[Diagnostic]' = <factory>, rules_applied: 'list[str]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. A complete runtime form state derived from a document contract.
|
|
- `evaluate_form_state(document: 'Document', contract: 'DocumentContract', runtime_context: 'RuntimeContext | None' = None) -> 'FormState'` - function. Evaluate contract fields, prefill sources, and dynamic runtime rules.
|
|
|
|
## `markitect_tool.schema.loader`
|
|
|
|
- `MarkdownSchema(schema: 'dict[str, Any]', metadata: 'dict[str, Any]', documentation: 'str', source_path: 'str | None' = None) -> None` - class. A JSON Schema loaded from a Markdown schema document.
|
|
- `load_schema_file(path: 'str | Path') -> 'MarkdownSchema'` - function. Load a Markdown schema file.
|
|
|
|
## `markitect_tool.schema.validator`
|
|
|
|
- `SchemaValidationResult(valid: 'bool', violations: 'list[ValidationViolation]', document_path: 'str | None' = None, schema_path: 'str | None' = None) -> None` - class. Validation result for one document and one schema.
|
|
- `ValidationViolation(path: 'str', message: 'str', schema_path: 'str') -> None` - class. A single schema validation violation.
|
|
- `validate_document(document: 'Document', schema: 'MarkdownSchema | dict[str, Any]') -> 'SchemaValidationResult'` - function. Validate a parsed document against a loaded or raw JSON Schema.
|
|
- `validate_markdown_file(markdown_path: 'str | Path', schema_path: 'str | Path') -> 'SchemaValidationResult'` - function. Parse and validate a Markdown file against a Markdown schema file.
|
|
- `validate_schema(schema: 'dict[str, Any]') -> 'SchemaValidationResult'` - function. Validate that a JSON Schema itself is well formed.
|
|
|
|
## `markitect_tool.source.engine`
|
|
|
|
- `NormalizationQuality(lossiness: 'str', confidence: 'float | None' = None, skipped_items: 'int | None' = None, warnings: 'int | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Summary of extraction lossiness and confidence.
|
|
- `NormalizedMarkdownDocument(document_id: 'str', asset: 'SourceAsset', metadata: 'SourceMetadata', markdown: 'str', segments: 'list[NormalizedMarkdownSegment]', quality: 'NormalizationQuality', adapter: 'dict[str, Any]', cache_key: 'str', schema_version: 'str' = 'markitect.source.v1', diagnostics: 'list[Diagnostic]' = <factory>, provenance: 'list[SourceProvenance]' = <factory>, attachments: 'list[SourceAsset]' = <factory>) -> None` - class. Canonical source-normalized Markdown document.
|
|
- `NormalizedMarkdownSegment(segment_id: 'str', order: 'int', markdown: 'str', heading: 'str | None' = None, heading_level: 'int | None' = None, anchors: 'list[str]' = <factory>, provenance: 'list[SourceProvenance]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. One ordered normalized Markdown segment.
|
|
- `SourceAdapterDescriptor(id: 'str', version: 'str', name: 'str', operations: 'list[str]', media_types: 'list[str]', extensions: 'list[str]', factory: 'SourceAdapterFactory', summary: 'str | None' = None, option_schema: 'dict[str, Any]' = <factory>, optional_dependencies: 'list[OptionalDependency]' = <factory>, safety: 'dict[str, Any]' = <factory>, quality_profile: 'dict[str, Any]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Inspectable descriptor for one source read adapter.
|
|
- `SourceAdapterError` - class. Raised when source adapter descriptors or registries are invalid.
|
|
- `SourceAdapterMatch(adapter_id: 'str', matched: 'bool', confidence: 'int' = 0, reason: 'str | None' = None, diagnostics: 'list[Diagnostic]' = <factory>) -> None` - class. Result of an adapter match attempt.
|
|
- `SourceAdapterMatchRequest(asset: 'SourceAsset', options: 'dict[str, Any]' = <factory>) -> None` - class. Cheap adapter matching request.
|
|
- `SourceAdapterRegistry(descriptors: 'Iterable[SourceAdapterDescriptor] | None' = None) -> 'None'` - class. Registry of source adapter descriptors.
|
|
- `SourceAsset(uri: 'str', path: 'str | None' = None, name: 'str | None' = None, media_type: 'str | None' = None, extension: 'str | None' = None, size: 'int | None' = None, mtime_ns: 'int | None' = None, digest: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Identity and filesystem metadata for one source asset.
|
|
- `SourceInspectRequest(asset: 'SourceAsset', options: 'dict[str, Any]' = <factory>) -> None` - class. Metadata-only source inspection request.
|
|
- `SourceInspectResult(asset: 'SourceAsset', adapter: 'dict[str, Any]', metadata: 'SourceMetadata', quality: 'NormalizationQuality', capabilities: 'list[str]' = <factory>, diagnostics: 'list[Diagnostic]' = <factory>, valid: 'bool | None' = None) -> None` - class. Metadata-only source inspection result.
|
|
- `SourceMetadata(title: 'str | None' = None, creators: 'list[str]' = <factory>, language: 'str | None' = None, rights: 'str | None' = None, source_url: 'str | None' = None, publication_date: 'str | None' = None, publisher: 'str | None' = None, identifiers: 'dict[str, str]' = <factory>, raw: 'dict[str, Any]' = <factory>) -> None` - class. Format-provided descriptive metadata.
|
|
- `SourceProvenance(source_uri: 'str', source_path: 'str | None' = None, source_href: 'str | None' = None, package_path: 'str | None' = None, anchor: 'str | None' = None, page: 'str | None' = None, section: 'str | None' = None, start_offset: 'int | None' = None, end_offset: 'int | None' = None, digest: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Trace from normalized Markdown back to source locations.
|
|
- `SourceReadAdapter(*args, **kwargs)` - class. Read-only source adapter protocol.
|
|
- `SourceReadRequest(asset: 'SourceAsset', options: 'dict[str, Any]' = <factory>) -> None` - class. Full source normalization request.
|
|
- `SourceReadResult(document: 'NormalizedMarkdownDocument | None' = None, diagnostics: 'list[Diagnostic]' = <factory>, valid: 'bool | None' = None) -> None` - class. Full source normalization result.
|
|
- `default_source_adapter_registry() -> 'SourceAdapterRegistry'` - function. Return the discovered source adapter registry.
|
|
- `discover_source_adapters(entry_points: 'Iterable[Any] | None' = None) -> 'SourceAdapterRegistry'` - function. Discover source adapters from package entry points.
|
|
- `inspect_source(path_or_uri: 'str | Path', *, registry: 'SourceAdapterRegistry | None' = None, adapter_id: 'str | None' = None, options: 'dict[str, Any] | None' = None) -> 'SourceInspectResult'` - function. Inspect a local source through the selected adapter.
|
|
- `normalization_cache_key(*, asset: 'SourceAsset', adapter_id: 'str', adapter_version: 'str', options: 'dict[str, Any] | None' = None) -> 'str'` - function. Compute a stable normalization cache key.
|
|
- `normalize_source(path_or_uri: 'str | Path', *, registry: 'SourceAdapterRegistry | None' = None, adapter_id: 'str | None' = None, options: 'dict[str, Any] | None' = None) -> 'SourceReadResult'` - function. Normalize a local source through the selected adapter.
|
|
- `source_adapter_registry_descriptor() -> 'ExtensionDescriptor'` - function. Return the built-in descriptor for source adapter discovery.
|
|
|
|
## `markitect_tool.template.engine`
|
|
|
|
- `MissingTemplateVariable` - class. Raised when strict rendering cannot resolve a variable.
|
|
- `TemplateAnalysis(variables: 'list[str]', root_variables: 'list[str]', nested_variables: 'list[str]', syntax_errors: 'list[str]', max_nesting_depth: 'int' = 0) -> None` - class. Variables and syntax diagnostics for one template.
|
|
- `TemplateError` - class. Raised when a template cannot be parsed or rendered.
|
|
- `TemplateRenderResult(markdown: 'str', variables: 'list[str]', missing_variables: 'list[str]', strict: 'bool' = True) -> None` - class. Rendered Markdown plus trace information.
|
|
- `analyze_template(template_text: 'str') -> 'TemplateAnalysis'` - function. Analyze variable usage and syntax in a template.
|
|
- `render_template(template_text: 'str', data: 'dict[str, Any]', *, strict: 'bool' = True) -> 'TemplateRenderResult'` - function. Render ``{{variable.path}}`` placeholders with data.
|
|
|
|
## `markitect_tool.workflow.engine`
|
|
|
|
- `WorkflowError` - class. Raised when a workflow definition cannot be loaded or executed.
|
|
- `WorkflowOutputRecord(id: 'str', path: 'str | None', content: 'str', written: 'bool' = False, artifact: 'str | None' = None) -> None` - class. One output considered or written by a workflow run.
|
|
- `WorkflowPlan(metadata: 'dict[str, Any]' = <factory>, intent: 'dict[str, Any]' = <factory>, inputs: 'dict[str, dict[str, Any]]' = <factory>, steps: 'list[dict[str, Any]]' = <factory>, outputs: 'dict[str, dict[str, Any]]' = <factory>, dependencies: 'list[Any]' = <factory>, conditions: 'dict[str, Any]' = <factory>, artifacts: 'dict[str, Any]' = <factory>, permissions: 'dict[str, Any]' = <factory>, resources: 'dict[str, Any]' = <factory>, timeouts: 'dict[str, Any]' = <factory>, retry_policies: 'dict[str, Any]' = <factory>, escalation_rules: 'dict[str, Any]' = <factory>, observability: 'dict[str, Any]' = <factory>, responsibilities: 'dict[str, Any]' = <factory>, extensions: 'dict[str, Any]' = <factory>, source_path: 'str | None' = None) -> None` - class. Loaded declarative workflow definition.
|
|
- `WorkflowRunResult(workflow_id: 'str', plan_path: 'str | None', dry_run: 'bool', sources: 'dict[str, Any]' = <factory>, steps: 'dict[str, Any]' = <factory>, outputs: 'list[WorkflowOutputRecord]' = <factory>, diagnostics: 'list[Diagnostic]' = <factory>, provenance: 'list[ProcessingProvenance]' = <factory>, trace: 'list[ProcessingTrace]' = <factory>) -> None` - class. Result envelope for workflow inspect/plan/run operations.
|
|
- `WorkflowRunner(plan: 'WorkflowPlan', *, base_dir: 'str | Path | None' = None, output_dir: 'str | Path | None' = None, assisted_hook: 'GenerationHook | None' = None) -> 'None'` - class. Execute deterministic Markitect workflows.
|
|
- `load_workflow_file(path: 'str | Path') -> 'WorkflowPlan'` - function. Load a YAML or Markdown-fenced workflow definition.
|
|
- `resolve_workflow_bindings(value: 'Any', context: 'dict[str, Any]') -> 'Any'` - function. Resolve `${...}` expressions recursively.
|
|
|
|
## `typing`
|
|
|
|
- `ExtensionRunner(*args, **kwargs)` - object.
|