chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/guide/en/api/AnalysisRunner.md

@@ -0,0 +1,191 @@
+# AnalysisRunner
+
+Import: `from chronaxis import AnalysisRunner`
+
+<a id="api-AnalysisRunner"></a>
+## `AnalysisRunner`
+
+Configures execution of one analysis. backend can override the plan; run creates independent resources and returns an AnalysisResult that must be closed. A runner can normally be reused while each result is managed separately.
+
+```python
+AnalysisRunner(backend=None)
+```
+
+
+
+<a id="api-AnalysisRunner-__init__"></a>
+### `AnalysisRunner.__init__`
+
+Selects an optional plan-backend override without reading source or configuration files.
+
+```python
+AnalysisRunner.__init__(backend=None)
+```
+
+#### Parameters
+
+| Name | Type | Required | Default | Purpose, choices, and effect |
+|---|---|---|---|---|
+|`backend`|str &#124; None|No|None|Positional or keyword. "reference" selects independent reference calculations; "numpy" selects NumPy array calculations. None uses the plan setting.|
+
+#### Returns
+
+None; initializes the instance.
+
+#### Raises
+
+TypeError for a non-string override; ValueError for an unknown backend.
+
+Exact diagnostics reported directly by this function (Chinese text is retained):
+
+- `TypeError`: `AnalysisRunner backend需要reference、numpy或None。` — backend must be reference, numpy, or None.
+- `ValueError`: `AnalysisRunner仅支持reference与numpy后端。` — only reference and numpy are supported.
+
+
+<a id="api-AnalysisRunner-backend"></a>
+### `AnalysisRunner.backend`
+
+Reads the constructor override, not the effective backend of a plan that has not yet run.
+
+```python
+AnalysisRunner.backend
+```
+
+Decorators: `property`.
+
+Read this as a property, without calling parentheses.
+
+
+#### Parameter notes
+
+None.
+
+#### Returns
+
+None/reference/numpy.
+
+#### Raises
+
+None.
+
+
+<a id="api-AnalysisRunner-validate"></a>
+### `AnalysisRunner.validate`
+
+Reports declaration validity and available execution paths without reading analysis data.
+
+```python
+AnalysisRunner.validate(plan)
+```
+
+#### Parameters
+
+| Name | Type | Required | Default | Purpose, choices, and effect |
+|---|---|---|---|---|
+|`plan`|AnalysisPlan|Yes|None|Positional or keyword. An AnalysisPlan built with load_analysis_plan("analysis.yaml") or AnalysisPlan.from_dict(config). A filename string is not accepted here.|
+
+#### Returns
+
+The shared ValidationReport, retaining warnings about actual fields/ranges that have not been verified.
+
+#### Raises
+
+TypeError if plan is not AnalysisPlan or its execution model is invalid. Ordinary static problems appear in ValidationReport.errors; execution_ready reports execution capability. Inputs are not read, so an empty errors list does not verify real logs.
+
+#### Side effects
+
+No source I/O or directory creation.
+
+
+<a id="api-AnalysisRunner-explain"></a>
+### `AnalysisRunner.explain`
+
+Lists dependencies, per-node backends, history requirements, and declared budgets without starting analysis.
+
+```python
+AnalysisRunner.explain(plan)
+```
+
+#### Parameters
+
+| Name | Type | Required | Default | Purpose, choices, and effect |
+|---|---|---|---|---|
+|`plan`|AnalysisPlan|Yes|None|Positional or keyword. An AnalysisPlan built with load_analysis_plan("analysis.yaml") or AnalysisPlan.from_dict(config). A filename string is not accepted here.|
+
+#### Returns
+
+ExplainReport; plan_identity retains the original declaration identity.
+
+#### Raises
+
+TypeError for an invalid plan or execution type. Manually corrupted typed references can cause AttributeError/KeyError; rebuild a valid plan through from_dict/load_analysis_plan. This method does not open CSV/DBC or measure runtime/memory.
+
+#### Side effects
+
+Does not read CSV/DBC or measure actual resource use.
+
+
+<a id="api-AnalysisRunner-run"></a>
+### `AnalysisRunner.run`
+
+Validates and performs one analysis, closing all inputs before returning an independent AnalysisResult.
+
+```python
+AnalysisRunner.run(plan, work_dir=None)
+```
+
+#### Parameters
+
+| Name | Type | Required | Default | Purpose, choices, and effect |
+|---|---|---|---|---|
+|`plan`|AnalysisPlan|Yes|None|Positional or keyword. An AnalysisPlan built with load_analysis_plan("analysis.yaml") or AnalysisPlan.from_dict(config). A filename string is not accepted here.|
+|`work_dir`|str &#124; Path &#124; None|No|None|Positional or keyword. Exclusive intermediate-work directory for this run. An explicit path must not exist; old directories are not overwritten. None creates a unique directory automatically.|
+
+#### Returns
+
+AnalysisResult in analysis_complete state. The caller closes it explicitly or with a context manager; write publishes separately.
+
+#### Raises
+
+TypeError for an invalid plan; validation/runtime failures raise AnalysisError retaining their cause and diagnostics. KeyboardInterrupt/SystemExit propagate unchanged. If cleanup remains incomplete, retry through runner_cleanup_owner.close.
+
+#### Side effects
+
+Creates staging for this run and scans sources once; any required subsequent history reads use the new staging. Publication is separate, and the returned result owns its cleanup lifecycle.
+
+#### Example
+
+```python
+"""Run a YAML plan and stream results; optionally publish to a new directory."""
+import argparse
+from pathlib import Path
+
+from chronaxis import AnalysisRunner, load_analysis_plan, validate_analysis_plan
+
+
+def main():
+    """Validate, run, and close cursors/results. Return None; preserve error chains."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('plan', nargs='?', type=Path, default=Path(__file__).parent / 'analysis.yaml')
+    parser.add_argument('--output', type=Path, help='New output directory; omit to print results only')
+    args = parser.parse_args()
+    plan = load_analysis_plan(args.plan)
+    report = validate_analysis_plan(plan)
+    if not report.valid or not report.execution_ready:
+        raise RuntimeError(report)
+    with AnalysisRunner().run(plan) as result:
+        rows = result.iter_calculations()
+        try:
+            for row in rows:
+                print(row.calculation_id, row.value, row.unit, row.status, row.reason)
+        finally:
+            rows.close()
+        if args.output is not None:
+            manifest = result.write(args.output)
+            print(manifest)
+
+
+if __name__ == '__main__':
+    main()
+
+```

chronaxis/guide/en/api/BatchJob.md

@@ -0,0 +1,17 @@
+# BatchJob
+
+Import: `from chronaxis import BatchJob`
+
+<a id="api-BatchJob"></a>
+## `BatchJob`
+
+Declare one independent analysis. Continuous files from the same session belong in one plan within this job.
+
+```python
+BatchJob(job_id: str, plan: chronaxis.planning.plan.AnalysisPlan | pathlib.Path) -> None
+```
+
+| Field | Type | Required / default | Meaning |
+|---|---|---|---|
+| `job_id` | str | Required | Unique job name within the batch, such as `test_a`, used for output directories and report lookup. Names differing only in case are not allowed. |
+| `plan` | AnalysisPlan &#124; Path | Required | Plan object or pathlib.Path, such as `Path("analysis.yaml")`. A bare string is not accepted by the direct constructor. Path-based plans load when the job actually starts. |

chronaxis/guide/en/api/BatchJobResult.md

@@ -0,0 +1,43 @@
+# BatchJobResult
+
+Import: `from chronaxis import BatchJobResult`
+
+<a id="api-BatchJobResult"></a>
+## `BatchJobResult`
+
+Store a job's final state. If cleanup fails after publication, status remains `failed` and the published path is retained.
+
+```python
+BatchJobResult(job_id: str, status: str, plan_path: str | None = None, plan_identity: str | None = None, dataset_id: str | None = None, entity_id: str | None = None, session_id: str | None = None, input_identity: str | None = None, run_id: str | None = None, output_dir: pathlib.Path | None = None, error_type: str | None = None, error_message: str | None = None, error_chain: tuple[str, ...] = (), elapsed_seconds: float = 0.0, memory_budget_bytes: int | None = None, worker_pid: int | None = None, recovery: chronaxis.batch.models.CleanupHandle | None = None) -> None
+```
+
+| Field | Type | Required / default | Meaning |
+|---|---|---|---|
+| `job_id` | str | Required | Original job identity. |
+| `status` | str | Required | `completed`: analysis, publication, and cleanup all succeeded. `failed`: any stage failed; inspect diagnostics. `cancelled`: cancellation or fail_fast prevented further execution. Failure and cancellation are distinct. |
+| `plan_path` | str &#124; None | Optional; None | Absolute original plan-file path. Normally None when an AnalysisPlan was supplied directly. |
+| `plan_identity` | str &#124; None | Optional; None | Obtained plan's declaration identity, not an input-content hash. None when the file plan is not yet loaded or failed to load. |
+| `dataset_id` | str &#124; None | Optional; None | Obtained plan's `dataset.name`; None if not loaded or loading failed. The result property remains named `dataset_id`. |
+| `entity_id` | str &#124; None | Optional; None | Optional `dataset.entity`, falling back to `dataset.name`; None if no plan was obtained. |
+| `session_id` | str &#124; None | Optional; None | Optional `dataset.session`, falling back to `dataset.name`; None if no plan was obtained. |
+| `input_identity` | str &#124; None | Optional; None | Input-summary identity returned by AnalysisRunner. None if no result was returned or no summary was requested; successful runs may also have None. |
+| `run_id` | str &#124; None | Optional; None | Run ID when AnalysisRunner returned a result. None if failure/cancellation occurred before that. |
+| `output_dir` | Path &#124; None | Optional; None | Formal directory after successful publication. Retained if subsequent cleanup fails, while status is failed. |
+| `error_type` | str &#124; None | Optional; None | Exception class or `not_started` cancellation marker. None on completion; read with status and error_chain. |
+| `error_message` | str &#124; None | Optional; None | Specific failure/cancellation explanation; None on completion. Causes and cleanup notes are in error_chain. |
+| `error_chain` | tuple[str, ...] | Optional; () | Cause chain and cleanup notes, retaining error origin. |
+| `elapsed_seconds` | float | Optional; 0.0 | Job wall-clock seconds, including publication and cleanup, not CPU time. |
+| `memory_budget_bytes` | int &#124; None | Optional; None | Obtained plan's new-analysis-layer budget in bytes. None when no plan was loaded, not zero bytes. |
+| `worker_pid` | int &#124; None | Optional; None | PID of the analysis worker that actually executed the job. None for unstarted jobs. Jobs reusing a process may share a PID. |
+| `recovery` | CleanupHandle &#124; None | Optional; None | Handle retained after failed cleanup; call close() to retry. None after normal cleanup. Excluded from JSON. Type link is a Chinese implementation reference. |
+
+<a id="api-BatchJobResult-to_dict"></a>
+### `BatchJobResult.to_dict`
+
+Convert job status, output directory, and errors to a report dictionary.
+
+```python
+BatchJobResult.to_dict() -> dict
+```
+
+No explicit parameters. Returns a JSON-compatible dict. No documented exceptions; resource objects are not serialized.

chronaxis/guide/en/api/BatchPlan.md

@@ -0,0 +1,37 @@
+# BatchPlan
+
+Import: `from chronaxis import BatchPlan`
+
+<a id="api-BatchPlan"></a>
+## `BatchPlan`
+
+Store batch configuration for independent plans. Do not split one continuous session into separate time jobs.
+
+```python
+BatchPlan(jobs: tuple[chronaxis.batch.models.BatchJob, ...], process_count: int = 1, fail_fast: bool = False, backend: str | None = None) -> None
+```
+
+| Field | Type | Required / default | Meaning |
+|---|---|---|---|
+| `jobs` | tuple[BatchJob, ...] | Required | Job tuple, such as `(BatchJob("a", Path("a.yaml")),)`, or loaded from YAML. Its order determines final report order. |
+| `process_count` | int | Optional; 1 | Positive maximum analysis-worker count. Fewer jobs use fewer workers; an empty batch starts none. Excludes the scheduler and CAN reader subprocesses. |
+| `fail_fast` | bool | Optional; False | False continues other independent jobs after failure. True stops new dispatch; started jobs finish through the batch executor's cancellation cleanup. |
+| `backend` | str &#124; None | Optional; None | `reference` uses independent reference calculations; `numpy` uses NumPy arrays. None preserves plan settings. |
+
+<a id="api-BatchPlan-from_dict"></a>
+### `BatchPlan.from_dict`
+
+Validate batch configuration. Jobs retain paths; templates are read and expanded into file sets.
+
+```python
+BatchPlan.from_dict(config, *, base_dir=None)
+```
+
+Class method.
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `config` | dict[str, object] | Required | Positional or keyword. `batch_version=1`; choose either `jobs` or `template` plus `inputs`. Each jobs entry requires plan; omitted name becomes `job_N` by position. Multiple-source templates need `source` to identify the target. Optional process_count, fail_fast, backend. See batch tasks. |
+| `base_dir` | str &#124; Path &#124; None | Optional; None | Keyword-only directory for resolving relative paths. None means the current working directory. |
+
+Returns a frozen BatchPlan. Raises `PlanValidationError` identifying invalid fields, duplicate names, missing template inputs, or source ambiguity. Jobs may be empty. Jobs retain plan paths; template mode reads the template, expands inputs, and reads DBC metadata if needed, but does not scan business-message records.

chronaxis/guide/en/api/BatchReport.md

@@ -0,0 +1,52 @@
+# BatchReport
+
+Import: `from chronaxis import BatchReport`
+
+<a id="api-BatchReport"></a>
+## `BatchReport`
+
+Summarize results in original job order. Each job's numerical tables remain in its own directory; this report does not combine values across different analysis definitions.
+
+```python
+BatchReport(output_dir: pathlib.Path, jobs: tuple[chronaxis.batch.models.BatchJobResult, ...], process_count: int, fail_fast: bool, cancel_requested: bool, device_label: str, worker_process_count: int = 0, infrastructure_error: str | None = None) -> None
+```
+
+| Field | Type | Required / default | Meaning |
+|---|---|---|---|
+| `output_dir` | Path | Required | New batch directory; existing targets are not overwritten. |
+| `jobs` | tuple[BatchJobResult, ...] | Required | Final results in declaration order regardless of worker completion order. |
+| `process_count` | int | Required | Configured positive maximum analysis-worker count. Scheduling defaults to 1; direct construction here requires a value. Excludes scheduler and CAN reader subprocesses. Fewer/zero jobs need fewer/zero workers. |
+| `fail_fast` | bool | Required | Whether dispatch stops after observing a failure. |
+| `cancel_requested` | bool | Required | Whether user cancellation or KeyboardInterrupt was observed. |
+| `device_label` | str | Required | Nonempty batch-report source-device label. Only run_batch/BatchRunner.run default this to pending. Does not override child metadata.device_label. |
+| `worker_process_count` | int | Optional; 0 | Actual number of analysis workers started, possibly less than process_count. Zero for an empty or pre-cancelled batch. Excludes CAN reader subprocesses. |
+| `infrastructure_error` | str &#124; None | Optional; None | Scheduler/report-infrastructure error. None means no such error was recorded, not that all jobs succeeded. Inspect each job's status and diagnostics. |
+
+<a id="api-BatchReport-status"></a>
+### `BatchReport.status`
+
+```python
+BatchReport.status: str
+```
+
+Property: read without parentheses. No parameters. Returns `failed`, `cancelled`, or `completed`, with failure taking precedence. No documented exceptions.
+
+<a id="api-BatchReport-to_dict"></a>
+### `BatchReport.to_dict`
+
+```python
+BatchReport.to_dict() -> dict
+```
+
+No explicit parameters. Returns a JSON-compatible dict containing identities and counts. Does not aggregate calculation values. No documented exceptions.
+
+<a id="api-BatchReport-close"></a>
+### `BatchReport.close`
+
+Retry all unfinished cleanup.
+
+```python
+BatchReport.close() -> None
+```
+
+No explicit parameters. Returns None, not additional calculation values. Raises the first close error after still attempting the other cleanup items.

chronaxis/guide/en/api/BatchRunner.md

@@ -0,0 +1,51 @@
+# BatchRunner
+
+Import: `from chronaxis import BatchRunner`
+
+<a id="api-BatchRunner"></a>
+## `BatchRunner`
+
+Execute independent jobs with a bounded pool of spawn workers. Continuous files within each job retain their original order.
+
+```python
+BatchRunner(process_count=1, *, fail_fast=False, backend=None)
+```
+
+<a id="api-BatchRunner-__init__"></a>
+### `BatchRunner.__init__`
+
+Configure scheduling without starting workers or reading business data.
+
+```python
+BatchRunner.__init__(process_count=1, *, fail_fast=False, backend=None)
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `process_count` | int | Optional; 1 | Positional or keyword. Positive maximum analysis-worker count. Fewer jobs need fewer workers; empty batches start none. Excludes scheduler and CAN reader subprocesses. |
+| `fail_fast` | bool | Optional; False | Keyword-only. False continues later jobs after failure; True stops new dispatch after observing failure and waits for started jobs to finish cleanup. |
+| `backend` | str &#124; None | Optional; None | Keyword-only. `reference` or `numpy`; None uses each plan's setting. |
+
+The initializer returns None; calling BatchRunner(...) creates the instance. Invalid types, ranges, or backends are rejected. Specific errors include `ValueError` (“process_count需要正原生int。”: requires a positive native int) and `TypeError` (“fail_fast需要bool。”: requires bool).
+
+<a id="api-BatchRunner-run"></a>
+### `BatchRunner.run`
+
+Run independent jobs and return a report in declaration order.
+
+```python
+BatchRunner.run(jobs, output_dir, *, cancel_event=None, device_label='pending') -> BatchReport
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `jobs` | tuple | Required | Positional or keyword. BatchJob tuple, for example `load_batch_plan("batch.yaml").jobs`; each includes an independent identity and plan. |
+| `output_dir` | str &#124; Path | Required | Positional or keyword. New batch directory with a subdirectory per job ID. Existing targets are rejected. |
+| `cancel_event` | threading.Event &#124; None | Optional; None | Keyword-only. Another thread can call set() to stop new dispatch; running jobs continue to finish cleanup. None disables this cancellation signal. |
+| `device_label` | str | Optional; `'pending'` | Keyword-only. Verified source-device label, such as home/work, or pending when unknown. It does not affect calculations or infer the device from paths. |
+
+Returns BatchReport; its close() retries failed cleanup in child processes. Declaration/path errors are rejected before creating workers. Worker-scheduler or other infrastructure errors propagate after cleanup.
+
+Specific errors: `TypeError` if jobs is not a BatchJob tuple (“批量任务需要BatchJob tuple。”); `ValueError` for duplicate or case-colliding IDs (“批量job_id不能重复，大小写冲突也拒绝。”); `TypeError` for a non-threading.Event cancellation signal (“cancel_event需要threading.Event。”); `ValueError` for an empty/nontext device label (“device_label需要非空文本。”).
+
+Side effects: starts at most process_count workers and publishes each job independently. Cancellation prevents dispatch only for jobs not yet dispatched.

chronaxis/guide/en/api/OutputManifest.md

@@ -0,0 +1,23 @@
+# OutputManifest
+
+Import: `from chronaxis import OutputManifest`
+
+<a id="api-OutputManifest"></a>
+## `OutputManifest`
+
+Stores the successfully published directory, manifest, and row counts for the fixed set of supported tables. Legacy output appears only when enabled.
+
+```python
+OutputManifest(run_id: str, output_dir: pathlib.Path, manifest_path: pathlib.Path, output_files: tuple[pathlib.Path, ...], row_counts: tuple[tuple[str, int], ...], status: str = 'completed') -> None
+```
+
+### Properties and data fields
+
+| Name | Type | Required | Default | Purpose, choices, and effect |
+|---|---|---|---|---|
+|`run_id`|str|Yes|None|Unique run identity, associated with the published manifest and resource records.|
+|`output_dir`|Path|Yes|None|Absolute Path of the successfully published result directory.|
+|`manifest_path`|Path|Yes|None|Absolute Path of the published run_manifest.json.|
+|`output_files`|tuple[Path, ...]|Yes|None|Tuple of file paths actually published in this operation.|
+|`row_counts`|tuple[tuple[str, int], ...]|Yes|None|Actual row counts for each supported result table.|
+|`status`|str|No|'completed'|Publication status; successful publication is completed.|

chronaxis/guide/en/api/PlanFragment.md

@@ -0,0 +1,33 @@
+# PlanFragment
+
+Import: `from chronaxis import PlanFragment`
+
+<a id="api-PlanFragment"></a>
+## `PlanFragment`
+
+A preset-generated set of derived values, rules, windows, calculations, and pairings. Merge it into a full plan for execution. It contains no real samples and reads no files itself. Generated IDs must still be unique against user-defined IDs.
+
+```python
+PlanFragment(derived: tuple[chronaxis.core.expression.DerivedDefinition, ...] = (), rules: tuple[chronaxis.planning.preset_models.PresetRule, ...] = (), windows: tuple[chronaxis.core.windows.WindowSpec, ...] = (), calculations: tuple[chronaxis.planning.preset_models.PresetCalculation, ...] = (), sequences: tuple[chronaxis.planning.sequences.SequencePlan, ...] = ()) -> None
+```
+
+The linked lower-level types are Chinese implementation references.
+
+| Field | Type | Required / default | Meaning |
+|---|---|---|---|
+| `derived` | tuple[DerivedDefinition, ...] | Optional; () | Generated derived definitions; empty means none. |
+| `rules` | tuple[PresetRule, ...] | Optional; () | Generated detection rules; empty means none. |
+| `windows` | tuple[WindowSpec, ...] | Optional; () | Generated event windows; empty means none. |
+| `calculations` | tuple[PresetCalculation, ...] | Optional; () | Generated calculation definitions; empty means none. |
+| `sequences` | tuple[SequencePlan, ...] | Optional; () | Generated pairings. Nonempty values become a sequences list in to_dict(); no pairings means empty. |
+
+<a id="api-PlanFragment-to_dict"></a>
+### `PlanFragment.to_dict`
+
+Serialize typed definitions to copies using the current configuration format; omit an empty sequences key.
+
+```python
+PlanFragment.to_dict()
+```
+
+No explicit parameters; reads the immutable generated declarations. Returns a dict that can be merged into input for AnalysisPlan.from_dict. It contains no invented sources or execution results. No proactively raised exceptions are documented; build_preset constructs these instances.

chronaxis/guide/en/api/PlanValidationError.md

@@ -0,0 +1,58 @@
+# PlanValidationError
+
+Import: `from chronaxis import PlanValidationError`
+
+<a id="api-PlanValidationError"></a>
+## `PlanValidationError`
+
+Store a configuration field path, reason, machine-readable code, and optional source location and correction hint. It does not suppress execution or data-read failures. `code` distinguishes invalid configuration from capabilities not yet connected to an executable path.
+
+```python
+PlanValidationError(path: str, message: str, code: str = 'invalid_config', *, hint=None, source=None, location=None, object_name=None, value=None)
+```
+
+Base class: `ValueError`.
+
+<a id="api-PlanValidationError-__init__"></a>
+### `PlanValidationError.__init__`
+
+Construct a field-specific error, preserving the original exception chain for loader diagnostics.
+
+```python
+PlanValidationError.__init__(path: str, message: str, code: str='invalid_config', *, hint=None, source=None, location=None, object_name=None, value=None)
+```
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `path` | str | Required | Positional or keyword. Actual failing field path, such as `$.signals[0].unit`. |
+| `message` | str | Required | Positional or keyword. Human-readable violated requirement, such as a positive integer being required. Do not include complete private input data. |
+| `code` | str | Optional; `'invalid_config'` | Positional or keyword. Machine-readable category. Classify errors by code rather than matching Chinese message text. |
+| `hint` | str or None | Optional; None | Keyword-only correction hint, such as valid options/names. Does not modify configuration. |
+| `source` | str or None | Optional; None | Keyword-only source file or display name, separate from field path. None when unknown. |
+| `location` | ConfigurationLocation or None | Optional; None | Keyword-only proven original line/column. If unavailable, report only file and field rather than guessing. |
+| `object_name` | str or None | Optional; None | Keyword-only source, signal, or node name for locating the error, not inferring names. |
+| `value` | str or None | Optional; None | Keyword-only shortened value description. Large containers show only type/size, not the entire configuration. |
+
+Returns None; exception text contains path and reason. No documented exceptions: validators construct the arguments internally.
+
+<a id="api-PlanValidationError-refresh_text"></a>
+### `PlanValidationError.refresh_text`
+
+Rebuild the human-readable message after attaching location information.
+
+```python
+PlanValidationError.refresh_text()
+```
+
+No explicit parameters. Returns None. No documented exceptions.
+
+<a id="api-PlanValidationError-to_dict"></a>
+### `PlanValidationError.to_dict`
+
+Return stable machine-readable diagnostics as a native dict.
+
+```python
+PlanValidationError.to_dict()
+```
+
+No explicit parameters. No documented exceptions.

chronaxis/guide/en/api/PresetSpec.md

@@ -0,0 +1,51 @@
+# PresetSpec
+
+Import: `from chronaxis import PresetSpec`
+
+<a id="api-PresetSpec"></a>
+## `PresetSpec`
+
+Freeze a preset ID, type/version, role aliases, and parameters as an independent JSON snapshot. The ID is a simple identifier. Role values reference simple aliases in the current plan, not domain attribute paths. Parameters do not retain caller-owned mutable objects. build_preset validates the actual type-specific parameters.
+
+```python
+PresetSpec(id: str, preset_type: str, version: str, role_bindings: collections.abc.Mapping, parameters: collections.abc.Mapping) -> None
+```
+
+| Field | Type | Required / default | Meaning |
+|---|---|---|---|
+| `id` | str | Required | Unique preset instance name, such as hot; generated names use this prefix and must not collide with existing nodes. |
+| `preset_type` | str | Required | charge_session, fault_context, command_response, or threshold_excursion. See presets for their purposes and roles. |
+| `version` | str | Required | Current template version is string `"1"`, not number 1 or the top-level config_version. |
+| `role_bindings` | Mapping | Required | Map permitted roles to defined signals, for example `{"signal": "temperature"}`. Omitted roles require the documented semantic lookup declarations. |
+| `parameters` | Mapping | Required | Type-specific parameters, such as threshold unit/enter_threshold/exit_threshold. Obtain values from business requirements and device units; do not mix different preset types' fields. |
+
+<a id="api-PresetSpec-from_dict"></a>
+### `PresetSpec.from_dict`
+
+Build an immutable public declaration from the current configuration format.
+
+```python
+PresetSpec.from_dict(value)
+```
+
+Class method.
+
+| Parameter | Type | Required / default | Meaning |
+|---|---|---|---|
+| `value` | dict[str, object] | Required | Positional or keyword. Requires name, preset_type, and parameters. Omitted version is string `"1"`; omitted role_bindings is an empty mapping. See role requirements. |
+
+Returns PresetSpec. Raises `PlanValidationError` for unknown keys, missing fields, or construction-protocol errors.
+
+```python
+from chronaxis import PresetSpec
+
+# Full role and threshold semantics are checked when the plan is assembled.
+spec = PresetSpec.from_dict({
+    "name": "heat_alarm",
+    "preset_type": "threshold_excursion",
+    "version": "1",
+    "role_bindings": {"signal": "temperature"},
+    "parameters": {"unit": "degC", "enter_threshold": 80, "exit_threshold": 75},
+})
+print(spec.id, spec.preset_type)
+```

chronaxis/guide/en/api/ResultClosedError.md

@@ -0,0 +1,14 @@
+# ResultClosedError
+
+Import: `from chronaxis import ResultClosedError`
+
+<a id="api-ResultClosedError"></a>
+## `ResultClosedError`
+
+Indicates a closed result: new iterators cannot be created and the result cannot be read or published.
+
+```python
+class ResultClosedError(AnalysisError)
+```
+
+Base class: AnalysisError. No additional fields are declared by this class.