From bbd9863d23dff18e81312882fbf0f09ecb693727 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Mon, 14 Sep 2026 00:18:17 +0530 Subject: [PATCH] refresh collected sites/mcp for docstring changes in dagpipe, mail-intake, openapi-first --- dagpipe/lib/dagpipe/engine/index.html | 100 ++++++++++- dagpipe/lib/dagpipe/graph/index.html | 8 +- dagpipe/lib/dagpipe/index.html | 144 +++++++++++++--- dagpipe/lib/dagpipe/node/index.html | 17 +- dagpipe/lib/dagpipe/state/index.html | 17 +- dagpipe/lib/dagpipe/yaml_loader/index.html | 2 +- dagpipe/lib/engine/index.html | 115 ++++++++++++- dagpipe/lib/graph/index.html | 8 +- dagpipe/lib/index.html | 159 +++++++++++++++--- dagpipe/lib/node/index.html | 17 +- dagpipe/lib/search/search_index.json | 2 +- dagpipe/lib/state/index.html | 17 +- dagpipe/lib/yaml_loader/index.html | 2 +- mail-intake/lib/credentials/index.html | 90 +++++++++- mail-intake/lib/credentials/redis/index.html | 90 +++++++++- .../lib/mail_intake/credentials/index.html | 90 +++++++++- .../mail_intake/credentials/redis/index.html | 90 +++++++++- mail-intake/lib/search/search_index.json | 2 +- mcp/dagpipe/modules/dagpipe.engine.json | 34 ++-- mcp/dagpipe/modules/dagpipe.graph.json | 12 +- mcp/dagpipe/modules/dagpipe.json | 110 ++++++------ mcp/dagpipe/modules/dagpipe.node.json | 8 +- mcp/dagpipe/modules/dagpipe.state.json | 6 +- mcp/dagpipe/modules/dagpipe.yaml_loader.json | 24 +-- mcp/dagpipe/nav.json | 12 +- .../modules/mail_intake.credentials.json | 22 +-- .../mail_intake.credentials.redis.json | 22 +-- mcp/mail-intake/modules/mail_intake.json | 22 +-- .../modules/openapi_first.app.json | 11 +- .../modules/openapi_first.binder.json | 25 ++- mcp/openapi-first/modules/openapi_first.json | 36 ++-- openapi-first/lib/app/index.html | 2 +- openapi-first/lib/binder/index.html | 8 +- .../lib/openapi_first/app/index.html | 2 +- .../lib/openapi_first/binder/index.html | 8 +- openapi-first/lib/search/search_index.json | 2 +- 36 files changed, 1037 insertions(+), 299 deletions(-) diff --git a/dagpipe/lib/dagpipe/engine/index.html b/dagpipe/lib/dagpipe/engine/index.html index d989bb2..533e953 100644 --- a/dagpipe/lib/dagpipe/engine/index.html +++ b/dagpipe/lib/dagpipe/engine/index.html @@ -812,6 +812,21 @@ + + @@ -1286,7 +1301,7 @@ are both supported.

resume_from - int + int | None
@@ -1301,7 +1316,7 @@ Steps are 0-indexed.

on_step - StepHook + StepHook | None
@@ -1408,7 +1423,7 @@ orchestrator. Use run_steps_async for async nodes.

resume_from - int + int | None
@@ -1422,7 +1437,7 @@ orchestrator. Use run_steps_async for async nodes.

on_step - AsyncStepHook + AsyncStepHook | None
@@ -1594,7 +1609,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic. states - Tuple[State, ...] + tuple[State, ...]
@@ -1616,6 +1631,79 @@ callers can surface counts/lines/errors without coupling the engine to pydantic. +

Initialise StepResult.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
index + int + +
+

Ordinal index of the step.

+
+ 		+ required +
node_id + str + +
+

Identifier of the node associated with this step.

+
+ 		+ required +
states + tuple[State, ...] + +
+

States produced by running this step.

+
+ 		+ required +
completed + bool + +
+

Whether this step succeeded (vs. paused/interrupted).

+
+ 		+ required +
+ @@ -1627,7 +1715,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic. - +
Functions
diff --git a/dagpipe/lib/dagpipe/graph/index.html b/dagpipe/lib/dagpipe/graph/index.html index 2d48cef..a5f0c80 100644 --- a/dagpipe/lib/dagpipe/graph/index.html +++ b/dagpipe/lib/dagpipe/graph/index.html @@ -1176,7 +1176,7 @@
-

Tuple[Node, ...]: +

tuple[Node, ...]: Outgoing neighbors.

@@ -1219,7 +1219,7 @@ Outgoing neighbors.

-

Tuple[Node, ...]: +

tuple[Node, ...]: All registered nodes.

@@ -1291,7 +1291,7 @@ All registered nodes.

-

Tuple[Node, ...]: +

tuple[Node, ...]: Incoming neighbors.

@@ -1334,7 +1334,7 @@ Incoming neighbors.

-

Tuple[Node, ...]: +

tuple[Node, ...]: Entry point nodes.

diff --git a/dagpipe/lib/dagpipe/index.html b/dagpipe/lib/dagpipe/index.html index 8e4ee35..852f554 100644 --- a/dagpipe/lib/dagpipe/index.html +++ b/dagpipe/lib/dagpipe/index.html @@ -1538,6 +1538,21 @@ + + @@ -1908,7 +1923,7 @@ an async engine is required.

payload_update - Mapping[str, Any] + Any
@@ -1936,7 +1951,7 @@ an async engine is required.

metadata_update - Mapping[str, Any] + Any
@@ -2696,7 +2711,7 @@ are both supported.

resume_from - int + int | None
@@ -2711,7 +2726,7 @@ Steps are 0-indexed.

on_step - StepHook + StepHook | None
@@ -2818,7 +2833,7 @@ orchestrator. Use run_steps_async for async nodes.

resume_from - int + int | None
@@ -2832,7 +2847,7 @@ orchestrator. Use run_steps_async for async nodes.

on_step - AsyncStepHook + AsyncStepHook | None
@@ -3185,7 +3200,7 @@ orchestrator. Use run_steps_async for async nodes.

-

Tuple[Node, ...]: +

tuple[Node, ...]: Outgoing neighbors.

@@ -3228,7 +3243,7 @@ Outgoing neighbors.

-

Tuple[Node, ...]: +

tuple[Node, ...]: All registered nodes.

@@ -3300,7 +3315,7 @@ All registered nodes.

-

Tuple[Node, ...]: +

tuple[Node, ...]: Incoming neighbors.

@@ -3343,7 +3358,7 @@ Incoming neighbors.

-

Tuple[Node, ...]: +

tuple[Node, ...]: Entry point nodes.

@@ -3656,7 +3671,7 @@ so pipeline builders can inject per-run dependencies.

payload_update - Mapping[str, Any] + Any
@@ -3684,7 +3699,7 @@ so pipeline builders can inject per-run dependencies.

metadata_update - Mapping[str, Any] + Any
@@ -3877,22 +3892,23 @@ so pipeline builders can inject per-run dependencies.

-

Yields:

+

Returns:

- + - @@ -4355,23 +4371,22 @@ Read-only view of the underlying data.

Name TypeType Description
State + Iterable[State]
-

Derived execution state(s).

+

Iterable[State]: +Derived execution state(s).
-

Returns:

+

Yields:

- + - @@ -4647,7 +4662,7 @@ Iterator over top-level keys.

@@ -5588,7 +5603,7 @@ Ordered execution lineage (root first).

TypeName Type Description
+str Iterable[str]
-

Iterable[str]: -Generator yielding dot-paths.

+

Dot-path for each leaf node.
payload_override - Mapping[str, Any] + Mapping[str, Any] | None
@@ -5224,7 +5239,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
payload_update - Mapping[str, Any] + Mapping[str, Any] | None
@@ -5252,7 +5267,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
node_id - str + str | None
@@ -5266,7 +5281,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
metadata_update - Mapping[str, Any] + Mapping[str, Any] | None
@@ -5505,7 +5520,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
-

Tuple[State, ...]: +

tuple[State, ...]: Ordered execution lineage (root first).
states - Tuple[State, ...] + tuple[State, ...]
@@ -5610,6 +5625,79 @@ Ordered execution lineage (root first).
+

Initialise StepResult.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
index + int + +
+

Ordinal index of the step.

+
+ 		+ required +
node_id + str + +
+

Identifier of the node associated with this step.

+
+ 		+ required +
states + tuple[State, ...] + +
+

States produced by running this step.

+
+ 		+ required +
completed + bool + +
+

Whether this step succeeded (vs. paused/interrupted).

+
+ 		+ required +
+ @@ -5621,7 +5709,7 @@ Ordered execution lineage (root first).

- +
Functions
diff --git a/dagpipe/lib/dagpipe/node/index.html b/dagpipe/lib/dagpipe/node/index.html index c51c07f..aecbabb 100644 --- a/dagpipe/lib/dagpipe/node/index.html +++ b/dagpipe/lib/dagpipe/node/index.html @@ -1280,7 +1280,7 @@ an async engine is required.

payload_update - Mapping[str, Any] + Any
@@ -1308,7 +1308,7 @@ an async engine is required.

metadata_update - Mapping[str, Any] + Any
@@ -1953,7 +1953,7 @@ so pipeline builders can inject per-run dependencies.

payload_update - Mapping[str, Any] + Any
@@ -1981,7 +1981,7 @@ so pipeline builders can inject per-run dependencies.

metadata_update - Mapping[str, Any] + Any
@@ -2174,22 +2174,23 @@ so pipeline builders can inject per-run dependencies.

-

Yields:

+

Returns:

- + - diff --git a/dagpipe/lib/dagpipe/state/index.html b/dagpipe/lib/dagpipe/state/index.html index d0281ab..e318fc0 100644 --- a/dagpipe/lib/dagpipe/state/index.html +++ b/dagpipe/lib/dagpipe/state/index.html @@ -1334,23 +1334,22 @@ Read-only view of the underlying data.

Name TypeType Description
State + Iterable[State]
-

Derived execution state(s).

+

Iterable[State]: +Derived execution state(s).
-

Returns:

+

Yields:

- + - @@ -1950,7 +1949,7 @@ Iterator over top-level keys.

diff --git a/dagpipe/lib/dagpipe/yaml_loader/index.html b/dagpipe/lib/dagpipe/yaml_loader/index.html index 85eb374..a5f1eb8 100644 --- a/dagpipe/lib/dagpipe/yaml_loader/index.html +++ b/dagpipe/lib/dagpipe/yaml_loader/index.html @@ -943,7 +943,7 @@ and initial payloads.

TypeName Type Description
+str Iterable[str]
-

Iterable[str]: -Generator yielding dot-paths.

+

Dot-path for each leaf node.
payload_update - Mapping[str, Any] + Mapping[str, Any] | None
@@ -1978,7 +1977,7 @@ Iterator over top-level keys.

node_id - str + str | None
@@ -1992,7 +1991,7 @@ Iterator over top-level keys.

metadata_update - Mapping[str, Any] + Mapping[str, Any] | None
@@ -2231,7 +2230,7 @@ Iterator over top-level keys.
-

Tuple[State, ...]: +

tuple[State, ...]: Ordered execution lineage (root first).
payload_override - Mapping[str, Any] + Mapping[str, Any] | None
diff --git a/dagpipe/lib/engine/index.html b/dagpipe/lib/engine/index.html index 2fe9d55..ad01711 100644 --- a/dagpipe/lib/engine/index.html +++ b/dagpipe/lib/engine/index.html @@ -737,6 +737,21 @@ + + @@ -1023,6 +1038,21 @@ + + @@ -1497,7 +1527,7 @@ are both supported.

resume_from - int + int | None
@@ -1512,7 +1542,7 @@ Steps are 0-indexed.

on_step - StepHook + StepHook | None
@@ -1619,7 +1649,7 @@ orchestrator. Use run_steps_async for async nodes.

resume_from - int + int | None
@@ -1633,7 +1663,7 @@ orchestrator. Use run_steps_async for async nodes.

on_step - AsyncStepHook + AsyncStepHook | None
@@ -1805,7 +1835,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
states - Tuple[State, ...] + tuple[State, ...]
@@ -1827,6 +1857,79 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
+

Initialise StepResult.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
index + int + +
+

Ordinal index of the step.

+
+ 		+ required +
node_id + str + +
+

Identifier of the node associated with this step.

+
+ 		+ required +
states + tuple[State, ...] + +
+

States produced by running this step.

+
+ 		+ required +
completed + bool + +
+

Whether this step succeeded (vs. paused/interrupted).

+
+ 		+ required +
+ @@ -1838,7 +1941,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic. - +
Functions
diff --git a/dagpipe/lib/graph/index.html b/dagpipe/lib/graph/index.html index c77f553..b4391d7 100644 --- a/dagpipe/lib/graph/index.html +++ b/dagpipe/lib/graph/index.html @@ -1381,7 +1381,7 @@
-

Tuple[Node, ...]: +

tuple[Node, ...]: Outgoing neighbors.

@@ -1424,7 +1424,7 @@ Outgoing neighbors.

-

Tuple[Node, ...]: +

tuple[Node, ...]: All registered nodes.

@@ -1496,7 +1496,7 @@ All registered nodes.

-

Tuple[Node, ...]: +

tuple[Node, ...]: Incoming neighbors.

@@ -1539,7 +1539,7 @@ Incoming neighbors.

-

Tuple[Node, ...]: +

tuple[Node, ...]: Entry point nodes.

diff --git a/dagpipe/lib/index.html b/dagpipe/lib/index.html index 441879f..106c1ac 100644 --- a/dagpipe/lib/index.html +++ b/dagpipe/lib/index.html @@ -1153,6 +1153,21 @@ + + @@ -2497,6 +2512,21 @@ + + @@ -2867,7 +2897,7 @@ an async engine is required.

payload_update - Mapping[str, Any] + Any
@@ -2895,7 +2925,7 @@ an async engine is required.

metadata_update - Mapping[str, Any] + Any
@@ -3655,7 +3685,7 @@ are both supported.

resume_from - int + int | None
@@ -3670,7 +3700,7 @@ Steps are 0-indexed.

on_step - StepHook + StepHook | None
@@ -3777,7 +3807,7 @@ orchestrator. Use run_steps_async for async nodes.

resume_from - int + int | None
@@ -3791,7 +3821,7 @@ orchestrator. Use run_steps_async for async nodes.

on_step - AsyncStepHook + AsyncStepHook | None
@@ -4144,7 +4174,7 @@ orchestrator. Use run_steps_async for async nodes.

-

Tuple[Node, ...]: +

tuple[Node, ...]: Outgoing neighbors.

@@ -4187,7 +4217,7 @@ Outgoing neighbors.

-

Tuple[Node, ...]: +

tuple[Node, ...]: All registered nodes.

@@ -4259,7 +4289,7 @@ All registered nodes.

-

Tuple[Node, ...]: +

tuple[Node, ...]: Incoming neighbors.

@@ -4302,7 +4332,7 @@ Incoming neighbors.

-

Tuple[Node, ...]: +

tuple[Node, ...]: Entry point nodes.

@@ -4615,7 +4645,7 @@ so pipeline builders can inject per-run dependencies.

payload_update - Mapping[str, Any] + Any
@@ -4643,7 +4673,7 @@ so pipeline builders can inject per-run dependencies.

metadata_update - Mapping[str, Any] + Any
@@ -4836,22 +4866,23 @@ so pipeline builders can inject per-run dependencies.

-

Yields:

+

Returns:

- + - @@ -5314,23 +5345,22 @@ Read-only view of the underlying data.

Name TypeType Description
State + Iterable[State]
-

Derived execution state(s).

+

Iterable[State]: +Derived execution state(s).
-

Returns:

+

Yields:

- + - @@ -5606,7 +5636,7 @@ Iterator over top-level keys.

@@ -6547,7 +6577,7 @@ Ordered execution lineage (root first).

TypeName Type Description
+str Iterable[str]
-

Iterable[str]: -Generator yielding dot-paths.

+

Dot-path for each leaf node.
payload_override - Mapping[str, Any] + Mapping[str, Any] | None
@@ -6183,7 +6213,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
payload_update - Mapping[str, Any] + Mapping[str, Any] | None
@@ -6211,7 +6241,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
node_id - str + str | None
@@ -6225,7 +6255,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
metadata_update - Mapping[str, Any] + Mapping[str, Any] | None
@@ -6464,7 +6494,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
-

Tuple[State, ...]: +

tuple[State, ...]: Ordered execution lineage (root first).
states - Tuple[State, ...] + tuple[State, ...]
@@ -6569,6 +6599,79 @@ Ordered execution lineage (root first).
+

Initialise StepResult.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
index + int + +
+

Ordinal index of the step.

+
+ 		+ required +
node_id + str + +
+

Identifier of the node associated with this step.

+
+ 		+ required +
states + tuple[State, ...] + +
+

States produced by running this step.

+
+ 		+ required +
completed + bool + +
+

Whether this step succeeded (vs. paused/interrupted).

+
+ 		+ required +
+ @@ -6580,7 +6683,7 @@ Ordered execution lineage (root first).

- +
Functions
diff --git a/dagpipe/lib/node/index.html b/dagpipe/lib/node/index.html index e55d946..92a615e 100644 --- a/dagpipe/lib/node/index.html +++ b/dagpipe/lib/node/index.html @@ -1668,7 +1668,7 @@ an async engine is required.

payload_update - Mapping[str, Any] + Any
@@ -1696,7 +1696,7 @@ an async engine is required.

metadata_update - Mapping[str, Any] + Any
@@ -2341,7 +2341,7 @@ so pipeline builders can inject per-run dependencies.

payload_update - Mapping[str, Any] + Any
@@ -2369,7 +2369,7 @@ so pipeline builders can inject per-run dependencies.

metadata_update - Mapping[str, Any] + Any
@@ -2562,22 +2562,23 @@ so pipeline builders can inject per-run dependencies.

-

Yields:

+

Returns:

- + - diff --git a/dagpipe/lib/search/search_index.json b/dagpipe/lib/search/search_index.json index cfec287..7f1543c 100644 --- a/dagpipe/lib/search/search_index.json +++ b/dagpipe/lib/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"dagpipe","text":"
  • Dagpipe
"},{"location":"#dagpipe","title":"dagpipe","text":""},{"location":"#dagpipe--summary","title":"Summary","text":"

Directed acyclic graph execution framework for deterministic state propagation.

dagpipe executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable State and optionally produces derived states for downstream nodes.

"},{"location":"#dagpipe--installation","title":"Installation","text":"

Install using pip:

pip install dagpipe\n
"},{"location":"#dagpipe--quick-start","title":"Quick Start","text":"
from dagpipe import State, Payload, Schema, Graph, Engine\nfrom dagpipe.node import Node\n\nclass HelloNode(Node):\n    id = \"hello\"\n    def resolve(self, state):\n        yield self.fork(state, payload_update={\"msg\": \"hello\"})\n\n# Build and run\ngraph = Graph()\ngraph.add_root(HelloNode())\nengine = Engine(graph)\n\nclass MyState(State):\n    schema = Schema({})\n\nresults = engine.run(MyState(payload=Payload({})))\n
"},{"location":"#dagpipe--public-api","title":"Public API","text":"

This package re-exports the core pipeline components. Consumers should import from this namespace for standard usage.

"},{"location":"#dagpipe--execution-core","title":"Execution Core","text":"
  • Engine: Responsible for orchestrating node execution and state propagation.
  • Graph: Defines the execution topology and node relationships.
  • Node: Base class for defining execution logic and transformations.
"},{"location":"#dagpipe--state-data","title":"State & Data","text":"
  • State: Represents an immutable execution snapshot at a point in time.
  • Payload: Immutable hierarchical container for execution data.
  • Schema: Defines and validates the allowed structure of payloads.
  • SchemaError: Raised when data violates the declared schema.
"},{"location":"#dagpipe--declarative-pipelines","title":"Declarative Pipelines","text":"
  • Pipeline: High-level wrapper for an engine, state type, and initial payload.
  • load_pipeline: Factory function to create a pipeline from YAML.
"},{"location":"#dagpipe-classes","title":"Classes","text":""},{"location":"#dagpipe.AsyncNode","title":"AsyncNode","text":"

Bases: Node

Base class for nodes whose execution is asynchronous.

Subclasses implement resolve_async (an async generator yielding derived State objects). The engine dispatches to resolve_async when running an async traversal (see Engine.run_async).

Sync-only engines (and the base Node.run) treat an AsyncNode as a no-op consumer: calling run on an AsyncNode returns no states, signalling that an async engine is required.

"},{"location":"#dagpipe.AsyncNode-functions","title":"Functions","text":""},{"location":"#dagpipe.AsyncNode.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"#dagpipe.AsyncNode.__hash__--returns","title":"Returns","text":"

int

"},{"location":"#dagpipe.AsyncNode.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"#dagpipe.AsyncNode.__repr__--returns","title":"Returns","text":"

str

"},{"location":"#dagpipe.AsyncNode.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"#dagpipe.AsyncNode.__str__--returns","title":"Returns","text":"

str

"},{"location":"#dagpipe.AsyncNode.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"#dagpipe.AsyncNode.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateMapping[str, Any]

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateMapping[str, Any]

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"#dagpipe.AsyncNode.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"#dagpipe.AsyncNode.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"#dagpipe.AsyncNode.resolve_async","title":"resolve_async async","text":"
resolve_async(state: State) -> Iterable[State]\n

Execute node logic asynchronously.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description Iterable[State]

Iterable[State]: Derived execution state(s).

Notes

Subclasses implement this. Must not mutate the input state. Should use fork() to create child states.

"},{"location":"#dagpipe.AsyncNode.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"#dagpipe.AsyncNode.run_async","title":"run_async async","text":"
run_async(state: State) -> tuple[State, ...]\n

Execute this node asynchronously on a state, validating outputs.

"},{"location":"#dagpipe.Engine","title":"Engine","text":"
Engine(\n    nodes_or_graph: Sequence[Node] | Graph,\n    *,\n    on_step: StepHook | None = None\n)\n

Execution engine responsible for running pipeline logic.

Notes

Responsibilities:

- Accepts either a linear sequence of `Node` objects or a `Graph`\n  defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n  collects terminal states.\n- Supports synchronous (`run`) and asynchronous (`run_async`)\n  execution, dispatching per-node.\n- Supports step-wise / resumable execution and progress hooks.\n

Guarantees:

- Never mutates `State`, `Node`, or `Graph` instances.\n- `State` objects are never modified in place; each branch produces\n  independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
"},{"location":"#dagpipe.Engine-attributes","title":"Attributes","text":""},{"location":"#dagpipe.Engine.nodes","title":"nodes property","text":"
nodes: tuple[Node, ...]\n

Return nodes managed by this engine.

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.

"},{"location":"#dagpipe.Engine-functions","title":"Functions","text":""},{"location":"#dagpipe.Engine.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return the canonical string representation of the object.

Returns:

Name Type Description strstr

Representation that uniquely identifies the object and its configuration.

"},{"location":"#dagpipe.Engine.run","title":"run","text":"
run(root: State) -> list[State]\n

Execute the pipeline starting from a root State.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Raises:

Type Description TypeError

If root is not a State instance.

RuntimeError

If the engine execution mode is invalid.

Notes

Responsibilities:

- Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n
"},{"location":"#dagpipe.Engine.run_async","title":"run_async async","text":"
run_async(root: State) -> list[State]\n

Execute the pipeline starting from root, dispatching sync vs async nodes.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Notes

Each node is executed with Node.run when synchronous and AsyncNode.run_async when asynchronous. Linear and graph topologies are both supported.

"},{"location":"#dagpipe.Engine.run_steps","title":"run_steps","text":"
run_steps(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: StepHook | None = None\n) -> Iterator[StepResult]\n

Execute the pipeline step-by-step, yielding one StepResult per step.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint

Skip steps at index < resume_from (for resume-after-partial). Steps are 0-indexed.

Noneon_stepStepHook

Callback (step, status, message) invoked per step; falls back to the engine-level hook when unset.

None

Yields:

Name Type Description StepResultStepResult

One per executed node/step, carrying the produced states.

Notes

This is a synchronous, generator-based checkpoint interface compatible with the imperative resume-by-step behaviour of the legacy orchestrator. Use run_steps_async for async nodes.

"},{"location":"#dagpipe.Engine.run_steps_async","title":"run_steps_async async","text":"
run_steps_async(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: AsyncStepHook | None = None\n) -> AsyncIterator[StepResult]\n

Async variant of run_steps supporting AsyncNode execution.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint

Skip steps at index < resume_from.

Noneon_stepAsyncStepHook

Async callback (step, status, message) invoked per step.

None

Yields:

Name Type Description StepResultAsyncIterator[StepResult]

One per executed node/step.

"},{"location":"#dagpipe.Graph","title":"Graph","text":"
Graph()\n

Directed Acyclic Graph defining execution topology of Node objects.

Notes

Responsibilities:

- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n

Guarantees:

- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n

Create an empty Graph.

"},{"location":"#dagpipe.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"#dagpipe.Graph-functions","title":"Functions","text":""},{"location":"#dagpipe.Graph.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"#dagpipe.Graph.__repr__--returns","title":"Returns","text":"

str

"},{"location":"#dagpipe.Graph.add_edge","title":"add_edge","text":"
add_edge(src: Node, dst: Node) -> None\n

Add a directed edge from src to dst.

Parameters:

Name Type Description Default srcNode

Source node.

required dstNode

Destination node.

required

Raises:

Type Description TypeError

If src or dst is not a Node.

ValueError

If the edge would create a cycle or if src and dst are common.

Notes
  • Validates node types.
  • Prevents cycles.
  • Registers nodes if not present.
  • Updates parent and child mappings.
"},{"location":"#dagpipe.Graph.add_root","title":"add_root","text":"
add_root(node: Node) -> None\n

Add a root node with no parents.

Parameters:

Name Type Description Default nodeNode

Node to add as a root.

required

Raises:

Type Description TypeError

If node is not a Node instance.

"},{"location":"#dagpipe.Graph.children","title":"children","text":"
children(node: Node) -> tuple[Node, ...]\n

Return child nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: Outgoing neighbors.

"},{"location":"#dagpipe.Graph.nodes","title":"nodes","text":"
nodes() -> tuple[Node, ...]\n

Return all nodes in the graph.

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: All registered nodes.

"},{"location":"#dagpipe.Graph.parents","title":"parents","text":"
parents(node: Node) -> tuple[Node, ...]\n

Return parent nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: Incoming neighbors.

"},{"location":"#dagpipe.Graph.roots","title":"roots","text":"
roots() -> tuple[Node, ...]\n

Return root nodes (nodes with no incoming edges).

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: Entry point nodes.

"},{"location":"#dagpipe.Node","title":"Node","text":"

Bases: ABC

Base class for all dagpipe execution nodes.

Attributes:

Name Type Description idstr

Unique identifier of the node (snake_case dotted format).

namestr

Human-readable display name.

Notes

Responsibilities:

- Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one `State` and produces zero, one, or many derived states.\n- Defines execution logic and enables branching, filtering, and transformation.\n

Guarantees:

- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n
"},{"location":"#dagpipe.Node-functions","title":"Functions","text":""},{"location":"#dagpipe.Node.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"#dagpipe.Node.__hash__--returns","title":"Returns","text":"

int

"},{"location":"#dagpipe.Node.__new__","title":"__new__","text":"
__new__(*args: Any, **kwargs: Any) -> Node\n

Create or reuse a Node instance.

Stateless subclasses (no parameterized __init__) share one singleton instance per class \u2014 matching the original dagpipe behaviour underpinning set_registry-style configuration. Subclasses that declare an __init__ requiring instance-state arguments get a fresh instance per construction so pipeline builders can inject per-run dependencies.

"},{"location":"#dagpipe.Node.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"#dagpipe.Node.__repr__--returns","title":"Returns","text":"

str

"},{"location":"#dagpipe.Node.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"#dagpipe.Node.__str__--returns","title":"Returns","text":"

str

"},{"location":"#dagpipe.Node.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"#dagpipe.Node.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateMapping[str, Any]

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateMapping[str, Any]

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"#dagpipe.Node.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"#dagpipe.Node.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"#dagpipe.Node.resolve","title":"resolve abstractmethod","text":"
resolve(state: State) -> Iterable[State]\n

Execute node logic.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Yields:

Name Type Description StateIterable[State]

Derived execution state(s).

Notes

Responsibilities:

- Subclasses implement specific resolution behavior.\n- Must not mutate input state.\n- Should use `fork()` to create child states.\n- May yield zero states to terminate a branch.\n
"},{"location":"#dagpipe.Node.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"#dagpipe.Payload","title":"Payload dataclass","text":"
Payload(_data: Mapping[str, Any])\n

Immutable hierarchical container with dot-path access.

Attributes:

Name Type Description _dataMapping[str, Any]

Immutable hierarchical data structure.

Notes

Responsibilities:

- Stores execution data used by `State`.\n- Supports efficient atomic updates without modifying existing instances.\n- `Payload` instances are fully thread-safe due to immutability.\n
"},{"location":"#dagpipe.Payload-functions","title":"Functions","text":""},{"location":"#dagpipe.Payload.as_dict","title":"as_dict","text":"
as_dict() -> Mapping[str, Any]\n

Return underlying mapping.

Returns:

Type Description Mapping[str, Any]

Mapping[str, Any]: Read-only view of the underlying data.

"},{"location":"#dagpipe.Payload.get","title":"get","text":"
get(path: str, default: Any = None) -> Any\n

Retrieve value using dot-path.

Parameters:

Name Type Description Default pathstr

Dot-separated path to the value.

required defaultAny

Default value if path doesn't exist.

None

Returns:

Name Type Description AnyAny

The retrieved value or default.

"},{"location":"#dagpipe.Payload.has","title":"has","text":"
has(path: str) -> bool\n

Return True if path exists.

Parameters:

Name Type Description Default pathstr

Dot-separated path to check.

required

Returns:

Name Type Description boolbool

Existence of the path.

"},{"location":"#dagpipe.Payload.iter_paths","title":"iter_paths classmethod","text":"
iter_paths(\n    data: Mapping[str, Any], prefix: str = \"\"\n) -> Iterable[str]\n

Recursively yield dot-paths for all leaf nodes.

Parameters:

Name Type Description Default dataMapping[str, Any]

The mapping to iterate over.

required prefixstr

Current path prefix.

''

Returns:

Type Description Iterable[str]

Iterable[str]: Generator yielding dot-paths.

"},{"location":"#dagpipe.Payload.keys","title":"keys","text":"
keys() -> Iterable[str]\n

Return top-level keys.

Returns:

Type Description Iterable[str]

Iterable[str]: Iterator over top-level keys.

"},{"location":"#dagpipe.Payload.update","title":"update","text":"
update(updates: Mapping[str, Any]) -> Payload\n

Create a new Payload with dot-path updates applied.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path to value mapping.

required

Returns:

Name Type Description PayloadPayload

New immutable payload instance with updates.

Notes

Guarantees:

- Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n
"},{"location":"#dagpipe.Pipeline","title":"Pipeline dataclass","text":"
Pipeline(\n    engine: Engine,\n    state_cls: type[State],\n    initial_payload: Payload,\n)\n

Executable pipeline created from YAML configuration.

Attributes:

Name Type Description engineEngine

Execution engine responsible for running the pipeline.

state_clsType[State]

Dynamically created State subclass with configured schema.

initial_payloadPayload

Default payload used when execution begins.

Notes

Responsibilities:

- Encapsulates engine, state type, and initial payload.\n- Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying nodes are thread-safe.\n
"},{"location":"#dagpipe.Pipeline-functions","title":"Functions","text":""},{"location":"#dagpipe.Pipeline.run","title":"run","text":"
run(\n    payload_override: Mapping[str, Any] | None = None,\n) -> list[State]\n

Execute the pipeline.

Parameters:

Name Type Description Default payload_overrideMapping[str, Any]

Payload values overriding initial payload.

None

Returns:

Type Description list[State]

list[State]: Terminal execution states.

Notes

Responsibilities:

- Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n
"},{"location":"#dagpipe.ProgressMessage","title":"ProgressMessage","text":"
ProgressMessage(\n    *,\n    lines: int | None = None,\n    blocks: int | None = None,\n    count: int | None = None,\n    unit: str | None = None,\n    raw_ocr_line: str | None = None,\n    error: str | None = None,\n    step: str = \"\",\n    status: str = \"\"\n)\n

Lightweight progress payload emitted by engine step hooks.

Mirrors the imperative ProgressMessage used by the legacy orchestrator so callers can surface counts/lines/errors without coupling the engine to pydantic.

"},{"location":"#dagpipe.Schema","title":"Schema dataclass","text":"
Schema(tree: Mapping[str, SchemaNode])\n

Immutable hierarchical schema defining allowed payload structure.

Attributes:

Name Type Description treeMapping[str, SchemaNode]

Hierarchical schema definition.

Notes

Responsibilities:

- Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n
"},{"location":"#dagpipe.Schema-functions","title":"Functions","text":""},{"location":"#dagpipe.Schema.validate_payload","title":"validate_payload","text":"
validate_payload(payload: Payload) -> None\n

Validate complete payload structure.

Parameters:

Name Type Description Default payloadPayload

Payload to validate.

required

Raises:

Type Description SchemaError

If payload violates schema.

"},{"location":"#dagpipe.Schema.validate_update","title":"validate_update","text":"
validate_update(updates: Mapping[str, Any]) -> None\n

Validate payload update paths.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path updates to validate.

required

Raises:

Type Description SchemaError

If any path is invalid according to the schema.

"},{"location":"#dagpipe.SchemaError","title":"SchemaError","text":"

Bases: Exception

Raised when payload data violates the declared schema.

"},{"location":"#dagpipe.SchemaError--indicates-invalid-structure-invalid-path-or-invalid-type","title":"Indicates invalid structure, invalid path, or invalid type.","text":""},{"location":"#dagpipe.State","title":"State dataclass","text":"
State(\n    payload: Payload,\n    confidence: float = 1.0,\n    parent: State | None = None,\n    depth: int = 0,\n    history: tuple[str, ...] = tuple(),\n    metadata: dict[str, Any] = dict(),\n)\n

Immutable execution state propagated through dagpipe pipeline.

Attributes:

Name Type Description payloadPayload

Execution data container.

schemaClassVar[Schema]

Payload validation schema.

confidencefloat

Execution confidence score.

parentOptional[State]

Parent state reference.

depthint

Execution depth.

historyTuple[str, ...]

Ordered node execution lineage.

metadataDict[str, Any]

Execution metadata.

Notes

Responsibilities:

- Represents a complete execution snapshot at a specific point in\n  pipeline traversal.\n- Fundamental unit of execution in `dagpipe`.\n- Fully thread-safe due to immutability.\n
"},{"location":"#dagpipe.State-functions","title":"Functions","text":""},{"location":"#dagpipe.State.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Concise debug representation.

Avoids printing full data for large states.

"},{"location":"#dagpipe.State.fork","title":"fork","text":"
fork(\n    *,\n    payload_update: Mapping[str, Any] | None = None,\n    confidence_delta: float = 0.0,\n    node_id: str | None = None,\n    metadata_update: Mapping[str, Any] | None = None\n) -> State\n

Create a new child State derived from this state.

Parameters:

Name Type Description Default payload_updateMapping[str, Any]

Dot-path updates applied to the payload.

Noneconfidence_deltafloat

Adjustment applied to current confidence.

0.0node_idstr

Identifier of the node creating this state.

Nonemetadata_updateMapping[str, Any]

Updates merged into state metadata.

None

Returns:

Name Type Description StateState

A new immutable State instance.

Notes

Guarantees:

- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n
"},{"location":"#dagpipe.State.get","title":"get","text":"
get(key: str, default: Any = None) -> Any\n

Retrieve payload value.

Parameters:

Name Type Description Default keystr

Dot-path key.

required defaultAny

Fallback value.

None

Returns:

Name Type Description AnyAny

Stored value or default.

"},{"location":"#dagpipe.State.has","title":"has","text":"
has(key: str) -> bool\n

Check whether payload contains key.

Parameters:

Name Type Description Default keystr

Dot-path key.

required

Returns:

Name Type Description boolbool

Existence of the key.

"},{"location":"#dagpipe.State.lineage","title":"lineage","text":"
lineage() -> tuple[State, ...]\n

Return lineage from root to this State.

Returns:

Type Description tuple[State, ...]

Tuple[State, ...]: Ordered execution lineage (root first).

"},{"location":"#dagpipe.StepResult","title":"StepResult","text":"
StepResult(\n    index: int,\n    node_id: str,\n    states: tuple[State, ...],\n    completed: bool,\n)\n

A single checkpointed step within an async/resumable engine run.

Attributes:

Name Type Description indexint

Ordinal index of the step.

node_idstr

Identifier of the node associated with this step.

statesTuple[State, ...]

States produced by running this step.

completedbool

Whether this step succeeded (vs. paused/interrupted).

"},{"location":"#dagpipe-functions","title":"Functions","text":""},{"location":"#dagpipe.load_pipeline","title":"load_pipeline","text":"
load_pipeline(path: str) -> Pipeline\n

Load pipeline from YAML file.

Parameters:

Name Type Description Default pathstr

Path to YAML configuration file.

required

Returns:

Name Type Description PipelinePipeline

Executable pipeline instance.

Notes

Responsibilities:

- Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n
"},{"location":"engine/","title":"Engine","text":""},{"location":"engine/#dagpipe.engine","title":"dagpipe.engine","text":""},{"location":"engine/#dagpipe.engine--summary","title":"Summary","text":"

Execution engine responsible for running pipelines and graphs.

The Engine executes Node objects and propagates immutable State instances through either a linear sequence or a directed acyclic graph (Graph). It orchestrates execution order, branching, and state propagation.

"},{"location":"engine/#dagpipe.engine--guarantees","title":"Guarantees","text":"
  • Deterministic execution and consistent state lineage.
  • Orchestrates execution without modifying Graph, Node, or State objects.
"},{"location":"engine/#dagpipe.engine-classes","title":"Classes","text":""},{"location":"engine/#dagpipe.engine.Engine","title":"Engine","text":"
Engine(\n    nodes_or_graph: Sequence[Node] | Graph,\n    *,\n    on_step: StepHook | None = None\n)\n

Execution engine responsible for running pipeline logic.

Notes

Responsibilities:

- Accepts either a linear sequence of `Node` objects or a `Graph`\n  defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n  collects terminal states.\n- Supports synchronous (`run`) and asynchronous (`run_async`)\n  execution, dispatching per-node.\n- Supports step-wise / resumable execution and progress hooks.\n

Guarantees:

- Never mutates `State`, `Node`, or `Graph` instances.\n- `State` objects are never modified in place; each branch produces\n  independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
"},{"location":"engine/#dagpipe.engine.Engine-attributes","title":"Attributes","text":""},{"location":"engine/#dagpipe.engine.Engine.nodes","title":"nodes property","text":"
nodes: tuple[Node, ...]\n

Return nodes managed by this engine.

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.

"},{"location":"engine/#dagpipe.engine.Engine-functions","title":"Functions","text":""},{"location":"engine/#dagpipe.engine.Engine.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return the canonical string representation of the object.

Returns:

Name Type Description strstr

Representation that uniquely identifies the object and its configuration.

"},{"location":"engine/#dagpipe.engine.Engine.run","title":"run","text":"
run(root: State) -> list[State]\n

Execute the pipeline starting from a root State.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Raises:

Type Description TypeError

If root is not a State instance.

RuntimeError

If the engine execution mode is invalid.

Notes

Responsibilities:

- Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n
"},{"location":"engine/#dagpipe.engine.Engine.run_async","title":"run_async async","text":"
run_async(root: State) -> list[State]\n

Execute the pipeline starting from root, dispatching sync vs async nodes.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Notes

Each node is executed with Node.run when synchronous and AsyncNode.run_async when asynchronous. Linear and graph topologies are both supported.

"},{"location":"engine/#dagpipe.engine.Engine.run_steps","title":"run_steps","text":"
run_steps(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: StepHook | None = None\n) -> Iterator[StepResult]\n

Execute the pipeline step-by-step, yielding one StepResult per step.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint

Skip steps at index < resume_from (for resume-after-partial). Steps are 0-indexed.

Noneon_stepStepHook

Callback (step, status, message) invoked per step; falls back to the engine-level hook when unset.

None

Yields:

Name Type Description StepResultStepResult

One per executed node/step, carrying the produced states.

Notes

This is a synchronous, generator-based checkpoint interface compatible with the imperative resume-by-step behaviour of the legacy orchestrator. Use run_steps_async for async nodes.

"},{"location":"engine/#dagpipe.engine.Engine.run_steps_async","title":"run_steps_async async","text":"
run_steps_async(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: AsyncStepHook | None = None\n) -> AsyncIterator[StepResult]\n

Async variant of run_steps supporting AsyncNode execution.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint

Skip steps at index < resume_from.

Noneon_stepAsyncStepHook

Async callback (step, status, message) invoked per step.

None

Yields:

Name Type Description StepResultAsyncIterator[StepResult]

One per executed node/step.

"},{"location":"engine/#dagpipe.engine.ProgressMessage","title":"ProgressMessage","text":"
ProgressMessage(\n    *,\n    lines: int | None = None,\n    blocks: int | None = None,\n    count: int | None = None,\n    unit: str | None = None,\n    raw_ocr_line: str | None = None,\n    error: str | None = None,\n    step: str = \"\",\n    status: str = \"\"\n)\n

Lightweight progress payload emitted by engine step hooks.

Mirrors the imperative ProgressMessage used by the legacy orchestrator so callers can surface counts/lines/errors without coupling the engine to pydantic.

"},{"location":"engine/#dagpipe.engine.StepResult","title":"StepResult","text":"
StepResult(\n    index: int,\n    node_id: str,\n    states: tuple[State, ...],\n    completed: bool,\n)\n

A single checkpointed step within an async/resumable engine run.

Attributes:

Name Type Description indexint

Ordinal index of the step.

node_idstr

Identifier of the node associated with this step.

statesTuple[State, ...]

States produced by running this step.

completedbool

Whether this step succeeded (vs. paused/interrupted).

"},{"location":"graph/","title":"Graph","text":""},{"location":"graph/#dagpipe.graph","title":"dagpipe.graph","text":""},{"location":"graph/#dagpipe.graph--summary","title":"Summary","text":"

Defines DAG structure connecting nodes.

A Graph describes execution topology only. It does not execute nodes or manage State. Execution is handled by an Engine.

"},{"location":"graph/#dagpipe.graph--responsibilities","title":"Responsibilities","text":"
  • Multiple roots, branching, and merging support.
  • Deterministic traversal based on topology.
  • Graph is mutable during construction but treated as immutable at runtime.
"},{"location":"graph/#dagpipe.graph-classes","title":"Classes","text":""},{"location":"graph/#dagpipe.graph.Graph","title":"Graph","text":"
Graph()\n

Directed Acyclic Graph defining execution topology of Node objects.

Notes

Responsibilities:

- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n

Guarantees:

- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n

Create an empty Graph.

"},{"location":"graph/#dagpipe.graph.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"graph/#dagpipe.graph.Graph-functions","title":"Functions","text":""},{"location":"graph/#dagpipe.graph.Graph.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"graph/#dagpipe.graph.Graph.__repr__--returns","title":"Returns","text":"

str

"},{"location":"graph/#dagpipe.graph.Graph.add_edge","title":"add_edge","text":"
add_edge(src: Node, dst: Node) -> None\n

Add a directed edge from src to dst.

Parameters:

Name Type Description Default srcNode

Source node.

required dstNode

Destination node.

required

Raises:

Type Description TypeError

If src or dst is not a Node.

ValueError

If the edge would create a cycle or if src and dst are common.

Notes
  • Validates node types.
  • Prevents cycles.
  • Registers nodes if not present.
  • Updates parent and child mappings.
"},{"location":"graph/#dagpipe.graph.Graph.add_root","title":"add_root","text":"
add_root(node: Node) -> None\n

Add a root node with no parents.

Parameters:

Name Type Description Default nodeNode

Node to add as a root.

required

Raises:

Type Description TypeError

If node is not a Node instance.

"},{"location":"graph/#dagpipe.graph.Graph.children","title":"children","text":"
children(node: Node) -> tuple[Node, ...]\n

Return child nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: Outgoing neighbors.

"},{"location":"graph/#dagpipe.graph.Graph.nodes","title":"nodes","text":"
nodes() -> tuple[Node, ...]\n

Return all nodes in the graph.

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: All registered nodes.

"},{"location":"graph/#dagpipe.graph.Graph.parents","title":"parents","text":"
parents(node: Node) -> tuple[Node, ...]\n

Return parent nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: Incoming neighbors.

"},{"location":"graph/#dagpipe.graph.Graph.roots","title":"roots","text":"
roots() -> tuple[Node, ...]\n

Return root nodes (nodes with no incoming edges).

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: Entry point nodes.

"},{"location":"node/","title":"Node","text":""},{"location":"node/#dagpipe.node","title":"dagpipe.node","text":""},{"location":"node/#dagpipe.node--summary","title":"Summary","text":"

Defines the Node abstraction used by dagpipe.

A node represents a single unit of pipeline execution logic. It consumes one State and produces zero, one, or many new State objects.

Nodes are connected using a Graph and executed by an Engine.

"},{"location":"node/#dagpipe.node--design-principles","title":"Design principles","text":"
  • Pure: Must not mutate input state.
  • Deterministic: Same input produces same output.
  • Stateless: Recommended to be stateless for reuse.
  • Composable: Nodes enable branching execution graphs.
"},{"location":"node/#dagpipe.node-classes","title":"Classes","text":""},{"location":"node/#dagpipe.node.AsyncNode","title":"AsyncNode","text":"

Bases: Node

Base class for nodes whose execution is asynchronous.

Subclasses implement resolve_async (an async generator yielding derived State objects). The engine dispatches to resolve_async when running an async traversal (see Engine.run_async).

Sync-only engines (and the base Node.run) treat an AsyncNode as a no-op consumer: calling run on an AsyncNode returns no states, signalling that an async engine is required.

"},{"location":"node/#dagpipe.node.AsyncNode-functions","title":"Functions","text":""},{"location":"node/#dagpipe.node.AsyncNode.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"node/#dagpipe.node.AsyncNode.__hash__--returns","title":"Returns","text":"

int

"},{"location":"node/#dagpipe.node.AsyncNode.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"node/#dagpipe.node.AsyncNode.__repr__--returns","title":"Returns","text":"

str

"},{"location":"node/#dagpipe.node.AsyncNode.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"node/#dagpipe.node.AsyncNode.__str__--returns","title":"Returns","text":"

str

"},{"location":"node/#dagpipe.node.AsyncNode.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"node/#dagpipe.node.AsyncNode.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateMapping[str, Any]

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateMapping[str, Any]

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"node/#dagpipe.node.AsyncNode.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"node/#dagpipe.node.AsyncNode.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"node/#dagpipe.node.AsyncNode.resolve_async","title":"resolve_async async","text":"
resolve_async(state: State) -> Iterable[State]\n

Execute node logic asynchronously.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description Iterable[State]

Iterable[State]: Derived execution state(s).

Notes

Subclasses implement this. Must not mutate the input state. Should use fork() to create child states.

"},{"location":"node/#dagpipe.node.AsyncNode.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"node/#dagpipe.node.AsyncNode.run_async","title":"run_async async","text":"
run_async(state: State) -> tuple[State, ...]\n

Execute this node asynchronously on a state, validating outputs.

"},{"location":"node/#dagpipe.node.Node","title":"Node","text":"

Bases: ABC

Base class for all dagpipe execution nodes.

Attributes:

Name Type Description idstr

Unique identifier of the node (snake_case dotted format).

namestr

Human-readable display name.

Notes

Responsibilities:

- Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one `State` and produces zero, one, or many derived states.\n- Defines execution logic and enables branching, filtering, and transformation.\n

Guarantees:

- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n
"},{"location":"node/#dagpipe.node.Node-functions","title":"Functions","text":""},{"location":"node/#dagpipe.node.Node.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"node/#dagpipe.node.Node.__hash__--returns","title":"Returns","text":"

int

"},{"location":"node/#dagpipe.node.Node.__new__","title":"__new__","text":"
__new__(*args: Any, **kwargs: Any) -> Node\n

Create or reuse a Node instance.

Stateless subclasses (no parameterized __init__) share one singleton instance per class \u2014 matching the original dagpipe behaviour underpinning set_registry-style configuration. Subclasses that declare an __init__ requiring instance-state arguments get a fresh instance per construction so pipeline builders can inject per-run dependencies.

"},{"location":"node/#dagpipe.node.Node.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"node/#dagpipe.node.Node.__repr__--returns","title":"Returns","text":"

str

"},{"location":"node/#dagpipe.node.Node.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"node/#dagpipe.node.Node.__str__--returns","title":"Returns","text":"

str

"},{"location":"node/#dagpipe.node.Node.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"node/#dagpipe.node.Node.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateMapping[str, Any]

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateMapping[str, Any]

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"node/#dagpipe.node.Node.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"node/#dagpipe.node.Node.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"node/#dagpipe.node.Node.resolve","title":"resolve abstractmethod","text":"
resolve(state: State) -> Iterable[State]\n

Execute node logic.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Yields:

Name Type Description StateIterable[State]

Derived execution state(s).

Notes

Responsibilities:

- Subclasses implement specific resolution behavior.\n- Must not mutate input state.\n- Should use `fork()` to create child states.\n- May yield zero states to terminate a branch.\n
"},{"location":"node/#dagpipe.node.Node.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"state/","title":"State","text":""},{"location":"state/#dagpipe.state","title":"dagpipe.state","text":""},{"location":"state/#dagpipe.state--summary","title":"Summary","text":"

Defines the core State object used by dagpipe.

The State represents a single point in pipeline execution. It contains arbitrary data and metadata and is designed to be immutable. Instead of modifying an existing state, nodes create new child states via fork().

"},{"location":"state/#dagpipe.state--design-principles","title":"Design principles","text":"
  • Immutability: States must never be modified after creation. All transformations must create a new state via fork().
  • Cheap cloning: Forking must be efficient since branching may create many states.
  • Lineage tracking: Each state maintains a reference to its parent and execution metadata for debugging and observability.
  • Domain agnostic: State contains generic key-value data and does not assume any schema.
  • Engine-friendly: State contains execution metadata such as depth and history.
"},{"location":"state/#dagpipe.state-classes","title":"Classes","text":""},{"location":"state/#dagpipe.state.Payload","title":"Payload dataclass","text":"
Payload(_data: Mapping[str, Any])\n

Immutable hierarchical container with dot-path access.

Attributes:

Name Type Description _dataMapping[str, Any]

Immutable hierarchical data structure.

Notes

Responsibilities:

- Stores execution data used by `State`.\n- Supports efficient atomic updates without modifying existing instances.\n- `Payload` instances are fully thread-safe due to immutability.\n
"},{"location":"state/#dagpipe.state.Payload-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.Payload.as_dict","title":"as_dict","text":"
as_dict() -> Mapping[str, Any]\n

Return underlying mapping.

Returns:

Type Description Mapping[str, Any]

Mapping[str, Any]: Read-only view of the underlying data.

"},{"location":"state/#dagpipe.state.Payload.get","title":"get","text":"
get(path: str, default: Any = None) -> Any\n

Retrieve value using dot-path.

Parameters:

Name Type Description Default pathstr

Dot-separated path to the value.

required defaultAny

Default value if path doesn't exist.

None

Returns:

Name Type Description AnyAny

The retrieved value or default.

"},{"location":"state/#dagpipe.state.Payload.has","title":"has","text":"
has(path: str) -> bool\n

Return True if path exists.

Parameters:

Name Type Description Default pathstr

Dot-separated path to check.

required

Returns:

Name Type Description boolbool

Existence of the path.

"},{"location":"state/#dagpipe.state.Payload.iter_paths","title":"iter_paths classmethod","text":"
iter_paths(\n    data: Mapping[str, Any], prefix: str = \"\"\n) -> Iterable[str]\n

Recursively yield dot-paths for all leaf nodes.

Parameters:

Name Type Description Default dataMapping[str, Any]

The mapping to iterate over.

required prefixstr

Current path prefix.

''

Returns:

Type Description Iterable[str]

Iterable[str]: Generator yielding dot-paths.

"},{"location":"state/#dagpipe.state.Payload.keys","title":"keys","text":"
keys() -> Iterable[str]\n

Return top-level keys.

Returns:

Type Description Iterable[str]

Iterable[str]: Iterator over top-level keys.

"},{"location":"state/#dagpipe.state.Payload.update","title":"update","text":"
update(updates: Mapping[str, Any]) -> Payload\n

Create a new Payload with dot-path updates applied.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path to value mapping.

required

Returns:

Name Type Description PayloadPayload

New immutable payload instance with updates.

Notes

Guarantees:

- Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n
"},{"location":"state/#dagpipe.state.Schema","title":"Schema dataclass","text":"
Schema(tree: Mapping[str, SchemaNode])\n

Immutable hierarchical schema defining allowed payload structure.

Attributes:

Name Type Description treeMapping[str, SchemaNode]

Hierarchical schema definition.

Notes

Responsibilities:

- Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n
"},{"location":"state/#dagpipe.state.Schema-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.Schema.validate_payload","title":"validate_payload","text":"
validate_payload(payload: Payload) -> None\n

Validate complete payload structure.

Parameters:

Name Type Description Default payloadPayload

Payload to validate.

required

Raises:

Type Description SchemaError

If payload violates schema.

"},{"location":"state/#dagpipe.state.Schema.validate_update","title":"validate_update","text":"
validate_update(updates: Mapping[str, Any]) -> None\n

Validate payload update paths.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path updates to validate.

required

Raises:

Type Description SchemaError

If any path is invalid according to the schema.

"},{"location":"state/#dagpipe.state.SchemaError","title":"SchemaError","text":"

Bases: Exception

Raised when payload data violates the declared schema.

"},{"location":"state/#dagpipe.state.SchemaError--indicates-invalid-structure-invalid-path-or-invalid-type","title":"Indicates invalid structure, invalid path, or invalid type.","text":""},{"location":"state/#dagpipe.state.State","title":"State dataclass","text":"
State(\n    payload: Payload,\n    confidence: float = 1.0,\n    parent: State | None = None,\n    depth: int = 0,\n    history: tuple[str, ...] = tuple(),\n    metadata: dict[str, Any] = dict(),\n)\n

Immutable execution state propagated through dagpipe pipeline.

Attributes:

Name Type Description payloadPayload

Execution data container.

schemaClassVar[Schema]

Payload validation schema.

confidencefloat

Execution confidence score.

parentOptional[State]

Parent state reference.

depthint

Execution depth.

historyTuple[str, ...]

Ordered node execution lineage.

metadataDict[str, Any]

Execution metadata.

Notes

Responsibilities:

- Represents a complete execution snapshot at a specific point in\n  pipeline traversal.\n- Fundamental unit of execution in `dagpipe`.\n- Fully thread-safe due to immutability.\n
"},{"location":"state/#dagpipe.state.State-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.State.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Concise debug representation.

Avoids printing full data for large states.

"},{"location":"state/#dagpipe.state.State.fork","title":"fork","text":"
fork(\n    *,\n    payload_update: Mapping[str, Any] | None = None,\n    confidence_delta: float = 0.0,\n    node_id: str | None = None,\n    metadata_update: Mapping[str, Any] | None = None\n) -> State\n

Create a new child State derived from this state.

Parameters:

Name Type Description Default payload_updateMapping[str, Any]

Dot-path updates applied to the payload.

Noneconfidence_deltafloat

Adjustment applied to current confidence.

0.0node_idstr

Identifier of the node creating this state.

Nonemetadata_updateMapping[str, Any]

Updates merged into state metadata.

None

Returns:

Name Type Description StateState

A new immutable State instance.

Notes

Guarantees:

- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n
"},{"location":"state/#dagpipe.state.State.get","title":"get","text":"
get(key: str, default: Any = None) -> Any\n

Retrieve payload value.

Parameters:

Name Type Description Default keystr

Dot-path key.

required defaultAny

Fallback value.

None

Returns:

Name Type Description AnyAny

Stored value or default.

"},{"location":"state/#dagpipe.state.State.has","title":"has","text":"
has(key: str) -> bool\n

Check whether payload contains key.

Parameters:

Name Type Description Default keystr

Dot-path key.

required

Returns:

Name Type Description boolbool

Existence of the key.

"},{"location":"state/#dagpipe.state.State.lineage","title":"lineage","text":"
lineage() -> tuple[State, ...]\n

Return lineage from root to this State.

Returns:

Type Description tuple[State, ...]

Tuple[State, ...]: Ordered execution lineage (root first).

"},{"location":"yaml_loader/","title":"Yaml Loader","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader","title":"dagpipe.yaml_loader","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader--summary","title":"Summary","text":"

Loads dagpipe pipelines from YAML configuration.

Creates fully configured pipeline objects from declarative YAML definitions, including Schema, State subclasses, Node instances, Graph topology, and initial payloads.

"},{"location":"yaml_loader/#dagpipe.yaml_loader-classes","title":"Classes","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline","title":"Pipeline dataclass","text":"
Pipeline(\n    engine: Engine,\n    state_cls: type[State],\n    initial_payload: Payload,\n)\n

Executable pipeline created from YAML configuration.

Attributes:

Name Type Description engineEngine

Execution engine responsible for running the pipeline.

state_clsType[State]

Dynamically created State subclass with configured schema.

initial_payloadPayload

Default payload used when execution begins.

Notes

Responsibilities:

- Encapsulates engine, state type, and initial payload.\n- Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying nodes are thread-safe.\n
"},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline-functions","title":"Functions","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline.run","title":"run","text":"
run(\n    payload_override: Mapping[str, Any] | None = None,\n) -> list[State]\n

Execute the pipeline.

Parameters:

Name Type Description Default payload_overrideMapping[str, Any]

Payload values overriding initial payload.

None

Returns:

Type Description list[State]

list[State]: Terminal execution states.

Notes

Responsibilities:

- Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n
"},{"location":"yaml_loader/#dagpipe.yaml_loader-functions","title":"Functions","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.load_pipeline","title":"load_pipeline","text":"
load_pipeline(path: str) -> Pipeline\n

Load pipeline from YAML file.

Parameters:

Name Type Description Default pathstr

Path to YAML configuration file.

required

Returns:

Name Type Description PipelinePipeline

Executable pipeline instance.

Notes

Responsibilities:

- Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n
"},{"location":"dagpipe/","title":"Dagpipe","text":"
  • Engine
  • Graph
  • Node
  • State
  • Yaml Loader
"},{"location":"dagpipe/#dagpipe","title":"dagpipe","text":""},{"location":"dagpipe/#dagpipe--summary","title":"Summary","text":"

Directed acyclic graph execution framework for deterministic state propagation.

dagpipe executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable State and optionally produces derived states for downstream nodes.

"},{"location":"dagpipe/#dagpipe--installation","title":"Installation","text":"

Install using pip:

pip install dagpipe\n
"},{"location":"dagpipe/#dagpipe--quick-start","title":"Quick Start","text":"
from dagpipe import State, Payload, Schema, Graph, Engine\nfrom dagpipe.node import Node\n\nclass HelloNode(Node):\n    id = \"hello\"\n    def resolve(self, state):\n        yield self.fork(state, payload_update={\"msg\": \"hello\"})\n\n# Build and run\ngraph = Graph()\ngraph.add_root(HelloNode())\nengine = Engine(graph)\n\nclass MyState(State):\n    schema = Schema({})\n\nresults = engine.run(MyState(payload=Payload({})))\n
"},{"location":"dagpipe/#dagpipe--public-api","title":"Public API","text":"

This package re-exports the core pipeline components. Consumers should import from this namespace for standard usage.

"},{"location":"dagpipe/#dagpipe--execution-core","title":"Execution Core","text":"
  • Engine: Responsible for orchestrating node execution and state propagation.
  • Graph: Defines the execution topology and node relationships.
  • Node: Base class for defining execution logic and transformations.
"},{"location":"dagpipe/#dagpipe--state-data","title":"State & Data","text":"
  • State: Represents an immutable execution snapshot at a point in time.
  • Payload: Immutable hierarchical container for execution data.
  • Schema: Defines and validates the allowed structure of payloads.
  • SchemaError: Raised when data violates the declared schema.
"},{"location":"dagpipe/#dagpipe--declarative-pipelines","title":"Declarative Pipelines","text":"
  • Pipeline: High-level wrapper for an engine, state type, and initial payload.
  • load_pipeline: Factory function to create a pipeline from YAML.
"},{"location":"dagpipe/#dagpipe-classes","title":"Classes","text":""},{"location":"dagpipe/#dagpipe.AsyncNode","title":"AsyncNode","text":"

Bases: Node

Base class for nodes whose execution is asynchronous.

Subclasses implement resolve_async (an async generator yielding derived State objects). The engine dispatches to resolve_async when running an async traversal (see Engine.run_async).

Sync-only engines (and the base Node.run) treat an AsyncNode as a no-op consumer: calling run on an AsyncNode returns no states, signalling that an async engine is required.

"},{"location":"dagpipe/#dagpipe.AsyncNode-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.AsyncNode.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"dagpipe/#dagpipe.AsyncNode.__hash__--returns","title":"Returns","text":"

int

"},{"location":"dagpipe/#dagpipe.AsyncNode.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"dagpipe/#dagpipe.AsyncNode.__repr__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/#dagpipe.AsyncNode.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"dagpipe/#dagpipe.AsyncNode.__str__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/#dagpipe.AsyncNode.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"dagpipe/#dagpipe.AsyncNode.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateMapping[str, Any]

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateMapping[str, Any]

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"dagpipe/#dagpipe.AsyncNode.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"dagpipe/#dagpipe.AsyncNode.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"dagpipe/#dagpipe.AsyncNode.resolve_async","title":"resolve_async async","text":"
resolve_async(state: State) -> Iterable[State]\n

Execute node logic asynchronously.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description Iterable[State]

Iterable[State]: Derived execution state(s).

Notes

Subclasses implement this. Must not mutate the input state. Should use fork() to create child states.

"},{"location":"dagpipe/#dagpipe.AsyncNode.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"dagpipe/#dagpipe.AsyncNode.run_async","title":"run_async async","text":"
run_async(state: State) -> tuple[State, ...]\n

Execute this node asynchronously on a state, validating outputs.

"},{"location":"dagpipe/#dagpipe.Engine","title":"Engine","text":"
Engine(\n    nodes_or_graph: Sequence[Node] | Graph,\n    *,\n    on_step: StepHook | None = None\n)\n

Execution engine responsible for running pipeline logic.

Notes

Responsibilities:

- Accepts either a linear sequence of `Node` objects or a `Graph`\n  defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n  collects terminal states.\n- Supports synchronous (`run`) and asynchronous (`run_async`)\n  execution, dispatching per-node.\n- Supports step-wise / resumable execution and progress hooks.\n

Guarantees:

- Never mutates `State`, `Node`, or `Graph` instances.\n- `State` objects are never modified in place; each branch produces\n  independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
"},{"location":"dagpipe/#dagpipe.Engine-attributes","title":"Attributes","text":""},{"location":"dagpipe/#dagpipe.Engine.nodes","title":"nodes property","text":"
nodes: tuple[Node, ...]\n

Return nodes managed by this engine.

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.

"},{"location":"dagpipe/#dagpipe.Engine-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Engine.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return the canonical string representation of the object.

Returns:

Name Type Description strstr

Representation that uniquely identifies the object and its configuration.

"},{"location":"dagpipe/#dagpipe.Engine.run","title":"run","text":"
run(root: State) -> list[State]\n

Execute the pipeline starting from a root State.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Raises:

Type Description TypeError

If root is not a State instance.

RuntimeError

If the engine execution mode is invalid.

Notes

Responsibilities:

- Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n
"},{"location":"dagpipe/#dagpipe.Engine.run_async","title":"run_async async","text":"
run_async(root: State) -> list[State]\n

Execute the pipeline starting from root, dispatching sync vs async nodes.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Notes

Each node is executed with Node.run when synchronous and AsyncNode.run_async when asynchronous. Linear and graph topologies are both supported.

"},{"location":"dagpipe/#dagpipe.Engine.run_steps","title":"run_steps","text":"
run_steps(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: StepHook | None = None\n) -> Iterator[StepResult]\n

Execute the pipeline step-by-step, yielding one StepResult per step.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint

Skip steps at index < resume_from (for resume-after-partial). Steps are 0-indexed.

Noneon_stepStepHook

Callback (step, status, message) invoked per step; falls back to the engine-level hook when unset.

None

Yields:

Name Type Description StepResultStepResult

One per executed node/step, carrying the produced states.

Notes

This is a synchronous, generator-based checkpoint interface compatible with the imperative resume-by-step behaviour of the legacy orchestrator. Use run_steps_async for async nodes.

"},{"location":"dagpipe/#dagpipe.Engine.run_steps_async","title":"run_steps_async async","text":"
run_steps_async(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: AsyncStepHook | None = None\n) -> AsyncIterator[StepResult]\n

Async variant of run_steps supporting AsyncNode execution.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint

Skip steps at index < resume_from.

Noneon_stepAsyncStepHook

Async callback (step, status, message) invoked per step.

None

Yields:

Name Type Description StepResultAsyncIterator[StepResult]

One per executed node/step.

"},{"location":"dagpipe/#dagpipe.Graph","title":"Graph","text":"
Graph()\n

Directed Acyclic Graph defining execution topology of Node objects.

Notes

Responsibilities:

- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n

Guarantees:

- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n

Create an empty Graph.

"},{"location":"dagpipe/#dagpipe.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"dagpipe/#dagpipe.Graph-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Graph.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"dagpipe/#dagpipe.Graph.__repr__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/#dagpipe.Graph.add_edge","title":"add_edge","text":"
add_edge(src: Node, dst: Node) -> None\n

Add a directed edge from src to dst.

Parameters:

Name Type Description Default srcNode

Source node.

required dstNode

Destination node.

required

Raises:

Type Description TypeError

If src or dst is not a Node.

ValueError

If the edge would create a cycle or if src and dst are common.

Notes
  • Validates node types.
  • Prevents cycles.
  • Registers nodes if not present.
  • Updates parent and child mappings.
"},{"location":"dagpipe/#dagpipe.Graph.add_root","title":"add_root","text":"
add_root(node: Node) -> None\n

Add a root node with no parents.

Parameters:

Name Type Description Default nodeNode

Node to add as a root.

required

Raises:

Type Description TypeError

If node is not a Node instance.

"},{"location":"dagpipe/#dagpipe.Graph.children","title":"children","text":"
children(node: Node) -> tuple[Node, ...]\n

Return child nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: Outgoing neighbors.

"},{"location":"dagpipe/#dagpipe.Graph.nodes","title":"nodes","text":"
nodes() -> tuple[Node, ...]\n

Return all nodes in the graph.

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: All registered nodes.

"},{"location":"dagpipe/#dagpipe.Graph.parents","title":"parents","text":"
parents(node: Node) -> tuple[Node, ...]\n

Return parent nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: Incoming neighbors.

"},{"location":"dagpipe/#dagpipe.Graph.roots","title":"roots","text":"
roots() -> tuple[Node, ...]\n

Return root nodes (nodes with no incoming edges).

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: Entry point nodes.

"},{"location":"dagpipe/#dagpipe.Node","title":"Node","text":"

Bases: ABC

Base class for all dagpipe execution nodes.

Attributes:

Name Type Description idstr

Unique identifier of the node (snake_case dotted format).

namestr

Human-readable display name.

Notes

Responsibilities:

- Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one `State` and produces zero, one, or many derived states.\n- Defines execution logic and enables branching, filtering, and transformation.\n

Guarantees:

- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n
"},{"location":"dagpipe/#dagpipe.Node-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Node.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"dagpipe/#dagpipe.Node.__hash__--returns","title":"Returns","text":"

int

"},{"location":"dagpipe/#dagpipe.Node.__new__","title":"__new__","text":"
__new__(*args: Any, **kwargs: Any) -> Node\n

Create or reuse a Node instance.

Stateless subclasses (no parameterized __init__) share one singleton instance per class \u2014 matching the original dagpipe behaviour underpinning set_registry-style configuration. Subclasses that declare an __init__ requiring instance-state arguments get a fresh instance per construction so pipeline builders can inject per-run dependencies.

"},{"location":"dagpipe/#dagpipe.Node.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"dagpipe/#dagpipe.Node.__repr__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/#dagpipe.Node.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"dagpipe/#dagpipe.Node.__str__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/#dagpipe.Node.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"dagpipe/#dagpipe.Node.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateMapping[str, Any]

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateMapping[str, Any]

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"dagpipe/#dagpipe.Node.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"dagpipe/#dagpipe.Node.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"dagpipe/#dagpipe.Node.resolve","title":"resolve abstractmethod","text":"
resolve(state: State) -> Iterable[State]\n

Execute node logic.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Yields:

Name Type Description StateIterable[State]

Derived execution state(s).

Notes

Responsibilities:

- Subclasses implement specific resolution behavior.\n- Must not mutate input state.\n- Should use `fork()` to create child states.\n- May yield zero states to terminate a branch.\n
"},{"location":"dagpipe/#dagpipe.Node.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"dagpipe/#dagpipe.Payload","title":"Payload dataclass","text":"
Payload(_data: Mapping[str, Any])\n

Immutable hierarchical container with dot-path access.

Attributes:

Name Type Description _dataMapping[str, Any]

Immutable hierarchical data structure.

Notes

Responsibilities:

- Stores execution data used by `State`.\n- Supports efficient atomic updates without modifying existing instances.\n- `Payload` instances are fully thread-safe due to immutability.\n
"},{"location":"dagpipe/#dagpipe.Payload-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Payload.as_dict","title":"as_dict","text":"
as_dict() -> Mapping[str, Any]\n

Return underlying mapping.

Returns:

Type Description Mapping[str, Any]

Mapping[str, Any]: Read-only view of the underlying data.

"},{"location":"dagpipe/#dagpipe.Payload.get","title":"get","text":"
get(path: str, default: Any = None) -> Any\n

Retrieve value using dot-path.

Parameters:

Name Type Description Default pathstr

Dot-separated path to the value.

required defaultAny

Default value if path doesn't exist.

None

Returns:

Name Type Description AnyAny

The retrieved value or default.

"},{"location":"dagpipe/#dagpipe.Payload.has","title":"has","text":"
has(path: str) -> bool\n

Return True if path exists.

Parameters:

Name Type Description Default pathstr

Dot-separated path to check.

required

Returns:

Name Type Description boolbool

Existence of the path.

"},{"location":"dagpipe/#dagpipe.Payload.iter_paths","title":"iter_paths classmethod","text":"
iter_paths(\n    data: Mapping[str, Any], prefix: str = \"\"\n) -> Iterable[str]\n

Recursively yield dot-paths for all leaf nodes.

Parameters:

Name Type Description Default dataMapping[str, Any]

The mapping to iterate over.

required prefixstr

Current path prefix.

''

Returns:

Type Description Iterable[str]

Iterable[str]: Generator yielding dot-paths.

"},{"location":"dagpipe/#dagpipe.Payload.keys","title":"keys","text":"
keys() -> Iterable[str]\n

Return top-level keys.

Returns:

Type Description Iterable[str]

Iterable[str]: Iterator over top-level keys.

"},{"location":"dagpipe/#dagpipe.Payload.update","title":"update","text":"
update(updates: Mapping[str, Any]) -> Payload\n

Create a new Payload with dot-path updates applied.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path to value mapping.

required

Returns:

Name Type Description PayloadPayload

New immutable payload instance with updates.

Notes

Guarantees:

- Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n
"},{"location":"dagpipe/#dagpipe.Pipeline","title":"Pipeline dataclass","text":"
Pipeline(\n    engine: Engine,\n    state_cls: type[State],\n    initial_payload: Payload,\n)\n

Executable pipeline created from YAML configuration.

Attributes:

Name Type Description engineEngine

Execution engine responsible for running the pipeline.

state_clsType[State]

Dynamically created State subclass with configured schema.

initial_payloadPayload

Default payload used when execution begins.

Notes

Responsibilities:

- Encapsulates engine, state type, and initial payload.\n- Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying nodes are thread-safe.\n
"},{"location":"dagpipe/#dagpipe.Pipeline-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Pipeline.run","title":"run","text":"
run(\n    payload_override: Mapping[str, Any] | None = None,\n) -> list[State]\n

Execute the pipeline.

Parameters:

Name Type Description Default payload_overrideMapping[str, Any]

Payload values overriding initial payload.

None

Returns:

Type Description list[State]

list[State]: Terminal execution states.

Notes

Responsibilities:

- Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n
"},{"location":"dagpipe/#dagpipe.ProgressMessage","title":"ProgressMessage","text":"
ProgressMessage(\n    *,\n    lines: int | None = None,\n    blocks: int | None = None,\n    count: int | None = None,\n    unit: str | None = None,\n    raw_ocr_line: str | None = None,\n    error: str | None = None,\n    step: str = \"\",\n    status: str = \"\"\n)\n

Lightweight progress payload emitted by engine step hooks.

Mirrors the imperative ProgressMessage used by the legacy orchestrator so callers can surface counts/lines/errors without coupling the engine to pydantic.

"},{"location":"dagpipe/#dagpipe.Schema","title":"Schema dataclass","text":"
Schema(tree: Mapping[str, SchemaNode])\n

Immutable hierarchical schema defining allowed payload structure.

Attributes:

Name Type Description treeMapping[str, SchemaNode]

Hierarchical schema definition.

Notes

Responsibilities:

- Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n
"},{"location":"dagpipe/#dagpipe.Schema-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Schema.validate_payload","title":"validate_payload","text":"
validate_payload(payload: Payload) -> None\n

Validate complete payload structure.

Parameters:

Name Type Description Default payloadPayload

Payload to validate.

required

Raises:

Type Description SchemaError

If payload violates schema.

"},{"location":"dagpipe/#dagpipe.Schema.validate_update","title":"validate_update","text":"
validate_update(updates: Mapping[str, Any]) -> None\n

Validate payload update paths.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path updates to validate.

required

Raises:

Type Description SchemaError

If any path is invalid according to the schema.

"},{"location":"dagpipe/#dagpipe.SchemaError","title":"SchemaError","text":"

Bases: Exception

Raised when payload data violates the declared schema.

"},{"location":"dagpipe/#dagpipe.SchemaError--indicates-invalid-structure-invalid-path-or-invalid-type","title":"Indicates invalid structure, invalid path, or invalid type.","text":""},{"location":"dagpipe/#dagpipe.State","title":"State dataclass","text":"
State(\n    payload: Payload,\n    confidence: float = 1.0,\n    parent: State | None = None,\n    depth: int = 0,\n    history: tuple[str, ...] = tuple(),\n    metadata: dict[str, Any] = dict(),\n)\n

Immutable execution state propagated through dagpipe pipeline.

Attributes:

Name Type Description payloadPayload

Execution data container.

schemaClassVar[Schema]

Payload validation schema.

confidencefloat

Execution confidence score.

parentOptional[State]

Parent state reference.

depthint

Execution depth.

historyTuple[str, ...]

Ordered node execution lineage.

metadataDict[str, Any]

Execution metadata.

Notes

Responsibilities:

- Represents a complete execution snapshot at a specific point in\n  pipeline traversal.\n- Fundamental unit of execution in `dagpipe`.\n- Fully thread-safe due to immutability.\n
"},{"location":"dagpipe/#dagpipe.State-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.State.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Concise debug representation.

Avoids printing full data for large states.

"},{"location":"dagpipe/#dagpipe.State.fork","title":"fork","text":"
fork(\n    *,\n    payload_update: Mapping[str, Any] | None = None,\n    confidence_delta: float = 0.0,\n    node_id: str | None = None,\n    metadata_update: Mapping[str, Any] | None = None\n) -> State\n

Create a new child State derived from this state.

Parameters:

Name Type Description Default payload_updateMapping[str, Any]

Dot-path updates applied to the payload.

Noneconfidence_deltafloat

Adjustment applied to current confidence.

0.0node_idstr

Identifier of the node creating this state.

Nonemetadata_updateMapping[str, Any]

Updates merged into state metadata.

None

Returns:

Name Type Description StateState

A new immutable State instance.

Notes

Guarantees:

- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n
"},{"location":"dagpipe/#dagpipe.State.get","title":"get","text":"
get(key: str, default: Any = None) -> Any\n

Retrieve payload value.

Parameters:

Name Type Description Default keystr

Dot-path key.

required defaultAny

Fallback value.

None

Returns:

Name Type Description AnyAny

Stored value or default.

"},{"location":"dagpipe/#dagpipe.State.has","title":"has","text":"
has(key: str) -> bool\n

Check whether payload contains key.

Parameters:

Name Type Description Default keystr

Dot-path key.

required

Returns:

Name Type Description boolbool

Existence of the key.

"},{"location":"dagpipe/#dagpipe.State.lineage","title":"lineage","text":"
lineage() -> tuple[State, ...]\n

Return lineage from root to this State.

Returns:

Type Description tuple[State, ...]

Tuple[State, ...]: Ordered execution lineage (root first).

"},{"location":"dagpipe/#dagpipe.StepResult","title":"StepResult","text":"
StepResult(\n    index: int,\n    node_id: str,\n    states: tuple[State, ...],\n    completed: bool,\n)\n

A single checkpointed step within an async/resumable engine run.

Attributes:

Name Type Description indexint

Ordinal index of the step.

node_idstr

Identifier of the node associated with this step.

statesTuple[State, ...]

States produced by running this step.

completedbool

Whether this step succeeded (vs. paused/interrupted).

"},{"location":"dagpipe/#dagpipe-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.load_pipeline","title":"load_pipeline","text":"
load_pipeline(path: str) -> Pipeline\n

Load pipeline from YAML file.

Parameters:

Name Type Description Default pathstr

Path to YAML configuration file.

required

Returns:

Name Type Description PipelinePipeline

Executable pipeline instance.

Notes

Responsibilities:

- Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n
"},{"location":"dagpipe/engine/","title":"Engine","text":""},{"location":"dagpipe/engine/#dagpipe.engine","title":"dagpipe.engine","text":""},{"location":"dagpipe/engine/#dagpipe.engine--summary","title":"Summary","text":"

Execution engine responsible for running pipelines and graphs.

The Engine executes Node objects and propagates immutable State instances through either a linear sequence or a directed acyclic graph (Graph). It orchestrates execution order, branching, and state propagation.

"},{"location":"dagpipe/engine/#dagpipe.engine--guarantees","title":"Guarantees","text":"
  • Deterministic execution and consistent state lineage.
  • Orchestrates execution without modifying Graph, Node, or State objects.
"},{"location":"dagpipe/engine/#dagpipe.engine-classes","title":"Classes","text":""},{"location":"dagpipe/engine/#dagpipe.engine.Engine","title":"Engine","text":"
Engine(\n    nodes_or_graph: Sequence[Node] | Graph,\n    *,\n    on_step: StepHook | None = None\n)\n

Execution engine responsible for running pipeline logic.

Notes

Responsibilities:

- Accepts either a linear sequence of `Node` objects or a `Graph`\n  defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n  collects terminal states.\n- Supports synchronous (`run`) and asynchronous (`run_async`)\n  execution, dispatching per-node.\n- Supports step-wise / resumable execution and progress hooks.\n

Guarantees:

- Never mutates `State`, `Node`, or `Graph` instances.\n- `State` objects are never modified in place; each branch produces\n  independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
"},{"location":"dagpipe/engine/#dagpipe.engine.Engine-attributes","title":"Attributes","text":""},{"location":"dagpipe/engine/#dagpipe.engine.Engine.nodes","title":"nodes property","text":"
nodes: tuple[Node, ...]\n

Return nodes managed by this engine.

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.

"},{"location":"dagpipe/engine/#dagpipe.engine.Engine-functions","title":"Functions","text":""},{"location":"dagpipe/engine/#dagpipe.engine.Engine.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return the canonical string representation of the object.

Returns:

Name Type Description strstr

Representation that uniquely identifies the object and its configuration.

"},{"location":"dagpipe/engine/#dagpipe.engine.Engine.run","title":"run","text":"
run(root: State) -> list[State]\n

Execute the pipeline starting from a root State.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Raises:

Type Description TypeError

If root is not a State instance.

RuntimeError

If the engine execution mode is invalid.

Notes

Responsibilities:

- Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n
"},{"location":"dagpipe/engine/#dagpipe.engine.Engine.run_async","title":"run_async async","text":"
run_async(root: State) -> list[State]\n

Execute the pipeline starting from root, dispatching sync vs async nodes.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Notes

Each node is executed with Node.run when synchronous and AsyncNode.run_async when asynchronous. Linear and graph topologies are both supported.

"},{"location":"dagpipe/engine/#dagpipe.engine.Engine.run_steps","title":"run_steps","text":"
run_steps(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: StepHook | None = None\n) -> Iterator[StepResult]\n

Execute the pipeline step-by-step, yielding one StepResult per step.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint

Skip steps at index < resume_from (for resume-after-partial). Steps are 0-indexed.

Noneon_stepStepHook

Callback (step, status, message) invoked per step; falls back to the engine-level hook when unset.

None

Yields:

Name Type Description StepResultStepResult

One per executed node/step, carrying the produced states.

Notes

This is a synchronous, generator-based checkpoint interface compatible with the imperative resume-by-step behaviour of the legacy orchestrator. Use run_steps_async for async nodes.

"},{"location":"dagpipe/engine/#dagpipe.engine.Engine.run_steps_async","title":"run_steps_async async","text":"
run_steps_async(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: AsyncStepHook | None = None\n) -> AsyncIterator[StepResult]\n

Async variant of run_steps supporting AsyncNode execution.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint

Skip steps at index < resume_from.

Noneon_stepAsyncStepHook

Async callback (step, status, message) invoked per step.

None

Yields:

Name Type Description StepResultAsyncIterator[StepResult]

One per executed node/step.

"},{"location":"dagpipe/engine/#dagpipe.engine.ProgressMessage","title":"ProgressMessage","text":"
ProgressMessage(\n    *,\n    lines: int | None = None,\n    blocks: int | None = None,\n    count: int | None = None,\n    unit: str | None = None,\n    raw_ocr_line: str | None = None,\n    error: str | None = None,\n    step: str = \"\",\n    status: str = \"\"\n)\n

Lightweight progress payload emitted by engine step hooks.

Mirrors the imperative ProgressMessage used by the legacy orchestrator so callers can surface counts/lines/errors without coupling the engine to pydantic.

"},{"location":"dagpipe/engine/#dagpipe.engine.StepResult","title":"StepResult","text":"
StepResult(\n    index: int,\n    node_id: str,\n    states: tuple[State, ...],\n    completed: bool,\n)\n

A single checkpointed step within an async/resumable engine run.

Attributes:

Name Type Description indexint

Ordinal index of the step.

node_idstr

Identifier of the node associated with this step.

statesTuple[State, ...]

States produced by running this step.

completedbool

Whether this step succeeded (vs. paused/interrupted).

"},{"location":"dagpipe/graph/","title":"Graph","text":""},{"location":"dagpipe/graph/#dagpipe.graph","title":"dagpipe.graph","text":""},{"location":"dagpipe/graph/#dagpipe.graph--summary","title":"Summary","text":"

Defines DAG structure connecting nodes.

A Graph describes execution topology only. It does not execute nodes or manage State. Execution is handled by an Engine.

"},{"location":"dagpipe/graph/#dagpipe.graph--responsibilities","title":"Responsibilities","text":"
  • Multiple roots, branching, and merging support.
  • Deterministic traversal based on topology.
  • Graph is mutable during construction but treated as immutable at runtime.
"},{"location":"dagpipe/graph/#dagpipe.graph-classes","title":"Classes","text":""},{"location":"dagpipe/graph/#dagpipe.graph.Graph","title":"Graph","text":"
Graph()\n

Directed Acyclic Graph defining execution topology of Node objects.

Notes

Responsibilities:

- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n

Guarantees:

- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n

Create an empty Graph.

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"dagpipe/graph/#dagpipe.graph.Graph-functions","title":"Functions","text":""},{"location":"dagpipe/graph/#dagpipe.graph.Graph.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.__repr__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge","title":"add_edge","text":"
add_edge(src: Node, dst: Node) -> None\n

Add a directed edge from src to dst.

Parameters:

Name Type Description Default srcNode

Source node.

required dstNode

Destination node.

required

Raises:

Type Description TypeError

If src or dst is not a Node.

ValueError

If the edge would create a cycle or if src and dst are common.

Notes
  • Validates node types.
  • Prevents cycles.
  • Registers nodes if not present.
  • Updates parent and child mappings.
"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_root","title":"add_root","text":"
add_root(node: Node) -> None\n

Add a root node with no parents.

Parameters:

Name Type Description Default nodeNode

Node to add as a root.

required

Raises:

Type Description TypeError

If node is not a Node instance.

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.children","title":"children","text":"
children(node: Node) -> tuple[Node, ...]\n

Return child nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: Outgoing neighbors.

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.nodes","title":"nodes","text":"
nodes() -> tuple[Node, ...]\n

Return all nodes in the graph.

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: All registered nodes.

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.parents","title":"parents","text":"
parents(node: Node) -> tuple[Node, ...]\n

Return parent nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: Incoming neighbors.

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.roots","title":"roots","text":"
roots() -> tuple[Node, ...]\n

Return root nodes (nodes with no incoming edges).

Returns:

Type Description tuple[Node, ...]

Tuple[Node, ...]: Entry point nodes.

"},{"location":"dagpipe/node/","title":"Node","text":""},{"location":"dagpipe/node/#dagpipe.node","title":"dagpipe.node","text":""},{"location":"dagpipe/node/#dagpipe.node--summary","title":"Summary","text":"

Defines the Node abstraction used by dagpipe.

A node represents a single unit of pipeline execution logic. It consumes one State and produces zero, one, or many new State objects.

Nodes are connected using a Graph and executed by an Engine.

"},{"location":"dagpipe/node/#dagpipe.node--design-principles","title":"Design principles","text":"
  • Pure: Must not mutate input state.
  • Deterministic: Same input produces same output.
  • Stateless: Recommended to be stateless for reuse.
  • Composable: Nodes enable branching execution graphs.
"},{"location":"dagpipe/node/#dagpipe.node-classes","title":"Classes","text":""},{"location":"dagpipe/node/#dagpipe.node.AsyncNode","title":"AsyncNode","text":"

Bases: Node

Base class for nodes whose execution is asynchronous.

Subclasses implement resolve_async (an async generator yielding derived State objects). The engine dispatches to resolve_async when running an async traversal (see Engine.run_async).

Sync-only engines (and the base Node.run) treat an AsyncNode as a no-op consumer: calling run on an AsyncNode returns no states, signalling that an async engine is required.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode-functions","title":"Functions","text":""},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__hash__--returns","title":"Returns","text":"

int

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__repr__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__str__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateMapping[str, Any]

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateMapping[str, Any]

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.resolve_async","title":"resolve_async async","text":"
resolve_async(state: State) -> Iterable[State]\n

Execute node logic asynchronously.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description Iterable[State]

Iterable[State]: Derived execution state(s).

Notes

Subclasses implement this. Must not mutate the input state. Should use fork() to create child states.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.run_async","title":"run_async async","text":"
run_async(state: State) -> tuple[State, ...]\n

Execute this node asynchronously on a state, validating outputs.

"},{"location":"dagpipe/node/#dagpipe.node.Node","title":"Node","text":"

Bases: ABC

Base class for all dagpipe execution nodes.

Attributes:

Name Type Description idstr

Unique identifier of the node (snake_case dotted format).

namestr

Human-readable display name.

Notes

Responsibilities:

- Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one `State` and produces zero, one, or many derived states.\n- Defines execution logic and enables branching, filtering, and transformation.\n

Guarantees:

- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n
"},{"location":"dagpipe/node/#dagpipe.node.Node-functions","title":"Functions","text":""},{"location":"dagpipe/node/#dagpipe.node.Node.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"dagpipe/node/#dagpipe.node.Node.__hash__--returns","title":"Returns","text":"

int

"},{"location":"dagpipe/node/#dagpipe.node.Node.__new__","title":"__new__","text":"
__new__(*args: Any, **kwargs: Any) -> Node\n

Create or reuse a Node instance.

Stateless subclasses (no parameterized __init__) share one singleton instance per class \u2014 matching the original dagpipe behaviour underpinning set_registry-style configuration. Subclasses that declare an __init__ requiring instance-state arguments get a fresh instance per construction so pipeline builders can inject per-run dependencies.

"},{"location":"dagpipe/node/#dagpipe.node.Node.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"dagpipe/node/#dagpipe.node.Node.__repr__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/node/#dagpipe.node.Node.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"dagpipe/node/#dagpipe.node.Node.__str__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/node/#dagpipe.node.Node.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"dagpipe/node/#dagpipe.node.Node.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateMapping[str, Any]

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateMapping[str, Any]

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"dagpipe/node/#dagpipe.node.Node.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"dagpipe/node/#dagpipe.node.Node.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"dagpipe/node/#dagpipe.node.Node.resolve","title":"resolve abstractmethod","text":"
resolve(state: State) -> Iterable[State]\n

Execute node logic.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Yields:

Name Type Description StateIterable[State]

Derived execution state(s).

Notes

Responsibilities:

- Subclasses implement specific resolution behavior.\n- Must not mutate input state.\n- Should use `fork()` to create child states.\n- May yield zero states to terminate a branch.\n
"},{"location":"dagpipe/node/#dagpipe.node.Node.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"dagpipe/state/","title":"State","text":""},{"location":"dagpipe/state/#dagpipe.state","title":"dagpipe.state","text":""},{"location":"dagpipe/state/#dagpipe.state--summary","title":"Summary","text":"

Defines the core State object used by dagpipe.

The State represents a single point in pipeline execution. It contains arbitrary data and metadata and is designed to be immutable. Instead of modifying an existing state, nodes create new child states via fork().

"},{"location":"dagpipe/state/#dagpipe.state--design-principles","title":"Design principles","text":"
  • Immutability: States must never be modified after creation. All transformations must create a new state via fork().
  • Cheap cloning: Forking must be efficient since branching may create many states.
  • Lineage tracking: Each state maintains a reference to its parent and execution metadata for debugging and observability.
  • Domain agnostic: State contains generic key-value data and does not assume any schema.
  • Engine-friendly: State contains execution metadata such as depth and history.
"},{"location":"dagpipe/state/#dagpipe.state-classes","title":"Classes","text":""},{"location":"dagpipe/state/#dagpipe.state.Payload","title":"Payload dataclass","text":"
Payload(_data: Mapping[str, Any])\n

Immutable hierarchical container with dot-path access.

Attributes:

Name Type Description _dataMapping[str, Any]

Immutable hierarchical data structure.

Notes

Responsibilities:

- Stores execution data used by `State`.\n- Supports efficient atomic updates without modifying existing instances.\n- `Payload` instances are fully thread-safe due to immutability.\n
"},{"location":"dagpipe/state/#dagpipe.state.Payload-functions","title":"Functions","text":""},{"location":"dagpipe/state/#dagpipe.state.Payload.as_dict","title":"as_dict","text":"
as_dict() -> Mapping[str, Any]\n

Return underlying mapping.

Returns:

Type Description Mapping[str, Any]

Mapping[str, Any]: Read-only view of the underlying data.

"},{"location":"dagpipe/state/#dagpipe.state.Payload.get","title":"get","text":"
get(path: str, default: Any = None) -> Any\n

Retrieve value using dot-path.

Parameters:

Name Type Description Default pathstr

Dot-separated path to the value.

required defaultAny

Default value if path doesn't exist.

None

Returns:

Name Type Description AnyAny

The retrieved value or default.

"},{"location":"dagpipe/state/#dagpipe.state.Payload.has","title":"has","text":"
has(path: str) -> bool\n

Return True if path exists.

Parameters:

Name Type Description Default pathstr

Dot-separated path to check.

required

Returns:

Name Type Description boolbool

Existence of the path.

"},{"location":"dagpipe/state/#dagpipe.state.Payload.iter_paths","title":"iter_paths classmethod","text":"
iter_paths(\n    data: Mapping[str, Any], prefix: str = \"\"\n) -> Iterable[str]\n

Recursively yield dot-paths for all leaf nodes.

Parameters:

Name Type Description Default dataMapping[str, Any]

The mapping to iterate over.

required prefixstr

Current path prefix.

''

Returns:

Type Description Iterable[str]

Iterable[str]: Generator yielding dot-paths.

"},{"location":"dagpipe/state/#dagpipe.state.Payload.keys","title":"keys","text":"
keys() -> Iterable[str]\n

Return top-level keys.

Returns:

Type Description Iterable[str]

Iterable[str]: Iterator over top-level keys.

"},{"location":"dagpipe/state/#dagpipe.state.Payload.update","title":"update","text":"
update(updates: Mapping[str, Any]) -> Payload\n

Create a new Payload with dot-path updates applied.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path to value mapping.

required

Returns:

Name Type Description PayloadPayload

New immutable payload instance with updates.

Notes

Guarantees:

- Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n
"},{"location":"dagpipe/state/#dagpipe.state.Schema","title":"Schema dataclass","text":"
Schema(tree: Mapping[str, SchemaNode])\n

Immutable hierarchical schema defining allowed payload structure.

Attributes:

Name Type Description treeMapping[str, SchemaNode]

Hierarchical schema definition.

Notes

Responsibilities:

- Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n
"},{"location":"dagpipe/state/#dagpipe.state.Schema-functions","title":"Functions","text":""},{"location":"dagpipe/state/#dagpipe.state.Schema.validate_payload","title":"validate_payload","text":"
validate_payload(payload: Payload) -> None\n

Validate complete payload structure.

Parameters:

Name Type Description Default payloadPayload

Payload to validate.

required

Raises:

Type Description SchemaError

If payload violates schema.

"},{"location":"dagpipe/state/#dagpipe.state.Schema.validate_update","title":"validate_update","text":"
validate_update(updates: Mapping[str, Any]) -> None\n

Validate payload update paths.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path updates to validate.

required

Raises:

Type Description SchemaError

If any path is invalid according to the schema.

"},{"location":"dagpipe/state/#dagpipe.state.SchemaError","title":"SchemaError","text":"

Bases: Exception

Raised when payload data violates the declared schema.

"},{"location":"dagpipe/state/#dagpipe.state.SchemaError--indicates-invalid-structure-invalid-path-or-invalid-type","title":"Indicates invalid structure, invalid path, or invalid type.","text":""},{"location":"dagpipe/state/#dagpipe.state.State","title":"State dataclass","text":"
State(\n    payload: Payload,\n    confidence: float = 1.0,\n    parent: State | None = None,\n    depth: int = 0,\n    history: tuple[str, ...] = tuple(),\n    metadata: dict[str, Any] = dict(),\n)\n

Immutable execution state propagated through dagpipe pipeline.

Attributes:

Name Type Description payloadPayload

Execution data container.

schemaClassVar[Schema]

Payload validation schema.

confidencefloat

Execution confidence score.

parentOptional[State]

Parent state reference.

depthint

Execution depth.

historyTuple[str, ...]

Ordered node execution lineage.

metadataDict[str, Any]

Execution metadata.

Notes

Responsibilities:

- Represents a complete execution snapshot at a specific point in\n  pipeline traversal.\n- Fundamental unit of execution in `dagpipe`.\n- Fully thread-safe due to immutability.\n
"},{"location":"dagpipe/state/#dagpipe.state.State-functions","title":"Functions","text":""},{"location":"dagpipe/state/#dagpipe.state.State.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Concise debug representation.

Avoids printing full data for large states.

"},{"location":"dagpipe/state/#dagpipe.state.State.fork","title":"fork","text":"
fork(\n    *,\n    payload_update: Mapping[str, Any] | None = None,\n    confidence_delta: float = 0.0,\n    node_id: str | None = None,\n    metadata_update: Mapping[str, Any] | None = None\n) -> State\n

Create a new child State derived from this state.

Parameters:

Name Type Description Default payload_updateMapping[str, Any]

Dot-path updates applied to the payload.

Noneconfidence_deltafloat

Adjustment applied to current confidence.

0.0node_idstr

Identifier of the node creating this state.

Nonemetadata_updateMapping[str, Any]

Updates merged into state metadata.

None

Returns:

Name Type Description StateState

A new immutable State instance.

Notes

Guarantees:

- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n
"},{"location":"dagpipe/state/#dagpipe.state.State.get","title":"get","text":"
get(key: str, default: Any = None) -> Any\n

Retrieve payload value.

Parameters:

Name Type Description Default keystr

Dot-path key.

required defaultAny

Fallback value.

None

Returns:

Name Type Description AnyAny

Stored value or default.

"},{"location":"dagpipe/state/#dagpipe.state.State.has","title":"has","text":"
has(key: str) -> bool\n

Check whether payload contains key.

Parameters:

Name Type Description Default keystr

Dot-path key.

required

Returns:

Name Type Description boolbool

Existence of the key.

"},{"location":"dagpipe/state/#dagpipe.state.State.lineage","title":"lineage","text":"
lineage() -> tuple[State, ...]\n

Return lineage from root to this State.

Returns:

Type Description tuple[State, ...]

Tuple[State, ...]: Ordered execution lineage (root first).

"},{"location":"dagpipe/yaml_loader/","title":"Yaml Loader","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader","title":"dagpipe.yaml_loader","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader--summary","title":"Summary","text":"

Loads dagpipe pipelines from YAML configuration.

Creates fully configured pipeline objects from declarative YAML definitions, including Schema, State subclasses, Node instances, Graph topology, and initial payloads.

"},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader-classes","title":"Classes","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.Pipeline","title":"Pipeline dataclass","text":"
Pipeline(\n    engine: Engine,\n    state_cls: type[State],\n    initial_payload: Payload,\n)\n

Executable pipeline created from YAML configuration.

Attributes:

Name Type Description engineEngine

Execution engine responsible for running the pipeline.

state_clsType[State]

Dynamically created State subclass with configured schema.

initial_payloadPayload

Default payload used when execution begins.

Notes

Responsibilities:

- Encapsulates engine, state type, and initial payload.\n- Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying nodes are thread-safe.\n
"},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.Pipeline-functions","title":"Functions","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.Pipeline.run","title":"run","text":"
run(\n    payload_override: Mapping[str, Any] | None = None,\n) -> list[State]\n

Execute the pipeline.

Parameters:

Name Type Description Default payload_overrideMapping[str, Any]

Payload values overriding initial payload.

None

Returns:

Type Description list[State]

list[State]: Terminal execution states.

Notes

Responsibilities:

- Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n
"},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader-functions","title":"Functions","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.load_pipeline","title":"load_pipeline","text":"
load_pipeline(path: str) -> Pipeline\n

Load pipeline from YAML file.

Parameters:

Name Type Description Default pathstr

Path to YAML configuration file.

required

Returns:

Name Type Description PipelinePipeline

Executable pipeline instance.

Notes

Responsibilities:

- Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n
"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"dagpipe","text":"
  • Dagpipe
"},{"location":"#dagpipe","title":"dagpipe","text":""},{"location":"#dagpipe--summary","title":"Summary","text":"

Directed acyclic graph execution framework for deterministic state propagation.

dagpipe executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable State and optionally produces derived states for downstream nodes.

"},{"location":"#dagpipe--installation","title":"Installation","text":"

Install using pip:

pip install dagpipe\n
"},{"location":"#dagpipe--quick-start","title":"Quick Start","text":"
from dagpipe import State, Payload, Schema, Graph, Engine\nfrom dagpipe.node import Node\n\nclass HelloNode(Node):\n    id = \"hello\"\n    def resolve(self, state):\n        yield self.fork(state, payload_update={\"msg\": \"hello\"})\n\n# Build and run\ngraph = Graph()\ngraph.add_root(HelloNode())\nengine = Engine(graph)\n\nclass MyState(State):\n    schema = Schema({})\n\nresults = engine.run(MyState(payload=Payload({})))\n
"},{"location":"#dagpipe--public-api","title":"Public API","text":"

This package re-exports the core pipeline components. Consumers should import from this namespace for standard usage.

"},{"location":"#dagpipe--execution-core","title":"Execution Core","text":"
  • Engine: Responsible for orchestrating node execution and state propagation.
  • Graph: Defines the execution topology and node relationships.
  • Node: Base class for defining execution logic and transformations.
"},{"location":"#dagpipe--state-data","title":"State & Data","text":"
  • State: Represents an immutable execution snapshot at a point in time.
  • Payload: Immutable hierarchical container for execution data.
  • Schema: Defines and validates the allowed structure of payloads.
  • SchemaError: Raised when data violates the declared schema.
"},{"location":"#dagpipe--declarative-pipelines","title":"Declarative Pipelines","text":"
  • Pipeline: High-level wrapper for an engine, state type, and initial payload.
  • load_pipeline: Factory function to create a pipeline from YAML.
"},{"location":"#dagpipe-classes","title":"Classes","text":""},{"location":"#dagpipe.AsyncNode","title":"AsyncNode","text":"

Bases: Node

Base class for nodes whose execution is asynchronous.

Subclasses implement resolve_async (an async generator yielding derived State objects). The engine dispatches to resolve_async when running an async traversal (see Engine.run_async).

Sync-only engines (and the base Node.run) treat an AsyncNode as a no-op consumer: calling run on an AsyncNode returns no states, signalling that an async engine is required.

"},{"location":"#dagpipe.AsyncNode-functions","title":"Functions","text":""},{"location":"#dagpipe.AsyncNode.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"#dagpipe.AsyncNode.__hash__--returns","title":"Returns","text":"

int

"},{"location":"#dagpipe.AsyncNode.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"#dagpipe.AsyncNode.__repr__--returns","title":"Returns","text":"

str

"},{"location":"#dagpipe.AsyncNode.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"#dagpipe.AsyncNode.__str__--returns","title":"Returns","text":"

str

"},{"location":"#dagpipe.AsyncNode.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"#dagpipe.AsyncNode.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateAny

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateAny

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"#dagpipe.AsyncNode.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"#dagpipe.AsyncNode.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"#dagpipe.AsyncNode.resolve_async","title":"resolve_async async","text":"
resolve_async(state: State) -> Iterable[State]\n

Execute node logic asynchronously.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description Iterable[State]

Iterable[State]: Derived execution state(s).

Notes

Subclasses implement this. Must not mutate the input state. Should use fork() to create child states.

"},{"location":"#dagpipe.AsyncNode.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"#dagpipe.AsyncNode.run_async","title":"run_async async","text":"
run_async(state: State) -> tuple[State, ...]\n

Execute this node asynchronously on a state, validating outputs.

"},{"location":"#dagpipe.Engine","title":"Engine","text":"
Engine(\n    nodes_or_graph: Sequence[Node] | Graph,\n    *,\n    on_step: StepHook | None = None\n)\n

Execution engine responsible for running pipeline logic.

Notes

Responsibilities:

- Accepts either a linear sequence of `Node` objects or a `Graph`\n  defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n  collects terminal states.\n- Supports synchronous (`run`) and asynchronous (`run_async`)\n  execution, dispatching per-node.\n- Supports step-wise / resumable execution and progress hooks.\n

Guarantees:

- Never mutates `State`, `Node`, or `Graph` instances.\n- `State` objects are never modified in place; each branch produces\n  independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
"},{"location":"#dagpipe.Engine-attributes","title":"Attributes","text":""},{"location":"#dagpipe.Engine.nodes","title":"nodes property","text":"
nodes: tuple[Node, ...]\n

Return nodes managed by this engine.

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.

"},{"location":"#dagpipe.Engine-functions","title":"Functions","text":""},{"location":"#dagpipe.Engine.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return the canonical string representation of the object.

Returns:

Name Type Description strstr

Representation that uniquely identifies the object and its configuration.

"},{"location":"#dagpipe.Engine.run","title":"run","text":"
run(root: State) -> list[State]\n

Execute the pipeline starting from a root State.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Raises:

Type Description TypeError

If root is not a State instance.

RuntimeError

If the engine execution mode is invalid.

Notes

Responsibilities:

- Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n
"},{"location":"#dagpipe.Engine.run_async","title":"run_async async","text":"
run_async(root: State) -> list[State]\n

Execute the pipeline starting from root, dispatching sync vs async nodes.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Notes

Each node is executed with Node.run when synchronous and AsyncNode.run_async when asynchronous. Linear and graph topologies are both supported.

"},{"location":"#dagpipe.Engine.run_steps","title":"run_steps","text":"
run_steps(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: StepHook | None = None\n) -> Iterator[StepResult]\n

Execute the pipeline step-by-step, yielding one StepResult per step.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint | None

Skip steps at index < resume_from (for resume-after-partial). Steps are 0-indexed.

Noneon_stepStepHook | None

Callback (step, status, message) invoked per step; falls back to the engine-level hook when unset.

None

Yields:

Name Type Description StepResultStepResult

One per executed node/step, carrying the produced states.

Notes

This is a synchronous, generator-based checkpoint interface compatible with the imperative resume-by-step behaviour of the legacy orchestrator. Use run_steps_async for async nodes.

"},{"location":"#dagpipe.Engine.run_steps_async","title":"run_steps_async async","text":"
run_steps_async(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: AsyncStepHook | None = None\n) -> AsyncIterator[StepResult]\n

Async variant of run_steps supporting AsyncNode execution.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint | None

Skip steps at index < resume_from.

Noneon_stepAsyncStepHook | None

Async callback (step, status, message) invoked per step.

None

Yields:

Name Type Description StepResultAsyncIterator[StepResult]

One per executed node/step.

"},{"location":"#dagpipe.Graph","title":"Graph","text":"
Graph()\n

Directed Acyclic Graph defining execution topology of Node objects.

Notes

Responsibilities:

- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n

Guarantees:

- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n

Create an empty Graph.

"},{"location":"#dagpipe.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"#dagpipe.Graph-functions","title":"Functions","text":""},{"location":"#dagpipe.Graph.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"#dagpipe.Graph.__repr__--returns","title":"Returns","text":"

str

"},{"location":"#dagpipe.Graph.add_edge","title":"add_edge","text":"
add_edge(src: Node, dst: Node) -> None\n

Add a directed edge from src to dst.

Parameters:

Name Type Description Default srcNode

Source node.

required dstNode

Destination node.

required

Raises:

Type Description TypeError

If src or dst is not a Node.

ValueError

If the edge would create a cycle or if src and dst are common.

Notes
  • Validates node types.
  • Prevents cycles.
  • Registers nodes if not present.
  • Updates parent and child mappings.
"},{"location":"#dagpipe.Graph.add_root","title":"add_root","text":"
add_root(node: Node) -> None\n

Add a root node with no parents.

Parameters:

Name Type Description Default nodeNode

Node to add as a root.

required

Raises:

Type Description TypeError

If node is not a Node instance.

"},{"location":"#dagpipe.Graph.children","title":"children","text":"
children(node: Node) -> tuple[Node, ...]\n

Return child nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Outgoing neighbors.

"},{"location":"#dagpipe.Graph.nodes","title":"nodes","text":"
nodes() -> tuple[Node, ...]\n

Return all nodes in the graph.

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: All registered nodes.

"},{"location":"#dagpipe.Graph.parents","title":"parents","text":"
parents(node: Node) -> tuple[Node, ...]\n

Return parent nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Incoming neighbors.

"},{"location":"#dagpipe.Graph.roots","title":"roots","text":"
roots() -> tuple[Node, ...]\n

Return root nodes (nodes with no incoming edges).

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Entry point nodes.

"},{"location":"#dagpipe.Node","title":"Node","text":"

Bases: ABC

Base class for all dagpipe execution nodes.

Attributes:

Name Type Description idstr

Unique identifier of the node (snake_case dotted format).

namestr

Human-readable display name.

Notes

Responsibilities:

- Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one `State` and produces zero, one, or many derived states.\n- Defines execution logic and enables branching, filtering, and transformation.\n

Guarantees:

- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n
"},{"location":"#dagpipe.Node-functions","title":"Functions","text":""},{"location":"#dagpipe.Node.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"#dagpipe.Node.__hash__--returns","title":"Returns","text":"

int

"},{"location":"#dagpipe.Node.__new__","title":"__new__","text":"
__new__(*args: Any, **kwargs: Any) -> Node\n

Create or reuse a Node instance.

Stateless subclasses (no parameterized __init__) share one singleton instance per class \u2014 matching the original dagpipe behaviour underpinning set_registry-style configuration. Subclasses that declare an __init__ requiring instance-state arguments get a fresh instance per construction so pipeline builders can inject per-run dependencies.

"},{"location":"#dagpipe.Node.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"#dagpipe.Node.__repr__--returns","title":"Returns","text":"

str

"},{"location":"#dagpipe.Node.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"#dagpipe.Node.__str__--returns","title":"Returns","text":"

str

"},{"location":"#dagpipe.Node.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"#dagpipe.Node.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateAny

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateAny

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"#dagpipe.Node.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"#dagpipe.Node.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"#dagpipe.Node.resolve","title":"resolve abstractmethod","text":"
resolve(state: State) -> Iterable[State]\n

Execute node logic.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description Iterable[State]

Iterable[State]: Derived execution state(s).

Notes

Responsibilities:

- Subclasses implement specific resolution behavior.\n- Must not mutate input state.\n- Should use `fork()` to create child states.\n- May yield zero states to terminate a branch.\n
"},{"location":"#dagpipe.Node.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"#dagpipe.Payload","title":"Payload dataclass","text":"
Payload(_data: Mapping[str, Any])\n

Immutable hierarchical container with dot-path access.

Attributes:

Name Type Description _dataMapping[str, Any]

Immutable hierarchical data structure.

Notes

Responsibilities:

- Stores execution data used by `State`.\n- Supports efficient atomic updates without modifying existing instances.\n- `Payload` instances are fully thread-safe due to immutability.\n
"},{"location":"#dagpipe.Payload-functions","title":"Functions","text":""},{"location":"#dagpipe.Payload.as_dict","title":"as_dict","text":"
as_dict() -> Mapping[str, Any]\n

Return underlying mapping.

Returns:

Type Description Mapping[str, Any]

Mapping[str, Any]: Read-only view of the underlying data.

"},{"location":"#dagpipe.Payload.get","title":"get","text":"
get(path: str, default: Any = None) -> Any\n

Retrieve value using dot-path.

Parameters:

Name Type Description Default pathstr

Dot-separated path to the value.

required defaultAny

Default value if path doesn't exist.

None

Returns:

Name Type Description AnyAny

The retrieved value or default.

"},{"location":"#dagpipe.Payload.has","title":"has","text":"
has(path: str) -> bool\n

Return True if path exists.

Parameters:

Name Type Description Default pathstr

Dot-separated path to check.

required

Returns:

Name Type Description boolbool

Existence of the path.

"},{"location":"#dagpipe.Payload.iter_paths","title":"iter_paths classmethod","text":"
iter_paths(\n    data: Mapping[str, Any], prefix: str = \"\"\n) -> Iterable[str]\n

Recursively yield dot-paths for all leaf nodes.

Parameters:

Name Type Description Default dataMapping[str, Any]

The mapping to iterate over.

required prefixstr

Current path prefix.

''

Yields:

Name Type Description strIterable[str]

Dot-path for each leaf node.

"},{"location":"#dagpipe.Payload.keys","title":"keys","text":"
keys() -> Iterable[str]\n

Return top-level keys.

Returns:

Type Description Iterable[str]

Iterable[str]: Iterator over top-level keys.

"},{"location":"#dagpipe.Payload.update","title":"update","text":"
update(updates: Mapping[str, Any]) -> Payload\n

Create a new Payload with dot-path updates applied.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path to value mapping.

required

Returns:

Name Type Description PayloadPayload

New immutable payload instance with updates.

Notes

Guarantees:

- Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n
"},{"location":"#dagpipe.Pipeline","title":"Pipeline dataclass","text":"
Pipeline(\n    engine: Engine,\n    state_cls: type[State],\n    initial_payload: Payload,\n)\n

Executable pipeline created from YAML configuration.

Attributes:

Name Type Description engineEngine

Execution engine responsible for running the pipeline.

state_clsType[State]

Dynamically created State subclass with configured schema.

initial_payloadPayload

Default payload used when execution begins.

Notes

Responsibilities:

- Encapsulates engine, state type, and initial payload.\n- Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying nodes are thread-safe.\n
"},{"location":"#dagpipe.Pipeline-functions","title":"Functions","text":""},{"location":"#dagpipe.Pipeline.run","title":"run","text":"
run(\n    payload_override: Mapping[str, Any] | None = None,\n) -> list[State]\n

Execute the pipeline.

Parameters:

Name Type Description Default payload_overrideMapping[str, Any] | None

Payload values overriding initial payload.

None

Returns:

Type Description list[State]

list[State]: Terminal execution states.

Notes

Responsibilities:

- Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n
"},{"location":"#dagpipe.ProgressMessage","title":"ProgressMessage","text":"
ProgressMessage(\n    *,\n    lines: int | None = None,\n    blocks: int | None = None,\n    count: int | None = None,\n    unit: str | None = None,\n    raw_ocr_line: str | None = None,\n    error: str | None = None,\n    step: str = \"\",\n    status: str = \"\"\n)\n

Lightweight progress payload emitted by engine step hooks.

Mirrors the imperative ProgressMessage used by the legacy orchestrator so callers can surface counts/lines/errors without coupling the engine to pydantic.

"},{"location":"#dagpipe.Schema","title":"Schema dataclass","text":"
Schema(tree: Mapping[str, SchemaNode])\n

Immutable hierarchical schema defining allowed payload structure.

Attributes:

Name Type Description treeMapping[str, SchemaNode]

Hierarchical schema definition.

Notes

Responsibilities:

- Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n
"},{"location":"#dagpipe.Schema-functions","title":"Functions","text":""},{"location":"#dagpipe.Schema.validate_payload","title":"validate_payload","text":"
validate_payload(payload: Payload) -> None\n

Validate complete payload structure.

Parameters:

Name Type Description Default payloadPayload

Payload to validate.

required

Raises:

Type Description SchemaError

If payload violates schema.

"},{"location":"#dagpipe.Schema.validate_update","title":"validate_update","text":"
validate_update(updates: Mapping[str, Any]) -> None\n

Validate payload update paths.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path updates to validate.

required

Raises:

Type Description SchemaError

If any path is invalid according to the schema.

"},{"location":"#dagpipe.SchemaError","title":"SchemaError","text":"

Bases: Exception

Raised when payload data violates the declared schema.

"},{"location":"#dagpipe.SchemaError--indicates-invalid-structure-invalid-path-or-invalid-type","title":"Indicates invalid structure, invalid path, or invalid type.","text":""},{"location":"#dagpipe.State","title":"State dataclass","text":"
State(\n    payload: Payload,\n    confidence: float = 1.0,\n    parent: State | None = None,\n    depth: int = 0,\n    history: tuple[str, ...] = tuple(),\n    metadata: dict[str, Any] = dict(),\n)\n

Immutable execution state propagated through dagpipe pipeline.

Attributes:

Name Type Description payloadPayload

Execution data container.

schemaClassVar[Schema]

Payload validation schema.

confidencefloat

Execution confidence score.

parentOptional[State]

Parent state reference.

depthint

Execution depth.

historyTuple[str, ...]

Ordered node execution lineage.

metadataDict[str, Any]

Execution metadata.

Notes

Responsibilities:

- Represents a complete execution snapshot at a specific point in\n  pipeline traversal.\n- Fundamental unit of execution in `dagpipe`.\n- Fully thread-safe due to immutability.\n
"},{"location":"#dagpipe.State-functions","title":"Functions","text":""},{"location":"#dagpipe.State.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Concise debug representation.

Avoids printing full data for large states.

"},{"location":"#dagpipe.State.fork","title":"fork","text":"
fork(\n    *,\n    payload_update: Mapping[str, Any] | None = None,\n    confidence_delta: float = 0.0,\n    node_id: str | None = None,\n    metadata_update: Mapping[str, Any] | None = None\n) -> State\n

Create a new child State derived from this state.

Parameters:

Name Type Description Default payload_updateMapping[str, Any] | None

Dot-path updates applied to the payload.

Noneconfidence_deltafloat

Adjustment applied to current confidence.

0.0node_idstr | None

Identifier of the node creating this state.

Nonemetadata_updateMapping[str, Any] | None

Updates merged into state metadata.

None

Returns:

Name Type Description StateState

A new immutable State instance.

Notes

Guarantees:

- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n
"},{"location":"#dagpipe.State.get","title":"get","text":"
get(key: str, default: Any = None) -> Any\n

Retrieve payload value.

Parameters:

Name Type Description Default keystr

Dot-path key.

required defaultAny

Fallback value.

None

Returns:

Name Type Description AnyAny

Stored value or default.

"},{"location":"#dagpipe.State.has","title":"has","text":"
has(key: str) -> bool\n

Check whether payload contains key.

Parameters:

Name Type Description Default keystr

Dot-path key.

required

Returns:

Name Type Description boolbool

Existence of the key.

"},{"location":"#dagpipe.State.lineage","title":"lineage","text":"
lineage() -> tuple[State, ...]\n

Return lineage from root to this State.

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Ordered execution lineage (root first).

"},{"location":"#dagpipe.StepResult","title":"StepResult","text":"
StepResult(\n    index: int,\n    node_id: str,\n    states: tuple[State, ...],\n    completed: bool,\n)\n

A single checkpointed step within an async/resumable engine run.

Attributes:

Name Type Description indexint

Ordinal index of the step.

node_idstr

Identifier of the node associated with this step.

statestuple[State, ...]

States produced by running this step.

completedbool

Whether this step succeeded (vs. paused/interrupted).

Initialise StepResult.

Parameters:

Name Type Description Default indexint

Ordinal index of the step.

required node_idstr

Identifier of the node associated with this step.

required statestuple[State, ...]

States produced by running this step.

required completedbool

Whether this step succeeded (vs. paused/interrupted).

required"},{"location":"#dagpipe.StepResult-functions","title":"Functions","text":""},{"location":"#dagpipe-functions","title":"Functions","text":""},{"location":"#dagpipe.load_pipeline","title":"load_pipeline","text":"
load_pipeline(path: str) -> Pipeline\n

Load pipeline from YAML file.

Parameters:

Name Type Description Default pathstr

Path to YAML configuration file.

required

Returns:

Name Type Description PipelinePipeline

Executable pipeline instance.

Notes

Responsibilities:

- Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n
"},{"location":"engine/","title":"Engine","text":""},{"location":"engine/#dagpipe.engine","title":"dagpipe.engine","text":""},{"location":"engine/#dagpipe.engine--summary","title":"Summary","text":"

Execution engine responsible for running pipelines and graphs.

The Engine executes Node objects and propagates immutable State instances through either a linear sequence or a directed acyclic graph (Graph). It orchestrates execution order, branching, and state propagation.

"},{"location":"engine/#dagpipe.engine--guarantees","title":"Guarantees","text":"
  • Deterministic execution and consistent state lineage.
  • Orchestrates execution without modifying Graph, Node, or State objects.
"},{"location":"engine/#dagpipe.engine-classes","title":"Classes","text":""},{"location":"engine/#dagpipe.engine.Engine","title":"Engine","text":"
Engine(\n    nodes_or_graph: Sequence[Node] | Graph,\n    *,\n    on_step: StepHook | None = None\n)\n

Execution engine responsible for running pipeline logic.

Notes

Responsibilities:

- Accepts either a linear sequence of `Node` objects or a `Graph`\n  defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n  collects terminal states.\n- Supports synchronous (`run`) and asynchronous (`run_async`)\n  execution, dispatching per-node.\n- Supports step-wise / resumable execution and progress hooks.\n

Guarantees:

- Never mutates `State`, `Node`, or `Graph` instances.\n- `State` objects are never modified in place; each branch produces\n  independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
"},{"location":"engine/#dagpipe.engine.Engine-attributes","title":"Attributes","text":""},{"location":"engine/#dagpipe.engine.Engine.nodes","title":"nodes property","text":"
nodes: tuple[Node, ...]\n

Return nodes managed by this engine.

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.

"},{"location":"engine/#dagpipe.engine.Engine-functions","title":"Functions","text":""},{"location":"engine/#dagpipe.engine.Engine.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return the canonical string representation of the object.

Returns:

Name Type Description strstr

Representation that uniquely identifies the object and its configuration.

"},{"location":"engine/#dagpipe.engine.Engine.run","title":"run","text":"
run(root: State) -> list[State]\n

Execute the pipeline starting from a root State.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Raises:

Type Description TypeError

If root is not a State instance.

RuntimeError

If the engine execution mode is invalid.

Notes

Responsibilities:

- Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n
"},{"location":"engine/#dagpipe.engine.Engine.run_async","title":"run_async async","text":"
run_async(root: State) -> list[State]\n

Execute the pipeline starting from root, dispatching sync vs async nodes.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Notes

Each node is executed with Node.run when synchronous and AsyncNode.run_async when asynchronous. Linear and graph topologies are both supported.

"},{"location":"engine/#dagpipe.engine.Engine.run_steps","title":"run_steps","text":"
run_steps(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: StepHook | None = None\n) -> Iterator[StepResult]\n

Execute the pipeline step-by-step, yielding one StepResult per step.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint | None

Skip steps at index < resume_from (for resume-after-partial). Steps are 0-indexed.

Noneon_stepStepHook | None

Callback (step, status, message) invoked per step; falls back to the engine-level hook when unset.

None

Yields:

Name Type Description StepResultStepResult

One per executed node/step, carrying the produced states.

Notes

This is a synchronous, generator-based checkpoint interface compatible with the imperative resume-by-step behaviour of the legacy orchestrator. Use run_steps_async for async nodes.

"},{"location":"engine/#dagpipe.engine.Engine.run_steps_async","title":"run_steps_async async","text":"
run_steps_async(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: AsyncStepHook | None = None\n) -> AsyncIterator[StepResult]\n

Async variant of run_steps supporting AsyncNode execution.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint | None

Skip steps at index < resume_from.

Noneon_stepAsyncStepHook | None

Async callback (step, status, message) invoked per step.

None

Yields:

Name Type Description StepResultAsyncIterator[StepResult]

One per executed node/step.

"},{"location":"engine/#dagpipe.engine.ProgressMessage","title":"ProgressMessage","text":"
ProgressMessage(\n    *,\n    lines: int | None = None,\n    blocks: int | None = None,\n    count: int | None = None,\n    unit: str | None = None,\n    raw_ocr_line: str | None = None,\n    error: str | None = None,\n    step: str = \"\",\n    status: str = \"\"\n)\n

Lightweight progress payload emitted by engine step hooks.

Mirrors the imperative ProgressMessage used by the legacy orchestrator so callers can surface counts/lines/errors without coupling the engine to pydantic.

"},{"location":"engine/#dagpipe.engine.StepResult","title":"StepResult","text":"
StepResult(\n    index: int,\n    node_id: str,\n    states: tuple[State, ...],\n    completed: bool,\n)\n

A single checkpointed step within an async/resumable engine run.

Attributes:

Name Type Description indexint

Ordinal index of the step.

node_idstr

Identifier of the node associated with this step.

statestuple[State, ...]

States produced by running this step.

completedbool

Whether this step succeeded (vs. paused/interrupted).

Initialise StepResult.

Parameters:

Name Type Description Default indexint

Ordinal index of the step.

required node_idstr

Identifier of the node associated with this step.

required statestuple[State, ...]

States produced by running this step.

required completedbool

Whether this step succeeded (vs. paused/interrupted).

required"},{"location":"engine/#dagpipe.engine.StepResult-functions","title":"Functions","text":""},{"location":"graph/","title":"Graph","text":""},{"location":"graph/#dagpipe.graph","title":"dagpipe.graph","text":""},{"location":"graph/#dagpipe.graph--summary","title":"Summary","text":"

Defines DAG structure connecting nodes.

A Graph describes execution topology only. It does not execute nodes or manage State. Execution is handled by an Engine.

"},{"location":"graph/#dagpipe.graph--responsibilities","title":"Responsibilities","text":"
  • Multiple roots, branching, and merging support.
  • Deterministic traversal based on topology.
  • Graph is mutable during construction but treated as immutable at runtime.
"},{"location":"graph/#dagpipe.graph-classes","title":"Classes","text":""},{"location":"graph/#dagpipe.graph.Graph","title":"Graph","text":"
Graph()\n

Directed Acyclic Graph defining execution topology of Node objects.

Notes

Responsibilities:

- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n

Guarantees:

- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n

Create an empty Graph.

"},{"location":"graph/#dagpipe.graph.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"graph/#dagpipe.graph.Graph-functions","title":"Functions","text":""},{"location":"graph/#dagpipe.graph.Graph.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"graph/#dagpipe.graph.Graph.__repr__--returns","title":"Returns","text":"

str

"},{"location":"graph/#dagpipe.graph.Graph.add_edge","title":"add_edge","text":"
add_edge(src: Node, dst: Node) -> None\n

Add a directed edge from src to dst.

Parameters:

Name Type Description Default srcNode

Source node.

required dstNode

Destination node.

required

Raises:

Type Description TypeError

If src or dst is not a Node.

ValueError

If the edge would create a cycle or if src and dst are common.

Notes
  • Validates node types.
  • Prevents cycles.
  • Registers nodes if not present.
  • Updates parent and child mappings.
"},{"location":"graph/#dagpipe.graph.Graph.add_root","title":"add_root","text":"
add_root(node: Node) -> None\n

Add a root node with no parents.

Parameters:

Name Type Description Default nodeNode

Node to add as a root.

required

Raises:

Type Description TypeError

If node is not a Node instance.

"},{"location":"graph/#dagpipe.graph.Graph.children","title":"children","text":"
children(node: Node) -> tuple[Node, ...]\n

Return child nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Outgoing neighbors.

"},{"location":"graph/#dagpipe.graph.Graph.nodes","title":"nodes","text":"
nodes() -> tuple[Node, ...]\n

Return all nodes in the graph.

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: All registered nodes.

"},{"location":"graph/#dagpipe.graph.Graph.parents","title":"parents","text":"
parents(node: Node) -> tuple[Node, ...]\n

Return parent nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Incoming neighbors.

"},{"location":"graph/#dagpipe.graph.Graph.roots","title":"roots","text":"
roots() -> tuple[Node, ...]\n

Return root nodes (nodes with no incoming edges).

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Entry point nodes.

"},{"location":"node/","title":"Node","text":""},{"location":"node/#dagpipe.node","title":"dagpipe.node","text":""},{"location":"node/#dagpipe.node--summary","title":"Summary","text":"

Defines the Node abstraction used by dagpipe.

A node represents a single unit of pipeline execution logic. It consumes one State and produces zero, one, or many new State objects.

Nodes are connected using a Graph and executed by an Engine.

"},{"location":"node/#dagpipe.node--design-principles","title":"Design principles","text":"
  • Pure: Must not mutate input state.
  • Deterministic: Same input produces same output.
  • Stateless: Recommended to be stateless for reuse.
  • Composable: Nodes enable branching execution graphs.
"},{"location":"node/#dagpipe.node-classes","title":"Classes","text":""},{"location":"node/#dagpipe.node.AsyncNode","title":"AsyncNode","text":"

Bases: Node

Base class for nodes whose execution is asynchronous.

Subclasses implement resolve_async (an async generator yielding derived State objects). The engine dispatches to resolve_async when running an async traversal (see Engine.run_async).

Sync-only engines (and the base Node.run) treat an AsyncNode as a no-op consumer: calling run on an AsyncNode returns no states, signalling that an async engine is required.

"},{"location":"node/#dagpipe.node.AsyncNode-functions","title":"Functions","text":""},{"location":"node/#dagpipe.node.AsyncNode.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"node/#dagpipe.node.AsyncNode.__hash__--returns","title":"Returns","text":"

int

"},{"location":"node/#dagpipe.node.AsyncNode.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"node/#dagpipe.node.AsyncNode.__repr__--returns","title":"Returns","text":"

str

"},{"location":"node/#dagpipe.node.AsyncNode.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"node/#dagpipe.node.AsyncNode.__str__--returns","title":"Returns","text":"

str

"},{"location":"node/#dagpipe.node.AsyncNode.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"node/#dagpipe.node.AsyncNode.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateAny

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateAny

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"node/#dagpipe.node.AsyncNode.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"node/#dagpipe.node.AsyncNode.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"node/#dagpipe.node.AsyncNode.resolve_async","title":"resolve_async async","text":"
resolve_async(state: State) -> Iterable[State]\n

Execute node logic asynchronously.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description Iterable[State]

Iterable[State]: Derived execution state(s).

Notes

Subclasses implement this. Must not mutate the input state. Should use fork() to create child states.

"},{"location":"node/#dagpipe.node.AsyncNode.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"node/#dagpipe.node.AsyncNode.run_async","title":"run_async async","text":"
run_async(state: State) -> tuple[State, ...]\n

Execute this node asynchronously on a state, validating outputs.

"},{"location":"node/#dagpipe.node.Node","title":"Node","text":"

Bases: ABC

Base class for all dagpipe execution nodes.

Attributes:

Name Type Description idstr

Unique identifier of the node (snake_case dotted format).

namestr

Human-readable display name.

Notes

Responsibilities:

- Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one `State` and produces zero, one, or many derived states.\n- Defines execution logic and enables branching, filtering, and transformation.\n

Guarantees:

- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n
"},{"location":"node/#dagpipe.node.Node-functions","title":"Functions","text":""},{"location":"node/#dagpipe.node.Node.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"node/#dagpipe.node.Node.__hash__--returns","title":"Returns","text":"

int

"},{"location":"node/#dagpipe.node.Node.__new__","title":"__new__","text":"
__new__(*args: Any, **kwargs: Any) -> Node\n

Create or reuse a Node instance.

Stateless subclasses (no parameterized __init__) share one singleton instance per class \u2014 matching the original dagpipe behaviour underpinning set_registry-style configuration. Subclasses that declare an __init__ requiring instance-state arguments get a fresh instance per construction so pipeline builders can inject per-run dependencies.

"},{"location":"node/#dagpipe.node.Node.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"node/#dagpipe.node.Node.__repr__--returns","title":"Returns","text":"

str

"},{"location":"node/#dagpipe.node.Node.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"node/#dagpipe.node.Node.__str__--returns","title":"Returns","text":"

str

"},{"location":"node/#dagpipe.node.Node.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"node/#dagpipe.node.Node.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateAny

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateAny

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"node/#dagpipe.node.Node.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"node/#dagpipe.node.Node.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"node/#dagpipe.node.Node.resolve","title":"resolve abstractmethod","text":"
resolve(state: State) -> Iterable[State]\n

Execute node logic.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description Iterable[State]

Iterable[State]: Derived execution state(s).

Notes

Responsibilities:

- Subclasses implement specific resolution behavior.\n- Must not mutate input state.\n- Should use `fork()` to create child states.\n- May yield zero states to terminate a branch.\n
"},{"location":"node/#dagpipe.node.Node.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"state/","title":"State","text":""},{"location":"state/#dagpipe.state","title":"dagpipe.state","text":""},{"location":"state/#dagpipe.state--summary","title":"Summary","text":"

Defines the core State object used by dagpipe.

The State represents a single point in pipeline execution. It contains arbitrary data and metadata and is designed to be immutable. Instead of modifying an existing state, nodes create new child states via fork().

"},{"location":"state/#dagpipe.state--design-principles","title":"Design principles","text":"
  • Immutability: States must never be modified after creation. All transformations must create a new state via fork().
  • Cheap cloning: Forking must be efficient since branching may create many states.
  • Lineage tracking: Each state maintains a reference to its parent and execution metadata for debugging and observability.
  • Domain agnostic: State contains generic key-value data and does not assume any schema.
  • Engine-friendly: State contains execution metadata such as depth and history.
"},{"location":"state/#dagpipe.state-classes","title":"Classes","text":""},{"location":"state/#dagpipe.state.Payload","title":"Payload dataclass","text":"
Payload(_data: Mapping[str, Any])\n

Immutable hierarchical container with dot-path access.

Attributes:

Name Type Description _dataMapping[str, Any]

Immutable hierarchical data structure.

Notes

Responsibilities:

- Stores execution data used by `State`.\n- Supports efficient atomic updates without modifying existing instances.\n- `Payload` instances are fully thread-safe due to immutability.\n
"},{"location":"state/#dagpipe.state.Payload-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.Payload.as_dict","title":"as_dict","text":"
as_dict() -> Mapping[str, Any]\n

Return underlying mapping.

Returns:

Type Description Mapping[str, Any]

Mapping[str, Any]: Read-only view of the underlying data.

"},{"location":"state/#dagpipe.state.Payload.get","title":"get","text":"
get(path: str, default: Any = None) -> Any\n

Retrieve value using dot-path.

Parameters:

Name Type Description Default pathstr

Dot-separated path to the value.

required defaultAny

Default value if path doesn't exist.

None

Returns:

Name Type Description AnyAny

The retrieved value or default.

"},{"location":"state/#dagpipe.state.Payload.has","title":"has","text":"
has(path: str) -> bool\n

Return True if path exists.

Parameters:

Name Type Description Default pathstr

Dot-separated path to check.

required

Returns:

Name Type Description boolbool

Existence of the path.

"},{"location":"state/#dagpipe.state.Payload.iter_paths","title":"iter_paths classmethod","text":"
iter_paths(\n    data: Mapping[str, Any], prefix: str = \"\"\n) -> Iterable[str]\n

Recursively yield dot-paths for all leaf nodes.

Parameters:

Name Type Description Default dataMapping[str, Any]

The mapping to iterate over.

required prefixstr

Current path prefix.

''

Yields:

Name Type Description strIterable[str]

Dot-path for each leaf node.

"},{"location":"state/#dagpipe.state.Payload.keys","title":"keys","text":"
keys() -> Iterable[str]\n

Return top-level keys.

Returns:

Type Description Iterable[str]

Iterable[str]: Iterator over top-level keys.

"},{"location":"state/#dagpipe.state.Payload.update","title":"update","text":"
update(updates: Mapping[str, Any]) -> Payload\n

Create a new Payload with dot-path updates applied.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path to value mapping.

required

Returns:

Name Type Description PayloadPayload

New immutable payload instance with updates.

Notes

Guarantees:

- Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n
"},{"location":"state/#dagpipe.state.Schema","title":"Schema dataclass","text":"
Schema(tree: Mapping[str, SchemaNode])\n

Immutable hierarchical schema defining allowed payload structure.

Attributes:

Name Type Description treeMapping[str, SchemaNode]

Hierarchical schema definition.

Notes

Responsibilities:

- Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n
"},{"location":"state/#dagpipe.state.Schema-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.Schema.validate_payload","title":"validate_payload","text":"
validate_payload(payload: Payload) -> None\n

Validate complete payload structure.

Parameters:

Name Type Description Default payloadPayload

Payload to validate.

required

Raises:

Type Description SchemaError

If payload violates schema.

"},{"location":"state/#dagpipe.state.Schema.validate_update","title":"validate_update","text":"
validate_update(updates: Mapping[str, Any]) -> None\n

Validate payload update paths.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path updates to validate.

required

Raises:

Type Description SchemaError

If any path is invalid according to the schema.

"},{"location":"state/#dagpipe.state.SchemaError","title":"SchemaError","text":"

Bases: Exception

Raised when payload data violates the declared schema.

"},{"location":"state/#dagpipe.state.SchemaError--indicates-invalid-structure-invalid-path-or-invalid-type","title":"Indicates invalid structure, invalid path, or invalid type.","text":""},{"location":"state/#dagpipe.state.State","title":"State dataclass","text":"
State(\n    payload: Payload,\n    confidence: float = 1.0,\n    parent: State | None = None,\n    depth: int = 0,\n    history: tuple[str, ...] = tuple(),\n    metadata: dict[str, Any] = dict(),\n)\n

Immutable execution state propagated through dagpipe pipeline.

Attributes:

Name Type Description payloadPayload

Execution data container.

schemaClassVar[Schema]

Payload validation schema.

confidencefloat

Execution confidence score.

parentOptional[State]

Parent state reference.

depthint

Execution depth.

historyTuple[str, ...]

Ordered node execution lineage.

metadataDict[str, Any]

Execution metadata.

Notes

Responsibilities:

- Represents a complete execution snapshot at a specific point in\n  pipeline traversal.\n- Fundamental unit of execution in `dagpipe`.\n- Fully thread-safe due to immutability.\n
"},{"location":"state/#dagpipe.state.State-functions","title":"Functions","text":""},{"location":"state/#dagpipe.state.State.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Concise debug representation.

Avoids printing full data for large states.

"},{"location":"state/#dagpipe.state.State.fork","title":"fork","text":"
fork(\n    *,\n    payload_update: Mapping[str, Any] | None = None,\n    confidence_delta: float = 0.0,\n    node_id: str | None = None,\n    metadata_update: Mapping[str, Any] | None = None\n) -> State\n

Create a new child State derived from this state.

Parameters:

Name Type Description Default payload_updateMapping[str, Any] | None

Dot-path updates applied to the payload.

Noneconfidence_deltafloat

Adjustment applied to current confidence.

0.0node_idstr | None

Identifier of the node creating this state.

Nonemetadata_updateMapping[str, Any] | None

Updates merged into state metadata.

None

Returns:

Name Type Description StateState

A new immutable State instance.

Notes

Guarantees:

- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n
"},{"location":"state/#dagpipe.state.State.get","title":"get","text":"
get(key: str, default: Any = None) -> Any\n

Retrieve payload value.

Parameters:

Name Type Description Default keystr

Dot-path key.

required defaultAny

Fallback value.

None

Returns:

Name Type Description AnyAny

Stored value or default.

"},{"location":"state/#dagpipe.state.State.has","title":"has","text":"
has(key: str) -> bool\n

Check whether payload contains key.

Parameters:

Name Type Description Default keystr

Dot-path key.

required

Returns:

Name Type Description boolbool

Existence of the key.

"},{"location":"state/#dagpipe.state.State.lineage","title":"lineage","text":"
lineage() -> tuple[State, ...]\n

Return lineage from root to this State.

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Ordered execution lineage (root first).

"},{"location":"yaml_loader/","title":"Yaml Loader","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader","title":"dagpipe.yaml_loader","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader--summary","title":"Summary","text":"

Loads dagpipe pipelines from YAML configuration.

Creates fully configured pipeline objects from declarative YAML definitions, including Schema, State subclasses, Node instances, Graph topology, and initial payloads.

"},{"location":"yaml_loader/#dagpipe.yaml_loader-classes","title":"Classes","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline","title":"Pipeline dataclass","text":"
Pipeline(\n    engine: Engine,\n    state_cls: type[State],\n    initial_payload: Payload,\n)\n

Executable pipeline created from YAML configuration.

Attributes:

Name Type Description engineEngine

Execution engine responsible for running the pipeline.

state_clsType[State]

Dynamically created State subclass with configured schema.

initial_payloadPayload

Default payload used when execution begins.

Notes

Responsibilities:

- Encapsulates engine, state type, and initial payload.\n- Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying nodes are thread-safe.\n
"},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline-functions","title":"Functions","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.Pipeline.run","title":"run","text":"
run(\n    payload_override: Mapping[str, Any] | None = None,\n) -> list[State]\n

Execute the pipeline.

Parameters:

Name Type Description Default payload_overrideMapping[str, Any] | None

Payload values overriding initial payload.

None

Returns:

Type Description list[State]

list[State]: Terminal execution states.

Notes

Responsibilities:

- Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n
"},{"location":"yaml_loader/#dagpipe.yaml_loader-functions","title":"Functions","text":""},{"location":"yaml_loader/#dagpipe.yaml_loader.load_pipeline","title":"load_pipeline","text":"
load_pipeline(path: str) -> Pipeline\n

Load pipeline from YAML file.

Parameters:

Name Type Description Default pathstr

Path to YAML configuration file.

required

Returns:

Name Type Description PipelinePipeline

Executable pipeline instance.

Notes

Responsibilities:

- Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n
"},{"location":"dagpipe/","title":"Dagpipe","text":"
  • Engine
  • Graph
  • Node
  • State
  • Yaml Loader
"},{"location":"dagpipe/#dagpipe","title":"dagpipe","text":""},{"location":"dagpipe/#dagpipe--summary","title":"Summary","text":"

Directed acyclic graph execution framework for deterministic state propagation.

dagpipe executes pipelines composed of nodes connected in a directed acyclic graph (DAG). Each node receives an immutable State and optionally produces derived states for downstream nodes.

"},{"location":"dagpipe/#dagpipe--installation","title":"Installation","text":"

Install using pip:

pip install dagpipe\n
"},{"location":"dagpipe/#dagpipe--quick-start","title":"Quick Start","text":"
from dagpipe import State, Payload, Schema, Graph, Engine\nfrom dagpipe.node import Node\n\nclass HelloNode(Node):\n    id = \"hello\"\n    def resolve(self, state):\n        yield self.fork(state, payload_update={\"msg\": \"hello\"})\n\n# Build and run\ngraph = Graph()\ngraph.add_root(HelloNode())\nengine = Engine(graph)\n\nclass MyState(State):\n    schema = Schema({})\n\nresults = engine.run(MyState(payload=Payload({})))\n
"},{"location":"dagpipe/#dagpipe--public-api","title":"Public API","text":"

This package re-exports the core pipeline components. Consumers should import from this namespace for standard usage.

"},{"location":"dagpipe/#dagpipe--execution-core","title":"Execution Core","text":"
  • Engine: Responsible for orchestrating node execution and state propagation.
  • Graph: Defines the execution topology and node relationships.
  • Node: Base class for defining execution logic and transformations.
"},{"location":"dagpipe/#dagpipe--state-data","title":"State & Data","text":"
  • State: Represents an immutable execution snapshot at a point in time.
  • Payload: Immutable hierarchical container for execution data.
  • Schema: Defines and validates the allowed structure of payloads.
  • SchemaError: Raised when data violates the declared schema.
"},{"location":"dagpipe/#dagpipe--declarative-pipelines","title":"Declarative Pipelines","text":"
  • Pipeline: High-level wrapper for an engine, state type, and initial payload.
  • load_pipeline: Factory function to create a pipeline from YAML.
"},{"location":"dagpipe/#dagpipe-classes","title":"Classes","text":""},{"location":"dagpipe/#dagpipe.AsyncNode","title":"AsyncNode","text":"

Bases: Node

Base class for nodes whose execution is asynchronous.

Subclasses implement resolve_async (an async generator yielding derived State objects). The engine dispatches to resolve_async when running an async traversal (see Engine.run_async).

Sync-only engines (and the base Node.run) treat an AsyncNode as a no-op consumer: calling run on an AsyncNode returns no states, signalling that an async engine is required.

"},{"location":"dagpipe/#dagpipe.AsyncNode-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.AsyncNode.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"dagpipe/#dagpipe.AsyncNode.__hash__--returns","title":"Returns","text":"

int

"},{"location":"dagpipe/#dagpipe.AsyncNode.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"dagpipe/#dagpipe.AsyncNode.__repr__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/#dagpipe.AsyncNode.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"dagpipe/#dagpipe.AsyncNode.__str__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/#dagpipe.AsyncNode.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"dagpipe/#dagpipe.AsyncNode.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateAny

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateAny

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"dagpipe/#dagpipe.AsyncNode.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"dagpipe/#dagpipe.AsyncNode.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"dagpipe/#dagpipe.AsyncNode.resolve_async","title":"resolve_async async","text":"
resolve_async(state: State) -> Iterable[State]\n

Execute node logic asynchronously.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description Iterable[State]

Iterable[State]: Derived execution state(s).

Notes

Subclasses implement this. Must not mutate the input state. Should use fork() to create child states.

"},{"location":"dagpipe/#dagpipe.AsyncNode.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"dagpipe/#dagpipe.AsyncNode.run_async","title":"run_async async","text":"
run_async(state: State) -> tuple[State, ...]\n

Execute this node asynchronously on a state, validating outputs.

"},{"location":"dagpipe/#dagpipe.Engine","title":"Engine","text":"
Engine(\n    nodes_or_graph: Sequence[Node] | Graph,\n    *,\n    on_step: StepHook | None = None\n)\n

Execution engine responsible for running pipeline logic.

Notes

Responsibilities:

- Accepts either a linear sequence of `Node` objects or a `Graph`\n  defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n  collects terminal states.\n- Supports synchronous (`run`) and asynchronous (`run_async`)\n  execution, dispatching per-node.\n- Supports step-wise / resumable execution and progress hooks.\n

Guarantees:

- Never mutates `State`, `Node`, or `Graph` instances.\n- `State` objects are never modified in place; each branch produces\n  independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
"},{"location":"dagpipe/#dagpipe.Engine-attributes","title":"Attributes","text":""},{"location":"dagpipe/#dagpipe.Engine.nodes","title":"nodes property","text":"
nodes: tuple[Node, ...]\n

Return nodes managed by this engine.

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.

"},{"location":"dagpipe/#dagpipe.Engine-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Engine.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return the canonical string representation of the object.

Returns:

Name Type Description strstr

Representation that uniquely identifies the object and its configuration.

"},{"location":"dagpipe/#dagpipe.Engine.run","title":"run","text":"
run(root: State) -> list[State]\n

Execute the pipeline starting from a root State.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Raises:

Type Description TypeError

If root is not a State instance.

RuntimeError

If the engine execution mode is invalid.

Notes

Responsibilities:

- Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n
"},{"location":"dagpipe/#dagpipe.Engine.run_async","title":"run_async async","text":"
run_async(root: State) -> list[State]\n

Execute the pipeline starting from root, dispatching sync vs async nodes.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Notes

Each node is executed with Node.run when synchronous and AsyncNode.run_async when asynchronous. Linear and graph topologies are both supported.

"},{"location":"dagpipe/#dagpipe.Engine.run_steps","title":"run_steps","text":"
run_steps(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: StepHook | None = None\n) -> Iterator[StepResult]\n

Execute the pipeline step-by-step, yielding one StepResult per step.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint | None

Skip steps at index < resume_from (for resume-after-partial). Steps are 0-indexed.

Noneon_stepStepHook | None

Callback (step, status, message) invoked per step; falls back to the engine-level hook when unset.

None

Yields:

Name Type Description StepResultStepResult

One per executed node/step, carrying the produced states.

Notes

This is a synchronous, generator-based checkpoint interface compatible with the imperative resume-by-step behaviour of the legacy orchestrator. Use run_steps_async for async nodes.

"},{"location":"dagpipe/#dagpipe.Engine.run_steps_async","title":"run_steps_async async","text":"
run_steps_async(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: AsyncStepHook | None = None\n) -> AsyncIterator[StepResult]\n

Async variant of run_steps supporting AsyncNode execution.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint | None

Skip steps at index < resume_from.

Noneon_stepAsyncStepHook | None

Async callback (step, status, message) invoked per step.

None

Yields:

Name Type Description StepResultAsyncIterator[StepResult]

One per executed node/step.

"},{"location":"dagpipe/#dagpipe.Graph","title":"Graph","text":"
Graph()\n

Directed Acyclic Graph defining execution topology of Node objects.

Notes

Responsibilities:

- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n

Guarantees:

- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n

Create an empty Graph.

"},{"location":"dagpipe/#dagpipe.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"dagpipe/#dagpipe.Graph-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Graph.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"dagpipe/#dagpipe.Graph.__repr__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/#dagpipe.Graph.add_edge","title":"add_edge","text":"
add_edge(src: Node, dst: Node) -> None\n

Add a directed edge from src to dst.

Parameters:

Name Type Description Default srcNode

Source node.

required dstNode

Destination node.

required

Raises:

Type Description TypeError

If src or dst is not a Node.

ValueError

If the edge would create a cycle or if src and dst are common.

Notes
  • Validates node types.
  • Prevents cycles.
  • Registers nodes if not present.
  • Updates parent and child mappings.
"},{"location":"dagpipe/#dagpipe.Graph.add_root","title":"add_root","text":"
add_root(node: Node) -> None\n

Add a root node with no parents.

Parameters:

Name Type Description Default nodeNode

Node to add as a root.

required

Raises:

Type Description TypeError

If node is not a Node instance.

"},{"location":"dagpipe/#dagpipe.Graph.children","title":"children","text":"
children(node: Node) -> tuple[Node, ...]\n

Return child nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Outgoing neighbors.

"},{"location":"dagpipe/#dagpipe.Graph.nodes","title":"nodes","text":"
nodes() -> tuple[Node, ...]\n

Return all nodes in the graph.

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: All registered nodes.

"},{"location":"dagpipe/#dagpipe.Graph.parents","title":"parents","text":"
parents(node: Node) -> tuple[Node, ...]\n

Return parent nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Incoming neighbors.

"},{"location":"dagpipe/#dagpipe.Graph.roots","title":"roots","text":"
roots() -> tuple[Node, ...]\n

Return root nodes (nodes with no incoming edges).

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Entry point nodes.

"},{"location":"dagpipe/#dagpipe.Node","title":"Node","text":"

Bases: ABC

Base class for all dagpipe execution nodes.

Attributes:

Name Type Description idstr

Unique identifier of the node (snake_case dotted format).

namestr

Human-readable display name.

Notes

Responsibilities:

- Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one `State` and produces zero, one, or many derived states.\n- Defines execution logic and enables branching, filtering, and transformation.\n

Guarantees:

- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n
"},{"location":"dagpipe/#dagpipe.Node-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Node.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"dagpipe/#dagpipe.Node.__hash__--returns","title":"Returns","text":"

int

"},{"location":"dagpipe/#dagpipe.Node.__new__","title":"__new__","text":"
__new__(*args: Any, **kwargs: Any) -> Node\n

Create or reuse a Node instance.

Stateless subclasses (no parameterized __init__) share one singleton instance per class \u2014 matching the original dagpipe behaviour underpinning set_registry-style configuration. Subclasses that declare an __init__ requiring instance-state arguments get a fresh instance per construction so pipeline builders can inject per-run dependencies.

"},{"location":"dagpipe/#dagpipe.Node.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"dagpipe/#dagpipe.Node.__repr__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/#dagpipe.Node.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"dagpipe/#dagpipe.Node.__str__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/#dagpipe.Node.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"dagpipe/#dagpipe.Node.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateAny

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateAny

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"dagpipe/#dagpipe.Node.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"dagpipe/#dagpipe.Node.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"dagpipe/#dagpipe.Node.resolve","title":"resolve abstractmethod","text":"
resolve(state: State) -> Iterable[State]\n

Execute node logic.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description Iterable[State]

Iterable[State]: Derived execution state(s).

Notes

Responsibilities:

- Subclasses implement specific resolution behavior.\n- Must not mutate input state.\n- Should use `fork()` to create child states.\n- May yield zero states to terminate a branch.\n
"},{"location":"dagpipe/#dagpipe.Node.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"dagpipe/#dagpipe.Payload","title":"Payload dataclass","text":"
Payload(_data: Mapping[str, Any])\n

Immutable hierarchical container with dot-path access.

Attributes:

Name Type Description _dataMapping[str, Any]

Immutable hierarchical data structure.

Notes

Responsibilities:

- Stores execution data used by `State`.\n- Supports efficient atomic updates without modifying existing instances.\n- `Payload` instances are fully thread-safe due to immutability.\n
"},{"location":"dagpipe/#dagpipe.Payload-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Payload.as_dict","title":"as_dict","text":"
as_dict() -> Mapping[str, Any]\n

Return underlying mapping.

Returns:

Type Description Mapping[str, Any]

Mapping[str, Any]: Read-only view of the underlying data.

"},{"location":"dagpipe/#dagpipe.Payload.get","title":"get","text":"
get(path: str, default: Any = None) -> Any\n

Retrieve value using dot-path.

Parameters:

Name Type Description Default pathstr

Dot-separated path to the value.

required defaultAny

Default value if path doesn't exist.

None

Returns:

Name Type Description AnyAny

The retrieved value or default.

"},{"location":"dagpipe/#dagpipe.Payload.has","title":"has","text":"
has(path: str) -> bool\n

Return True if path exists.

Parameters:

Name Type Description Default pathstr

Dot-separated path to check.

required

Returns:

Name Type Description boolbool

Existence of the path.

"},{"location":"dagpipe/#dagpipe.Payload.iter_paths","title":"iter_paths classmethod","text":"
iter_paths(\n    data: Mapping[str, Any], prefix: str = \"\"\n) -> Iterable[str]\n

Recursively yield dot-paths for all leaf nodes.

Parameters:

Name Type Description Default dataMapping[str, Any]

The mapping to iterate over.

required prefixstr

Current path prefix.

''

Yields:

Name Type Description strIterable[str]

Dot-path for each leaf node.

"},{"location":"dagpipe/#dagpipe.Payload.keys","title":"keys","text":"
keys() -> Iterable[str]\n

Return top-level keys.

Returns:

Type Description Iterable[str]

Iterable[str]: Iterator over top-level keys.

"},{"location":"dagpipe/#dagpipe.Payload.update","title":"update","text":"
update(updates: Mapping[str, Any]) -> Payload\n

Create a new Payload with dot-path updates applied.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path to value mapping.

required

Returns:

Name Type Description PayloadPayload

New immutable payload instance with updates.

Notes

Guarantees:

- Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n
"},{"location":"dagpipe/#dagpipe.Pipeline","title":"Pipeline dataclass","text":"
Pipeline(\n    engine: Engine,\n    state_cls: type[State],\n    initial_payload: Payload,\n)\n

Executable pipeline created from YAML configuration.

Attributes:

Name Type Description engineEngine

Execution engine responsible for running the pipeline.

state_clsType[State]

Dynamically created State subclass with configured schema.

initial_payloadPayload

Default payload used when execution begins.

Notes

Responsibilities:

- Encapsulates engine, state type, and initial payload.\n- Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying nodes are thread-safe.\n
"},{"location":"dagpipe/#dagpipe.Pipeline-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Pipeline.run","title":"run","text":"
run(\n    payload_override: Mapping[str, Any] | None = None,\n) -> list[State]\n

Execute the pipeline.

Parameters:

Name Type Description Default payload_overrideMapping[str, Any] | None

Payload values overriding initial payload.

None

Returns:

Type Description list[State]

list[State]: Terminal execution states.

Notes

Responsibilities:

- Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n
"},{"location":"dagpipe/#dagpipe.ProgressMessage","title":"ProgressMessage","text":"
ProgressMessage(\n    *,\n    lines: int | None = None,\n    blocks: int | None = None,\n    count: int | None = None,\n    unit: str | None = None,\n    raw_ocr_line: str | None = None,\n    error: str | None = None,\n    step: str = \"\",\n    status: str = \"\"\n)\n

Lightweight progress payload emitted by engine step hooks.

Mirrors the imperative ProgressMessage used by the legacy orchestrator so callers can surface counts/lines/errors without coupling the engine to pydantic.

"},{"location":"dagpipe/#dagpipe.Schema","title":"Schema dataclass","text":"
Schema(tree: Mapping[str, SchemaNode])\n

Immutable hierarchical schema defining allowed payload structure.

Attributes:

Name Type Description treeMapping[str, SchemaNode]

Hierarchical schema definition.

Notes

Responsibilities:

- Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n
"},{"location":"dagpipe/#dagpipe.Schema-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.Schema.validate_payload","title":"validate_payload","text":"
validate_payload(payload: Payload) -> None\n

Validate complete payload structure.

Parameters:

Name Type Description Default payloadPayload

Payload to validate.

required

Raises:

Type Description SchemaError

If payload violates schema.

"},{"location":"dagpipe/#dagpipe.Schema.validate_update","title":"validate_update","text":"
validate_update(updates: Mapping[str, Any]) -> None\n

Validate payload update paths.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path updates to validate.

required

Raises:

Type Description SchemaError

If any path is invalid according to the schema.

"},{"location":"dagpipe/#dagpipe.SchemaError","title":"SchemaError","text":"

Bases: Exception

Raised when payload data violates the declared schema.

"},{"location":"dagpipe/#dagpipe.SchemaError--indicates-invalid-structure-invalid-path-or-invalid-type","title":"Indicates invalid structure, invalid path, or invalid type.","text":""},{"location":"dagpipe/#dagpipe.State","title":"State dataclass","text":"
State(\n    payload: Payload,\n    confidence: float = 1.0,\n    parent: State | None = None,\n    depth: int = 0,\n    history: tuple[str, ...] = tuple(),\n    metadata: dict[str, Any] = dict(),\n)\n

Immutable execution state propagated through dagpipe pipeline.

Attributes:

Name Type Description payloadPayload

Execution data container.

schemaClassVar[Schema]

Payload validation schema.

confidencefloat

Execution confidence score.

parentOptional[State]

Parent state reference.

depthint

Execution depth.

historyTuple[str, ...]

Ordered node execution lineage.

metadataDict[str, Any]

Execution metadata.

Notes

Responsibilities:

- Represents a complete execution snapshot at a specific point in\n  pipeline traversal.\n- Fundamental unit of execution in `dagpipe`.\n- Fully thread-safe due to immutability.\n
"},{"location":"dagpipe/#dagpipe.State-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.State.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Concise debug representation.

Avoids printing full data for large states.

"},{"location":"dagpipe/#dagpipe.State.fork","title":"fork","text":"
fork(\n    *,\n    payload_update: Mapping[str, Any] | None = None,\n    confidence_delta: float = 0.0,\n    node_id: str | None = None,\n    metadata_update: Mapping[str, Any] | None = None\n) -> State\n

Create a new child State derived from this state.

Parameters:

Name Type Description Default payload_updateMapping[str, Any] | None

Dot-path updates applied to the payload.

Noneconfidence_deltafloat

Adjustment applied to current confidence.

0.0node_idstr | None

Identifier of the node creating this state.

Nonemetadata_updateMapping[str, Any] | None

Updates merged into state metadata.

None

Returns:

Name Type Description StateState

A new immutable State instance.

Notes

Guarantees:

- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n
"},{"location":"dagpipe/#dagpipe.State.get","title":"get","text":"
get(key: str, default: Any = None) -> Any\n

Retrieve payload value.

Parameters:

Name Type Description Default keystr

Dot-path key.

required defaultAny

Fallback value.

None

Returns:

Name Type Description AnyAny

Stored value or default.

"},{"location":"dagpipe/#dagpipe.State.has","title":"has","text":"
has(key: str) -> bool\n

Check whether payload contains key.

Parameters:

Name Type Description Default keystr

Dot-path key.

required

Returns:

Name Type Description boolbool

Existence of the key.

"},{"location":"dagpipe/#dagpipe.State.lineage","title":"lineage","text":"
lineage() -> tuple[State, ...]\n

Return lineage from root to this State.

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Ordered execution lineage (root first).

"},{"location":"dagpipe/#dagpipe.StepResult","title":"StepResult","text":"
StepResult(\n    index: int,\n    node_id: str,\n    states: tuple[State, ...],\n    completed: bool,\n)\n

A single checkpointed step within an async/resumable engine run.

Attributes:

Name Type Description indexint

Ordinal index of the step.

node_idstr

Identifier of the node associated with this step.

statestuple[State, ...]

States produced by running this step.

completedbool

Whether this step succeeded (vs. paused/interrupted).

Initialise StepResult.

Parameters:

Name Type Description Default indexint

Ordinal index of the step.

required node_idstr

Identifier of the node associated with this step.

required statestuple[State, ...]

States produced by running this step.

required completedbool

Whether this step succeeded (vs. paused/interrupted).

required"},{"location":"dagpipe/#dagpipe.StepResult-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe-functions","title":"Functions","text":""},{"location":"dagpipe/#dagpipe.load_pipeline","title":"load_pipeline","text":"
load_pipeline(path: str) -> Pipeline\n

Load pipeline from YAML file.

Parameters:

Name Type Description Default pathstr

Path to YAML configuration file.

required

Returns:

Name Type Description PipelinePipeline

Executable pipeline instance.

Notes

Responsibilities:

- Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n
"},{"location":"dagpipe/engine/","title":"Engine","text":""},{"location":"dagpipe/engine/#dagpipe.engine","title":"dagpipe.engine","text":""},{"location":"dagpipe/engine/#dagpipe.engine--summary","title":"Summary","text":"

Execution engine responsible for running pipelines and graphs.

The Engine executes Node objects and propagates immutable State instances through either a linear sequence or a directed acyclic graph (Graph). It orchestrates execution order, branching, and state propagation.

"},{"location":"dagpipe/engine/#dagpipe.engine--guarantees","title":"Guarantees","text":"
  • Deterministic execution and consistent state lineage.
  • Orchestrates execution without modifying Graph, Node, or State objects.
"},{"location":"dagpipe/engine/#dagpipe.engine-classes","title":"Classes","text":""},{"location":"dagpipe/engine/#dagpipe.engine.Engine","title":"Engine","text":"
Engine(\n    nodes_or_graph: Sequence[Node] | Graph,\n    *,\n    on_step: StepHook | None = None\n)\n

Execution engine responsible for running pipeline logic.

Notes

Responsibilities:

- Accepts either a linear sequence of `Node` objects or a `Graph`\n  defining execution topology.\n- Propagates immutable `State` objects through `Node` objects and\n  collects terminal states.\n- Supports synchronous (`run`) and asynchronous (`run_async`)\n  execution, dispatching per-node.\n- Supports step-wise / resumable execution and progress hooks.\n

Guarantees:

- Never mutates `State`, `Node`, or `Graph` instances.\n- `State` objects are never modified in place; each branch produces\n  independent instances.\n- Execution order is deterministic and follows graph or pipeline topology.\n- Thread-safe for concurrent execution.\n
"},{"location":"dagpipe/engine/#dagpipe.engine.Engine-attributes","title":"Attributes","text":""},{"location":"dagpipe/engine/#dagpipe.engine.Engine.nodes","title":"nodes property","text":"
nodes: tuple[Node, ...]\n

Return nodes managed by this engine.

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Ordered sequence in linear mode or all nodes in graph mode.

"},{"location":"dagpipe/engine/#dagpipe.engine.Engine-functions","title":"Functions","text":""},{"location":"dagpipe/engine/#dagpipe.engine.Engine.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return the canonical string representation of the object.

Returns:

Name Type Description strstr

Representation that uniquely identifies the object and its configuration.

"},{"location":"dagpipe/engine/#dagpipe.engine.Engine.run","title":"run","text":"
run(root: State) -> list[State]\n

Execute the pipeline starting from a root State.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Raises:

Type Description TypeError

If root is not a State instance.

RuntimeError

If the engine execution mode is invalid.

Notes

Responsibilities:

- Selects execution mode, propagates state through nodes, creates\n  new instances for branches, and collects terminal states.\n
"},{"location":"dagpipe/engine/#dagpipe.engine.Engine.run_async","title":"run_async async","text":"
run_async(root: State) -> list[State]\n

Execute the pipeline starting from root, dispatching sync vs async nodes.

Parameters:

Name Type Description Default rootState

Initial execution state.

required

Returns:

Type Description list[State]

list[State]: Terminal execution states produced by the pipeline.

Notes

Each node is executed with Node.run when synchronous and AsyncNode.run_async when asynchronous. Linear and graph topologies are both supported.

"},{"location":"dagpipe/engine/#dagpipe.engine.Engine.run_steps","title":"run_steps","text":"
run_steps(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: StepHook | None = None\n) -> Iterator[StepResult]\n

Execute the pipeline step-by-step, yielding one StepResult per step.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint | None

Skip steps at index < resume_from (for resume-after-partial). Steps are 0-indexed.

Noneon_stepStepHook | None

Callback (step, status, message) invoked per step; falls back to the engine-level hook when unset.

None

Yields:

Name Type Description StepResultStepResult

One per executed node/step, carrying the produced states.

Notes

This is a synchronous, generator-based checkpoint interface compatible with the imperative resume-by-step behaviour of the legacy orchestrator. Use run_steps_async for async nodes.

"},{"location":"dagpipe/engine/#dagpipe.engine.Engine.run_steps_async","title":"run_steps_async async","text":"
run_steps_async(\n    root: State,\n    *,\n    resume_from: int | None = None,\n    on_step: AsyncStepHook | None = None\n) -> AsyncIterator[StepResult]\n

Async variant of run_steps supporting AsyncNode execution.

Parameters:

Name Type Description Default rootState

Initial execution state.

required resume_fromint | None

Skip steps at index < resume_from.

Noneon_stepAsyncStepHook | None

Async callback (step, status, message) invoked per step.

None

Yields:

Name Type Description StepResultAsyncIterator[StepResult]

One per executed node/step.

"},{"location":"dagpipe/engine/#dagpipe.engine.ProgressMessage","title":"ProgressMessage","text":"
ProgressMessage(\n    *,\n    lines: int | None = None,\n    blocks: int | None = None,\n    count: int | None = None,\n    unit: str | None = None,\n    raw_ocr_line: str | None = None,\n    error: str | None = None,\n    step: str = \"\",\n    status: str = \"\"\n)\n

Lightweight progress payload emitted by engine step hooks.

Mirrors the imperative ProgressMessage used by the legacy orchestrator so callers can surface counts/lines/errors without coupling the engine to pydantic.

"},{"location":"dagpipe/engine/#dagpipe.engine.StepResult","title":"StepResult","text":"
StepResult(\n    index: int,\n    node_id: str,\n    states: tuple[State, ...],\n    completed: bool,\n)\n

A single checkpointed step within an async/resumable engine run.

Attributes:

Name Type Description indexint

Ordinal index of the step.

node_idstr

Identifier of the node associated with this step.

statestuple[State, ...]

States produced by running this step.

completedbool

Whether this step succeeded (vs. paused/interrupted).

Initialise StepResult.

Parameters:

Name Type Description Default indexint

Ordinal index of the step.

required node_idstr

Identifier of the node associated with this step.

required statestuple[State, ...]

States produced by running this step.

required completedbool

Whether this step succeeded (vs. paused/interrupted).

required"},{"location":"dagpipe/engine/#dagpipe.engine.StepResult-functions","title":"Functions","text":""},{"location":"dagpipe/graph/","title":"Graph","text":""},{"location":"dagpipe/graph/#dagpipe.graph","title":"dagpipe.graph","text":""},{"location":"dagpipe/graph/#dagpipe.graph--summary","title":"Summary","text":"

Defines DAG structure connecting nodes.

A Graph describes execution topology only. It does not execute nodes or manage State. Execution is handled by an Engine.

"},{"location":"dagpipe/graph/#dagpipe.graph--responsibilities","title":"Responsibilities","text":"
  • Multiple roots, branching, and merging support.
  • Deterministic traversal based on topology.
  • Graph is mutable during construction but treated as immutable at runtime.
"},{"location":"dagpipe/graph/#dagpipe.graph-classes","title":"Classes","text":""},{"location":"dagpipe/graph/#dagpipe.graph.Graph","title":"Graph","text":"
Graph()\n

Directed Acyclic Graph defining execution topology of Node objects.

Notes

Responsibilities:

- Stores node connectivity and validates that the topology remains acyclic.\n- Structure determines how `State` flows between nodes during execution.\n

Guarantees:

- Topology is acyclic. Node relationships remain consistent.\n- Thread-safe for concurrent reads after construction.\n

Create an empty Graph.

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph--initializes-node-registry-and-edge-mappings","title":"Initializes node registry and edge mappings.","text":""},{"location":"dagpipe/graph/#dagpipe.graph.Graph-functions","title":"Functions","text":""},{"location":"dagpipe/graph/#dagpipe.graph.Graph.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.__repr__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_edge","title":"add_edge","text":"
add_edge(src: Node, dst: Node) -> None\n

Add a directed edge from src to dst.

Parameters:

Name Type Description Default srcNode

Source node.

required dstNode

Destination node.

required

Raises:

Type Description TypeError

If src or dst is not a Node.

ValueError

If the edge would create a cycle or if src and dst are common.

Notes
  • Validates node types.
  • Prevents cycles.
  • Registers nodes if not present.
  • Updates parent and child mappings.
"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.add_root","title":"add_root","text":"
add_root(node: Node) -> None\n

Add a root node with no parents.

Parameters:

Name Type Description Default nodeNode

Node to add as a root.

required

Raises:

Type Description TypeError

If node is not a Node instance.

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.children","title":"children","text":"
children(node: Node) -> tuple[Node, ...]\n

Return child nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Outgoing neighbors.

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.nodes","title":"nodes","text":"
nodes() -> tuple[Node, ...]\n

Return all nodes in the graph.

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: All registered nodes.

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.parents","title":"parents","text":"
parents(node: Node) -> tuple[Node, ...]\n

Return parent nodes of a node.

Parameters:

Name Type Description Default nodeNode

Node to query.

required

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Incoming neighbors.

"},{"location":"dagpipe/graph/#dagpipe.graph.Graph.roots","title":"roots","text":"
roots() -> tuple[Node, ...]\n

Return root nodes (nodes with no incoming edges).

Returns:

Type Description tuple[Node, ...]

tuple[Node, ...]: Entry point nodes.

"},{"location":"dagpipe/node/","title":"Node","text":""},{"location":"dagpipe/node/#dagpipe.node","title":"dagpipe.node","text":""},{"location":"dagpipe/node/#dagpipe.node--summary","title":"Summary","text":"

Defines the Node abstraction used by dagpipe.

A node represents a single unit of pipeline execution logic. It consumes one State and produces zero, one, or many new State objects.

Nodes are connected using a Graph and executed by an Engine.

"},{"location":"dagpipe/node/#dagpipe.node--design-principles","title":"Design principles","text":"
  • Pure: Must not mutate input state.
  • Deterministic: Same input produces same output.
  • Stateless: Recommended to be stateless for reuse.
  • Composable: Nodes enable branching execution graphs.
"},{"location":"dagpipe/node/#dagpipe.node-classes","title":"Classes","text":""},{"location":"dagpipe/node/#dagpipe.node.AsyncNode","title":"AsyncNode","text":"

Bases: Node

Base class for nodes whose execution is asynchronous.

Subclasses implement resolve_async (an async generator yielding derived State objects). The engine dispatches to resolve_async when running an async traversal (see Engine.run_async).

Sync-only engines (and the base Node.run) treat an AsyncNode as a no-op consumer: calling run on an AsyncNode returns no states, signalling that an async engine is required.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode-functions","title":"Functions","text":""},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__hash__--returns","title":"Returns","text":"

int

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__repr__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.__str__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateAny

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateAny

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.resolve_async","title":"resolve_async async","text":"
resolve_async(state: State) -> Iterable[State]\n

Execute node logic asynchronously.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description Iterable[State]

Iterable[State]: Derived execution state(s).

Notes

Subclasses implement this. Must not mutate the input state. Should use fork() to create child states.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"dagpipe/node/#dagpipe.node.AsyncNode.run_async","title":"run_async async","text":"
run_async(state: State) -> tuple[State, ...]\n

Execute this node asynchronously on a state, validating outputs.

"},{"location":"dagpipe/node/#dagpipe.node.Node","title":"Node","text":"

Bases: ABC

Base class for all dagpipe execution nodes.

Attributes:

Name Type Description idstr

Unique identifier of the node (snake_case dotted format).

namestr

Human-readable display name.

Notes

Responsibilities:

- Represents a deterministic unit of execution in the pipeline graph.\n- Consumes one `State` and produces zero, one, or many derived states.\n- Defines execution logic and enables branching, filtering, and transformation.\n

Guarantees:

- Nodes must never mutate the input `State`.\n- Instances are singletons per subclass and reused across executions.\n
"},{"location":"dagpipe/node/#dagpipe.node.Node-functions","title":"Functions","text":""},{"location":"dagpipe/node/#dagpipe.node.Node.__hash__","title":"__hash__","text":"
__hash__() -> int\n

Return stable hash based on node ID.

"},{"location":"dagpipe/node/#dagpipe.node.Node.__hash__--returns","title":"Returns","text":"

int

"},{"location":"dagpipe/node/#dagpipe.node.Node.__new__","title":"__new__","text":"
__new__(*args: Any, **kwargs: Any) -> Node\n

Create or reuse a Node instance.

Stateless subclasses (no parameterized __init__) share one singleton instance per class \u2014 matching the original dagpipe behaviour underpinning set_registry-style configuration. Subclasses that declare an __init__ requiring instance-state arguments get a fresh instance per construction so pipeline builders can inject per-run dependencies.

"},{"location":"dagpipe/node/#dagpipe.node.Node.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Return debug representation.

"},{"location":"dagpipe/node/#dagpipe.node.Node.__repr__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/node/#dagpipe.node.Node.__str__","title":"__str__","text":"
__str__() -> str\n

Return display representation.

"},{"location":"dagpipe/node/#dagpipe.node.Node.__str__--returns","title":"Returns","text":"

str

"},{"location":"dagpipe/node/#dagpipe.node.Node.clean_id_and_name","title":"clean_id_and_name classmethod","text":"
clean_id_and_name() -> None\n

Normalize and validate node ID and display name.

Raises:

Type Description TypeError

If ID is not a string.

ValueError

If ID format is invalid.

Notes

Guarantees:

- Generates ID from module and class name if missing.\n- Validates ID format.\n- Generates human-readable name if missing.\n
"},{"location":"dagpipe/node/#dagpipe.node.Node.fork","title":"fork","text":"
fork(\n    state: State,\n    *,\n    payload_update: Any = None,\n    confidence_delta: float = 0.0,\n    metadata_update: Any = None\n) -> State\n

Create a child State attributed to this node.

Parameters:

Name Type Description Default stateState

Parent execution state.

required payload_updateAny

Dot-path payload updates.

Noneconfidence_deltafloat

Confidence adjustment.

0.0metadata_updateAny

Metadata updates.

None

Returns:

Name Type Description StateState

New child execution state.

Notes

Responsibilities:

- Convenience wrapper around `State.fork()` that automatically\n  records this node's ID in state history.\n
"},{"location":"dagpipe/node/#dagpipe.node.Node.is_async","title":"is_async","text":"
is_async() -> bool\n

Return whether this node executes asynchronously.

"},{"location":"dagpipe/node/#dagpipe.node.Node.node_id_to_name","title":"node_id_to_name staticmethod","text":"
node_id_to_name(node_id: str) -> str\n

Convert a dotted snake_case node ID into a human-readable name.

Parameters:

Name Type Description Default node_idstr

Unique node identifier (e.g., 'entity.resolve.numeric_merchant').

required

Returns:

Name Type Description strstr

Human-readable display name (e.g., 'Entity \u203a Resolve \u203a Numeric Merchant').

"},{"location":"dagpipe/node/#dagpipe.node.Node.resolve","title":"resolve abstractmethod","text":"
resolve(state: State) -> Iterable[State]\n

Execute node logic.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description Iterable[State]

Iterable[State]: Derived execution state(s).

Notes

Responsibilities:

- Subclasses implement specific resolution behavior.\n- Must not mutate input state.\n- Should use `fork()` to create child states.\n- May yield zero states to terminate a branch.\n
"},{"location":"dagpipe/node/#dagpipe.node.Node.run","title":"run","text":"
run(state: State) -> tuple[State, ...]\n

Execute this node on a State.

Parameters:

Name Type Description Default stateState

Input execution state.

required

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Derived execution states.

Raises:

Type Description TypeError

If resolve() yields a non-State object.

"},{"location":"dagpipe/state/","title":"State","text":""},{"location":"dagpipe/state/#dagpipe.state","title":"dagpipe.state","text":""},{"location":"dagpipe/state/#dagpipe.state--summary","title":"Summary","text":"

Defines the core State object used by dagpipe.

The State represents a single point in pipeline execution. It contains arbitrary data and metadata and is designed to be immutable. Instead of modifying an existing state, nodes create new child states via fork().

"},{"location":"dagpipe/state/#dagpipe.state--design-principles","title":"Design principles","text":"
  • Immutability: States must never be modified after creation. All transformations must create a new state via fork().
  • Cheap cloning: Forking must be efficient since branching may create many states.
  • Lineage tracking: Each state maintains a reference to its parent and execution metadata for debugging and observability.
  • Domain agnostic: State contains generic key-value data and does not assume any schema.
  • Engine-friendly: State contains execution metadata such as depth and history.
"},{"location":"dagpipe/state/#dagpipe.state-classes","title":"Classes","text":""},{"location":"dagpipe/state/#dagpipe.state.Payload","title":"Payload dataclass","text":"
Payload(_data: Mapping[str, Any])\n

Immutable hierarchical container with dot-path access.

Attributes:

Name Type Description _dataMapping[str, Any]

Immutable hierarchical data structure.

Notes

Responsibilities:

- Stores execution data used by `State`.\n- Supports efficient atomic updates without modifying existing instances.\n- `Payload` instances are fully thread-safe due to immutability.\n
"},{"location":"dagpipe/state/#dagpipe.state.Payload-functions","title":"Functions","text":""},{"location":"dagpipe/state/#dagpipe.state.Payload.as_dict","title":"as_dict","text":"
as_dict() -> Mapping[str, Any]\n

Return underlying mapping.

Returns:

Type Description Mapping[str, Any]

Mapping[str, Any]: Read-only view of the underlying data.

"},{"location":"dagpipe/state/#dagpipe.state.Payload.get","title":"get","text":"
get(path: str, default: Any = None) -> Any\n

Retrieve value using dot-path.

Parameters:

Name Type Description Default pathstr

Dot-separated path to the value.

required defaultAny

Default value if path doesn't exist.

None

Returns:

Name Type Description AnyAny

The retrieved value or default.

"},{"location":"dagpipe/state/#dagpipe.state.Payload.has","title":"has","text":"
has(path: str) -> bool\n

Return True if path exists.

Parameters:

Name Type Description Default pathstr

Dot-separated path to check.

required

Returns:

Name Type Description boolbool

Existence of the path.

"},{"location":"dagpipe/state/#dagpipe.state.Payload.iter_paths","title":"iter_paths classmethod","text":"
iter_paths(\n    data: Mapping[str, Any], prefix: str = \"\"\n) -> Iterable[str]\n

Recursively yield dot-paths for all leaf nodes.

Parameters:

Name Type Description Default dataMapping[str, Any]

The mapping to iterate over.

required prefixstr

Current path prefix.

''

Yields:

Name Type Description strIterable[str]

Dot-path for each leaf node.

"},{"location":"dagpipe/state/#dagpipe.state.Payload.keys","title":"keys","text":"
keys() -> Iterable[str]\n

Return top-level keys.

Returns:

Type Description Iterable[str]

Iterable[str]: Iterator over top-level keys.

"},{"location":"dagpipe/state/#dagpipe.state.Payload.update","title":"update","text":"
update(updates: Mapping[str, Any]) -> Payload\n

Create a new Payload with dot-path updates applied.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path to value mapping.

required

Returns:

Name Type Description PayloadPayload

New immutable payload instance with updates.

Notes

Guarantees:

- Preserves existing data by copying only modified branches.\n- Returns a new immutable `Payload`.\n
"},{"location":"dagpipe/state/#dagpipe.state.Schema","title":"Schema dataclass","text":"
Schema(tree: Mapping[str, SchemaNode])\n

Immutable hierarchical schema defining allowed payload structure.

Attributes:

Name Type Description treeMapping[str, SchemaNode]

Hierarchical schema definition.

Notes

Responsibilities:

- Validates `State` payloads and updates.\n- Reusable across all `State` instances.\n- Fully thread-safe due to immutability.\n
"},{"location":"dagpipe/state/#dagpipe.state.Schema-functions","title":"Functions","text":""},{"location":"dagpipe/state/#dagpipe.state.Schema.validate_payload","title":"validate_payload","text":"
validate_payload(payload: Payload) -> None\n

Validate complete payload structure.

Parameters:

Name Type Description Default payloadPayload

Payload to validate.

required

Raises:

Type Description SchemaError

If payload violates schema.

"},{"location":"dagpipe/state/#dagpipe.state.Schema.validate_update","title":"validate_update","text":"
validate_update(updates: Mapping[str, Any]) -> None\n

Validate payload update paths.

Parameters:

Name Type Description Default updatesMapping[str, Any]

Dot-path updates to validate.

required

Raises:

Type Description SchemaError

If any path is invalid according to the schema.

"},{"location":"dagpipe/state/#dagpipe.state.SchemaError","title":"SchemaError","text":"

Bases: Exception

Raised when payload data violates the declared schema.

"},{"location":"dagpipe/state/#dagpipe.state.SchemaError--indicates-invalid-structure-invalid-path-or-invalid-type","title":"Indicates invalid structure, invalid path, or invalid type.","text":""},{"location":"dagpipe/state/#dagpipe.state.State","title":"State dataclass","text":"
State(\n    payload: Payload,\n    confidence: float = 1.0,\n    parent: State | None = None,\n    depth: int = 0,\n    history: tuple[str, ...] = tuple(),\n    metadata: dict[str, Any] = dict(),\n)\n

Immutable execution state propagated through dagpipe pipeline.

Attributes:

Name Type Description payloadPayload

Execution data container.

schemaClassVar[Schema]

Payload validation schema.

confidencefloat

Execution confidence score.

parentOptional[State]

Parent state reference.

depthint

Execution depth.

historyTuple[str, ...]

Ordered node execution lineage.

metadataDict[str, Any]

Execution metadata.

Notes

Responsibilities:

- Represents a complete execution snapshot at a specific point in\n  pipeline traversal.\n- Fundamental unit of execution in `dagpipe`.\n- Fully thread-safe due to immutability.\n
"},{"location":"dagpipe/state/#dagpipe.state.State-functions","title":"Functions","text":""},{"location":"dagpipe/state/#dagpipe.state.State.__repr__","title":"__repr__","text":"
__repr__() -> str\n

Concise debug representation.

Avoids printing full data for large states.

"},{"location":"dagpipe/state/#dagpipe.state.State.fork","title":"fork","text":"
fork(\n    *,\n    payload_update: Mapping[str, Any] | None = None,\n    confidence_delta: float = 0.0,\n    node_id: str | None = None,\n    metadata_update: Mapping[str, Any] | None = None\n) -> State\n

Create a new child State derived from this state.

Parameters:

Name Type Description Default payload_updateMapping[str, Any] | None

Dot-path updates applied to the payload.

Noneconfidence_deltafloat

Adjustment applied to current confidence.

0.0node_idstr | None

Identifier of the node creating this state.

Nonemetadata_updateMapping[str, Any] | None

Updates merged into state metadata.

None

Returns:

Name Type Description StateState

A new immutable State instance.

Notes

Guarantees:

- This is the only supported mechanism for modifying execution data.\n- Validates payload updates, preserves lineage, increments depth,\n  and appends to history.\n
"},{"location":"dagpipe/state/#dagpipe.state.State.get","title":"get","text":"
get(key: str, default: Any = None) -> Any\n

Retrieve payload value.

Parameters:

Name Type Description Default keystr

Dot-path key.

required defaultAny

Fallback value.

None

Returns:

Name Type Description AnyAny

Stored value or default.

"},{"location":"dagpipe/state/#dagpipe.state.State.has","title":"has","text":"
has(key: str) -> bool\n

Check whether payload contains key.

Parameters:

Name Type Description Default keystr

Dot-path key.

required

Returns:

Name Type Description boolbool

Existence of the key.

"},{"location":"dagpipe/state/#dagpipe.state.State.lineage","title":"lineage","text":"
lineage() -> tuple[State, ...]\n

Return lineage from root to this State.

Returns:

Type Description tuple[State, ...]

tuple[State, ...]: Ordered execution lineage (root first).

"},{"location":"dagpipe/yaml_loader/","title":"Yaml Loader","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader","title":"dagpipe.yaml_loader","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader--summary","title":"Summary","text":"

Loads dagpipe pipelines from YAML configuration.

Creates fully configured pipeline objects from declarative YAML definitions, including Schema, State subclasses, Node instances, Graph topology, and initial payloads.

"},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader-classes","title":"Classes","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.Pipeline","title":"Pipeline dataclass","text":"
Pipeline(\n    engine: Engine,\n    state_cls: type[State],\n    initial_payload: Payload,\n)\n

Executable pipeline created from YAML configuration.

Attributes:

Name Type Description engineEngine

Execution engine responsible for running the pipeline.

state_clsType[State]

Dynamically created State subclass with configured schema.

initial_payloadPayload

Default payload used when execution begins.

Notes

Responsibilities:

- Encapsulates engine, state type, and initial payload.\n- Provides a simplified interface for executing configured pipelines.\n- Safe for concurrent execution if underlying nodes are thread-safe.\n
"},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.Pipeline-functions","title":"Functions","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.Pipeline.run","title":"run","text":"
run(\n    payload_override: Mapping[str, Any] | None = None,\n) -> list[State]\n

Execute the pipeline.

Parameters:

Name Type Description Default payload_overrideMapping[str, Any] | None

Payload values overriding initial payload.

None

Returns:

Type Description list[State]

list[State]: Terminal execution states.

Notes

Responsibilities:

- Merges override payload with initial payload.\n- Creates root `State` and executes engine.\n
"},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader-functions","title":"Functions","text":""},{"location":"dagpipe/yaml_loader/#dagpipe.yaml_loader.load_pipeline","title":"load_pipeline","text":"
load_pipeline(path: str) -> Pipeline\n

Load pipeline from YAML file.

Parameters:

Name Type Description Default pathstr

Path to YAML configuration file.

required

Returns:

Name Type Description PipelinePipeline

Executable pipeline instance.

Notes

Responsibilities:

- Loads YAML configuration and builds schema.\n- Creates `State` subclass and loads `Node` instances.\n- Builds `Graph` topology and initializes `Engine`.\n
"}]} \ No newline at end of file diff --git a/dagpipe/lib/state/index.html b/dagpipe/lib/state/index.html index 4611635..c4d8ca7 100644 --- a/dagpipe/lib/state/index.html +++ b/dagpipe/lib/state/index.html @@ -1659,23 +1659,22 @@ Read-only view of the underlying data.

Name TypeType Description
State + Iterable[State]
-

Derived execution state(s).

+

Iterable[State]: +Derived execution state(s).
-

Returns:

+

Yields:

- + - @@ -2275,7 +2274,7 @@ Iterator over top-level keys.

diff --git a/dagpipe/lib/yaml_loader/index.html b/dagpipe/lib/yaml_loader/index.html index 4ed4dae..35291f2 100644 --- a/dagpipe/lib/yaml_loader/index.html +++ b/dagpipe/lib/yaml_loader/index.html @@ -1089,7 +1089,7 @@ and initial payloads.

TypeName Type Description
+str Iterable[str]
-

Iterable[str]: -Generator yielding dot-paths.

+

Dot-path for each leaf node.
payload_update - Mapping[str, Any] + Mapping[str, Any] | None
@@ -2303,7 +2302,7 @@ Iterator over top-level keys.

node_id - str + str | None
@@ -2317,7 +2316,7 @@ Iterator over top-level keys.

metadata_update - Mapping[str, Any] + Mapping[str, Any] | None
@@ -2556,7 +2555,7 @@ Iterator over top-level keys.
-

Tuple[State, ...]: +

tuple[State, ...]: Ordered execution lineage (root first).
payload_override - Mapping[str, Any] + Mapping[str, Any] | None
diff --git a/mail-intake/lib/credentials/index.html b/mail-intake/lib/credentials/index.html index fbc0e40..7a07da3 100644 --- a/mail-intake/lib/credentials/index.html +++ b/mail-intake/lib/credentials/index.html @@ -2112,10 +2112,92 @@ must be shared across multiple processes or nodes.

Initialize a Redis-backed credential store.

-

Callers supply all runtime dependencies: redis_client is an -initialized Redis client instance, key names the storage key, -serialize/deserialize are the encoding and decoding callables, -and ttl_seconds optionally limits credential lifetime.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
redis_client + Any + +
+

Initialized Redis client instance used for persistence.

+
+ 		+ required +
key + str + +
+

Storage key under which credentials are persisted.

+
+ 		+ required +
serialize + Callable[[T], bytes] + +
+

Callable that encodes credentials to bytes for storage.

+
+ 		+ required +
deserialize + Callable[[bytes], T] + +
+

Callable that decodes stored bytes back into credentials.

+
+ 		+ required +
ttl_seconds + int | None + +
+

Optional time-to-live in seconds after which stored +credentials expire automatically. None disables expiry.

+
+ 		+ None +
diff --git a/mail-intake/lib/credentials/redis/index.html b/mail-intake/lib/credentials/redis/index.html index 5841c77..f8d8a40 100644 --- a/mail-intake/lib/credentials/redis/index.html +++ b/mail-intake/lib/credentials/redis/index.html @@ -1408,10 +1408,92 @@ must be shared across multiple processes or nodes.

Initialize a Redis-backed credential store.

-

Callers supply all runtime dependencies: redis_client is an -initialized Redis client instance, key names the storage key, -serialize/deserialize are the encoding and decoding callables, -and ttl_seconds optionally limits credential lifetime.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
redis_client + Any + +
+

Initialized Redis client instance used for persistence.

+
+ 		+ required +
key + str + +
+

Storage key under which credentials are persisted.

+
+ 		+ required +
serialize + Callable[[T], bytes] + +
+

Callable that encodes credentials to bytes for storage.

+
+ 		+ required +
deserialize + Callable[[bytes], T] + +
+

Callable that decodes stored bytes back into credentials.

+
+ 		+ required +
ttl_seconds + int | None + +
+

Optional time-to-live in seconds after which stored +credentials expire automatically. None disables expiry.

+
+ 		+ None +
diff --git a/mail-intake/lib/mail_intake/credentials/index.html b/mail-intake/lib/mail_intake/credentials/index.html index ea0820d..8dfb105 100644 --- a/mail-intake/lib/mail_intake/credentials/index.html +++ b/mail-intake/lib/mail_intake/credentials/index.html @@ -1847,10 +1847,92 @@ must be shared across multiple processes or nodes.

Initialize a Redis-backed credential store.

-

Callers supply all runtime dependencies: redis_client is an -initialized Redis client instance, key names the storage key, -serialize/deserialize are the encoding and decoding callables, -and ttl_seconds optionally limits credential lifetime.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
redis_client + Any + +
+

Initialized Redis client instance used for persistence.

+
+ 		+ required +
key + str + +
+

Storage key under which credentials are persisted.

+
+ 		+ required +
serialize + Callable[[T], bytes] + +
+

Callable that encodes credentials to bytes for storage.

+
+ 		+ required +
deserialize + Callable[[bytes], T] + +
+

Callable that decodes stored bytes back into credentials.

+
+ 		+ required +
ttl_seconds + int | None + +
+

Optional time-to-live in seconds after which stored +credentials expire automatically. None disables expiry.

+
+ 		+ None +
diff --git a/mail-intake/lib/mail_intake/credentials/redis/index.html b/mail-intake/lib/mail_intake/credentials/redis/index.html index 5a8e4e3..b3c2beb 100644 --- a/mail-intake/lib/mail_intake/credentials/redis/index.html +++ b/mail-intake/lib/mail_intake/credentials/redis/index.html @@ -1266,10 +1266,92 @@ must be shared across multiple processes or nodes.

Initialize a Redis-backed credential store.

-

Callers supply all runtime dependencies: redis_client is an -initialized Redis client instance, key names the storage key, -serialize/deserialize are the encoding and decoding callables, -and ttl_seconds optionally limits credential lifetime.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
redis_client + Any + +
+

Initialized Redis client instance used for persistence.

+
+ 		+ required +
key + str + +
+

Storage key under which credentials are persisted.

+
+ 		+ required +
serialize + Callable[[T], bytes] + +
+

Callable that encodes credentials to bytes for storage.

+
+ 		+ required +
deserialize + Callable[[bytes], T] + +
+

Callable that decodes stored bytes back into credentials.

+
+ 		+ required +
ttl_seconds + int | None + +
+

Optional time-to-live in seconds after which stored +credentials expire automatically. None disables expiry.

+
+ 		+ None +
diff --git a/mail-intake/lib/search/search_index.json b/mail-intake/lib/search/search_index.json index 516426f..0fa9c07 100644 --- a/mail-intake/lib/search/search_index.json +++ b/mail-intake/lib/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"mail_intake","text":"
  • Mail Intake
"},{"location":"#mail_intake","title":"mail_intake","text":""},{"location":"#mail_intake--summary","title":"Summary","text":"

Mail Intake \u2014 provider-agnostic, read-only email ingestion framework.

Mail Intake is a contract-first library designed to ingest, parse, and normalize email data from external providers (such as Gmail) into clean, provider-agnostic domain models.

The library is intentionally structured around clear layers, each exposed as a first-class module at the package root:

  • adapters: Provider-specific access (e.g., Gmail).
  • auth: Authentication providers and credential lifecycle management.
  • credentials: Credential persistence abstractions and implementations.
  • parsers: Extraction and normalization of message content.
  • ingestion: Orchestration and high-level ingestion workflows.
  • models: Canonical, provider-agnostic data representations.
  • config: Explicit global configuration.
  • exceptions: Library-defined error hierarchy.

The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.

"},{"location":"#mail_intake--installation","title":"Installation","text":"

Install using pip:

pip install mail-intake\n

Or with Poetry:

poetry add mail-intake\n

Mail Intake is pure Python and has no runtime dependencies beyond those required by the selected provider (for example, Google APIs for Gmail).

"},{"location":"#mail_intake--quick-start","title":"Quick Start","text":"

Minimal Gmail ingestion example (local development):

from mail_intake.ingestion import MailIntakeReader\nfrom mail_intake.adapters import MailIntakeGmailAdapter\nfrom mail_intake.auth import MailIntakeGoogleAuth\nfrom mail_intake.credentials import PickleCredentialStore\n\nstore = PickleCredentialStore(path=\"token.pickle\")\n\nauth = MailIntakeGoogleAuth(\n    credentials_path=\"credentials.json\",\n    store=store,\n    scopes=[\"https://www.googleapis.com/auth/gmail.readonly\"],\n)\n\nadapter = MailIntakeGmailAdapter(auth_provider=auth)\nreader = MailIntakeReader(adapter)\n\nfor message in reader.iter_messages(\"from:recruiter@example.com\"):\n    print(message.subject, message.from_email)\n

Iterating over threads:

for thread in reader.iter_threads(\"subject:Interview\"):\n    print(thread.normalized_subject, len(thread.messages))\n
"},{"location":"#mail_intake--architecture","title":"Architecture","text":"

Mail Intake is designed to be extensible via public contracts exposed through its modules:

  • Users MAY implement their own mail adapters by subclassing adapters.MailIntakeAdapter.
  • Users MAY implement their own authentication providers by subclassing auth.MailIntakeAuthProvider[T].
  • Users MAY implement their own credential persistence layers by implementing credentials.CredentialStore[T].

Users SHOULD NOT subclass built-in adapter implementations. Built-in adapters (such as Gmail) are reference implementations and may change internally without notice.

Design Guarantees:

  • Read-only access: no mutation of provider state.
  • Provider-agnostic domain models.
  • Explicit configuration and dependency injection.
  • No implicit global state or environment reads.
  • Deterministic, testable behavior.
  • Distributed-safe authentication design.

Mail Intake favors correctness, clarity, and explicitness over convenience shortcuts.

Core Philosophy:

Mail Intake is built as a contract-first ingestion pipeline:

  1. Layered Decoupling: Adapters handle transport, Parsers handle format normalization, and Ingestion orchestrates.
  2. Provider Agnosticism: Domain models and core logic never depend on provider-specific (e.g., Gmail) API internals.
  3. Stateless Workflows: The library functions as a read-only pipe, ensuring side-effect-free ingestion.
"},{"location":"#mail_intake--public-api","title":"Public API","text":"

The supported public API consists of the following top-level modules:

  • mail_intake.ingestion
  • mail_intake.adapters
  • mail_intake.auth
  • mail_intake.credentials
  • mail_intake.parsers
  • mail_intake.models
  • mail_intake.config
  • mail_intake.exceptions

Classes and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.

"},{"location":"config/","title":"Config","text":""},{"location":"config/#mail_intake.config","title":"mail_intake.config","text":""},{"location":"config/#mail_intake.config--summary","title":"Summary","text":"

Global configuration models for Mail Intake.

This module defines the top-level configuration object used to control mail ingestion behavior across adapters, authentication providers, and ingestion workflows.

Configuration is intentionally explicit, immutable, and free of implicit environment reads to ensure predictability and testability.

"},{"location":"config/#mail_intake.config-classes","title":"Classes","text":""},{"location":"config/#mail_intake.config.MailIntakeConfig","title":"MailIntakeConfig dataclass","text":"
MailIntakeConfig(\n    provider: str = ...,\n    user_id: str = ...,\n    readonly: bool = ...,\n    credentials_path: str | None = ...,\n    token_path: str | None = ...,\n)\n

Global configuration for mail-intake.

Notes

Guarantees:

- This configuration is intentionally explicit and immutable.\n- No implicit environment reads or global state.\n- Explicit configuration over implicit defaults.\n- No direct environment or filesystem access.\n- This model is safe to pass across layers and suitable for\n  serialization.\n
"},{"location":"config/#mail_intake.config.MailIntakeConfig-attributes","title":"Attributes","text":""},{"location":"config/#mail_intake.config.MailIntakeConfig.credentials_path","title":"credentials_path class-attribute instance-attribute","text":"
credentials_path: str | None = None\n

Optional path to provider credentials configuration.

"},{"location":"config/#mail_intake.config.MailIntakeConfig.provider","title":"provider class-attribute instance-attribute","text":"
provider: str = 'gmail'\n

Identifier of the mail provider to use (e.g., \"gmail\").

"},{"location":"config/#mail_intake.config.MailIntakeConfig.readonly","title":"readonly class-attribute instance-attribute","text":"
readonly: bool = True\n

Whether ingestion should operate in read-only mode.

"},{"location":"config/#mail_intake.config.MailIntakeConfig.token_path","title":"token_path class-attribute instance-attribute","text":"
token_path: str | None = None\n

Optional path to persisted authentication tokens.

"},{"location":"config/#mail_intake.config.MailIntakeConfig.user_id","title":"user_id class-attribute instance-attribute","text":"
user_id: str = 'me'\n

Provider-specific user identifier. Defaults to the authenticated user.

"},{"location":"exceptions/","title":"Exceptions","text":""},{"location":"exceptions/#mail_intake.exceptions","title":"mail_intake.exceptions","text":""},{"location":"exceptions/#mail_intake.exceptions--summary","title":"Summary","text":"

Exception hierarchy for Mail Intake.

This module defines the canonical exception types used throughout the Mail Intake library.

All library-raised errors derive from MailIntakeError. Consumers are encouraged to catch this base type (or specific subclasses) rather than provider-specific or third-party exceptions.

"},{"location":"exceptions/#mail_intake.exceptions-classes","title":"Classes","text":""},{"location":"exceptions/#mail_intake.exceptions.MailIntakeAdapterError","title":"MailIntakeAdapterError","text":"

Bases: MailIntakeError

Errors raised by mail provider adapters.

Notes

Lifecycle:

- Raised when a provider adapter encounters API errors, transport\n  failures, or invalid provider responses.\n
"},{"location":"exceptions/#mail_intake.exceptions.MailIntakeAuthError","title":"MailIntakeAuthError","text":"

Bases: MailIntakeError

Authentication and credential-related failures.

Notes

Lifecycle:

- Raised when authentication providers are unable to acquire,\n  refresh, or persist valid credentials.\n
"},{"location":"exceptions/#mail_intake.exceptions.MailIntakeError","title":"MailIntakeError","text":"

Bases: Exception

Base exception for all Mail Intake errors.

Notes

Guarantees:

- This is the root of the Mail Intake exception hierarchy\n- All errors raised by the library must derive from this class\n- Consumers should generally catch this type when handling library-level failures\n
"},{"location":"exceptions/#mail_intake.exceptions.MailIntakeParsingError","title":"MailIntakeParsingError","text":"

Bases: MailIntakeError

Errors encountered while parsing message content.

Notes

Lifecycle:

- Raised when raw provider payloads cannot be interpreted or\n  normalized into internal domain models.\n
"},{"location":"adapters/","title":"Adapters","text":""},{"location":"adapters/#mail_intake.adapters","title":"mail_intake.adapters","text":""},{"location":"adapters/#mail_intake.adapters--summary","title":"Summary","text":"

Mail provider adapter implementations for Mail Intake.

This package contains adapter-layer implementations responsible for interfacing with external mail providers and exposing a normalized, provider-agnostic contract to the rest of the system.

Adapters in this package:

  • Implement the MailIntakeAdapter interface.
  • Encapsulate all provider-specific APIs and semantics.
  • Perform read-only access to mail data.
  • Return provider-native payloads without interpretation.

Provider-specific logic must not leak outside of adapter implementations. All parsings, normalizations, and transformations must be handled by downstream components.

"},{"location":"adapters/#mail_intake.adapters--public-api","title":"Public API","text":"
  • MailIntakeAdapter
  • MailIntakeGmailAdapter
"},{"location":"adapters/#mail_intake.adapters-classes","title":"Classes","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter","title":"MailIntakeAdapter","text":"

Bases: ABC

Base adapter interface for mail providers.

Notes

Guarantees:

- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\n

Lifecycle:

- Adapters are intentionally read-only and must not mutate provider state.\n
"},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter-functions","title":"Functions","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_message","title":"fetch_message abstractmethod","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full raw message by message identifier.

Parameters:

Name Type Description Default message_id str

Provider-specific message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).

"},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_thread","title":"fetch_thread abstractmethod","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full raw thread by thread identifier.

Parameters:

Name Type Description Default thread_id str

Provider-specific thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native thread payload.

"},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs abstractmethod","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over lightweight message references matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[dict[str, str]]

Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message and thread identifiers.

Notes

Guarantees:

- Implementations must yield dictionaries containing at least\n  `message_id` and `thread_id`.\n
Example

Typical yield:

{\n    \"message_id\": \"...\",\n    \"thread_id\": \"...\"\n}\n
"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"
MailIntakeGmailAdapter(\n    auth_provider: MailIntakeAuthProvider[Any],\n    user_id: str = \"me\",\n)\n

Bases: MailIntakeAdapter

Gmail read-only adapter.

This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.

Notes

Responsibilities:

- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\n

Constraints:

- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\n

Initialize the Gmail adapter.

Parameters:

Name Type Description Default auth_provider MailIntakeAuthProvider

Authentication provider capable of supplying valid Gmail API credentials.

required user_id str

Gmail user identifier. Defaults to \"me\".

'me'"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.service","title":"service property","text":"
service: Any\n

Lazily initialize and return the Gmail API service client.

Raises:

Type Description MailIntakeAdapterError

If the Gmail service cannot be initialized.

"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full Gmail message by message ID.

Parameters:

Name Type Description Default message_id str

Gmail message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail message payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full Gmail thread by thread ID.

Parameters:

Name Type Description Default thread_id str

Gmail thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail thread payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over message references matching the query.

Parameters:

Name Type Description Default query str

Gmail search query string.

required

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message_id and thread_id.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"adapters/base/","title":"Base","text":""},{"location":"adapters/base/#mail_intake.adapters.base","title":"mail_intake.adapters.base","text":""},{"location":"adapters/base/#mail_intake.adapters.base--summary","title":"Summary","text":"

Mail provider adapter contracts for Mail Intake.

This module defines the provider-agnostic adapter interface used for read-only mail ingestion.

Adapters encapsulate all provider-specific access logic and expose a minimal, normalized contract to the rest of the system. No provider-specific types or semantics should leak beyond implementations of this interface.

"},{"location":"adapters/base/#mail_intake.adapters.base-classes","title":"Classes","text":""},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter","title":"MailIntakeAdapter","text":"

Bases: ABC

Base adapter interface for mail providers.

Notes

Guarantees:

- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\n

Lifecycle:

- Adapters are intentionally read-only and must not mutate provider state.\n
"},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter-functions","title":"Functions","text":""},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_message","title":"fetch_message abstractmethod","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full raw message by message identifier.

Parameters:

Name Type Description Default message_id str

Provider-specific message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).

"},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_thread","title":"fetch_thread abstractmethod","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full raw thread by thread identifier.

Parameters:

Name Type Description Default thread_id str

Provider-specific thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native thread payload.

"},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs abstractmethod","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over lightweight message references matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[dict[str, str]]

Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message and thread identifiers.

Notes

Guarantees:

- Implementations must yield dictionaries containing at least\n  `message_id` and `thread_id`.\n
Example

Typical yield:

{\n    \"message_id\": \"...\",\n    \"thread_id\": \"...\"\n}\n
"},{"location":"adapters/gmail/","title":"Gmail","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail","title":"mail_intake.adapters.gmail","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail--summary","title":"Summary","text":"

Gmail adapter implementation for Mail Intake.

This module provides a Gmail-specific implementation of the MailIntakeAdapter contract.

It is the only place in the codebase where:

  • googleapiclient is imported.
  • Gmail REST API semantics are known.
  • Low-level .execute() calls are made.

All Gmail-specific behavior must be strictly contained within this module.

"},{"location":"adapters/gmail/#mail_intake.adapters.gmail-classes","title":"Classes","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"
MailIntakeGmailAdapter(\n    auth_provider: MailIntakeAuthProvider[Any],\n    user_id: str = \"me\",\n)\n

Bases: MailIntakeAdapter

Gmail read-only adapter.

This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.

Notes

Responsibilities:

- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\n

Constraints:

- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\n

Initialize the Gmail adapter.

Parameters:

Name Type Description Default auth_provider MailIntakeAuthProvider

Authentication provider capable of supplying valid Gmail API credentials.

required user_id str

Gmail user identifier. Defaults to \"me\".

'me'"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.service","title":"service property","text":"
service: Any\n

Lazily initialize and return the Gmail API service client.

Raises:

Type Description MailIntakeAdapterError

If the Gmail service cannot be initialized.

"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full Gmail message by message ID.

Parameters:

Name Type Description Default message_id str

Gmail message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail message payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full Gmail thread by thread ID.

Parameters:

Name Type Description Default thread_id str

Gmail thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail thread payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over message references matching the query.

Parameters:

Name Type Description Default query str

Gmail search query string.

required

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message_id and thread_id.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"auth/","title":"Auth","text":""},{"location":"auth/#mail_intake.auth","title":"mail_intake.auth","text":""},{"location":"auth/#mail_intake.auth--summary","title":"Summary","text":"

Authentication provider implementations for Mail Intake.

This package defines the authentication layer used by mail adapters to obtain provider-specific credentials.

It exposes:

  • A stable, provider-agnostic authentication contract.
  • Concrete authentication providers for supported platforms.

Authentication providers:

  • Are responsible for credential acquisition and lifecycle management.
  • Are intentionally decoupled from adapter logic.
  • May be extended by users to support additional providers.

Consumers should depend on the abstract interface and use concrete implementations only where explicitly required.

"},{"location":"auth/#mail_intake.auth--public-api","title":"Public API","text":"
  • MailIntakeAuthProvider
  • MailIntakeGoogleAuth
"},{"location":"auth/#mail_intake.auth-classes","title":"Classes","text":""},{"location":"auth/#mail_intake.auth.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"

Bases: ABC, Generic[T]

Abstract base class for authentication providers.

This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.

Notes

Responsibilities:

- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\n

Constraints:

- Mail adapters must treat returned credentials as opaque and\n  provider-specific.\n- Mail adapters rely only on the declared credential type expected\n  by the adapter.\n
"},{"location":"auth/#mail_intake.auth.MailIntakeAuthProvider-functions","title":"Functions","text":""},{"location":"auth/#mail_intake.auth.MailIntakeAuthProvider.get_credentials","title":"get_credentials abstractmethod","text":"
get_credentials() -> T\n

Retrieve valid, provider-specific credentials.

Returns:

Name Type Description T T

Credentials of type T suitable for immediate use by the corresponding mail adapter.

Raises:

Type Description Exception

An authentication-specific exception indicating that credentials could not be obtained or validated.

Notes

Guarantees:

- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n  authentication material.\n- Implementations must either return credentials of the declared\n  type `T` that are valid at the time of return or raise an exception.\n
"},{"location":"auth/#mail_intake.auth.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"
MailIntakeGoogleAuth(\n    credentials_path: str,\n    store: CredentialStore[Any],\n    scopes: Sequence[str],\n)\n

Bases: MailIntakeAuthProvider

Google OAuth provider for Gmail access.

This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.

Notes

Responsibilities:

- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\n

Guarantees:

- This class is synchronous by design and maintains a minimal\n  internal state.\n

Initialize the Google authentication provider.

Parameters:

Name Type Description Default credentials_path str

Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.

required store CredentialStore[Credentials]

Credential store responsible for persisting and retrieving Google OAuth credentials.

required scopes Sequence[str]

OAuth scopes required for Gmail access.

required"},{"location":"auth/#mail_intake.auth.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"auth/#mail_intake.auth.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"
get_credentials() -> Any\n

Retrieve valid Google OAuth credentials.

Returns:

Name Type Description Credentials Any

A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.

Raises:

Type Description MailIntakeAuthError

If credentials cannot be loaded, refreshed, or obtained via interactive authentication.

Notes

Lifecycle:

- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\n
"},{"location":"auth/base/","title":"Base","text":""},{"location":"auth/base/#mail_intake.auth.base","title":"mail_intake.auth.base","text":""},{"location":"auth/base/#mail_intake.auth.base--summary","title":"Summary","text":"

Authentication provider contracts for Mail Intake.

This module defines the authentication abstraction layer used by mail adapters to obtain provider-specific credentials.

Authentication concerns are intentionally decoupled from adapter logic. Adapters depend only on this interface and must not be aware of how credentials are acquired, refreshed, or persisted.

"},{"location":"auth/base/#mail_intake.auth.base-classes","title":"Classes","text":""},{"location":"auth/base/#mail_intake.auth.base.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"

Bases: ABC, Generic[T]

Abstract base class for authentication providers.

This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.

Notes

Responsibilities:

- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\n

Constraints:

- Mail adapters must treat returned credentials as opaque and\n  provider-specific.\n- Mail adapters rely only on the declared credential type expected\n  by the adapter.\n
"},{"location":"auth/base/#mail_intake.auth.base.MailIntakeAuthProvider-functions","title":"Functions","text":""},{"location":"auth/base/#mail_intake.auth.base.MailIntakeAuthProvider.get_credentials","title":"get_credentials abstractmethod","text":"
get_credentials() -> T\n

Retrieve valid, provider-specific credentials.

Returns:

Name Type Description T T

Credentials of type T suitable for immediate use by the corresponding mail adapter.

Raises:

Type Description Exception

An authentication-specific exception indicating that credentials could not be obtained or validated.

Notes

Guarantees:

- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n  authentication material.\n- Implementations must either return credentials of the declared\n  type `T` that are valid at the time of return or raise an exception.\n
"},{"location":"auth/google/","title":"Google","text":""},{"location":"auth/google/#mail_intake.auth.google","title":"mail_intake.auth.google","text":""},{"location":"auth/google/#mail_intake.auth.google--summary","title":"Summary","text":"

Google authentication provider implementation for Mail Intake.

This module provides a Google OAuth\u2013based authentication provider used primarily for Gmail access.

It encapsulates all Google-specific authentication concerns, including:

  • Credential loading and persistence.
  • Token refresh handling.
  • Interactive OAuth flow initiation.
  • Coordination with a credential persistence layer.

No Google authentication details should leak outside this module.

"},{"location":"auth/google/#mail_intake.auth.google-classes","title":"Classes","text":""},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"
MailIntakeGoogleAuth(\n    credentials_path: str,\n    store: CredentialStore[Any],\n    scopes: Sequence[str],\n)\n

Bases: MailIntakeAuthProvider

Google OAuth provider for Gmail access.

This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.

Notes

Responsibilities:

- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\n

Guarantees:

- This class is synchronous by design and maintains a minimal\n  internal state.\n

Initialize the Google authentication provider.

Parameters:

Name Type Description Default credentials_path str

Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.

required store CredentialStore[Credentials]

Credential store responsible for persisting and retrieving Google OAuth credentials.

required scopes Sequence[str]

OAuth scopes required for Gmail access.

required"},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"
get_credentials() -> Any\n

Retrieve valid Google OAuth credentials.

Returns:

Name Type Description Credentials Any

A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.

Raises:

Type Description MailIntakeAuthError

If credentials cannot be loaded, refreshed, or obtained via interactive authentication.

Notes

Lifecycle:

- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\n
"},{"location":"credentials/","title":"Credentials","text":""},{"location":"credentials/#mail_intake.credentials","title":"mail_intake.credentials","text":""},{"location":"credentials/#mail_intake.credentials--summary","title":"Summary","text":"

Credential persistence interfaces and implementations for Mail Intake.

This package defines the abstractions and concrete implementations used to persist authentication credentials across Mail Intake components.

The credential persistence layer is intentionally decoupled from authentication logic. Authentication providers are responsible for credential acquisition, validation, and refresh, while implementations within this package are responsible solely for storage and retrieval.

The package provides:

  • A generic CredentialStore abstraction defining the persistence contract.
  • Local filesystem\u2013based storage for development and single-node use.
  • Distributed, Redis-backed storage for production and scaled deployments.

Credential lifecycle management, interpretation, and security policy decisions remain the responsibility of authentication providers.

"},{"location":"credentials/#mail_intake.credentials--public-api","title":"Public API","text":"
  • CredentialStore
  • PickleCredentialStore
  • RedisCredentialStore
"},{"location":"credentials/#mail_intake.credentials-classes","title":"Classes","text":""},{"location":"credentials/#mail_intake.credentials.CredentialStore","title":"CredentialStore","text":"

Bases: ABC, Generic[T]

Abstract base class defining a generic persistence interface.

Used for authentication credentials across different backends.

Notes

Responsibilities:

- Provide persistent storage separating life-cycle management from\n  storage mechanics.\n- Keep implementation focused only on persistence.\n

Constraints:

- The store is intentionally agnostic to:\n    - The concrete credential type being stored.\n    - The serialization format used to persist credentials.\n    - The underlying storage backend or durability guarantees.\n
"},{"location":"credentials/#mail_intake.credentials.CredentialStore-functions","title":"Functions","text":""},{"location":"credentials/#mail_intake.credentials.CredentialStore.clear","title":"clear abstractmethod","text":"
clear() -> None\n

Remove any persisted credentials from the store.

Notes

Lifecycle:

- This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n- Must ensure that no stale authentication material remains accessible\n

Guarantees:

- Implementations should treat this operation as idempotent\n
"},{"location":"credentials/#mail_intake.credentials.CredentialStore.load","title":"load abstractmethod","text":"
load() -> T | None\n

Load previously persisted credentials.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are available and loadable; otherwise None.

Notes

Guarantees:

- Implementations should return `None` when no credentials are\n  present or when stored credentials cannot be successfully\n  decoded or deserialized.\n- The store must not attempt to validate, refresh, or otherwise\n  interpret the returned credentials.\n
"},{"location":"credentials/#mail_intake.credentials.CredentialStore.save","title":"save abstractmethod","text":"
save(credentials: T) -> None\n

Persist credentials to the underlying storage backend.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Lifecycle:

- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n

Responsibilities:

- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n
"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore","title":"PickleCredentialStore","text":"
PickleCredentialStore(path: str)\n

Bases: CredentialStore[T]

Filesystem-backed credential store using pickle serialization.

This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.

Notes

Guarantees:

- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\n

Constraints:

- Credential lifecycle management, validation, and refresh logic are\n  explicitly out of scope for this class.\n

Initialize a pickle-backed credential store.

Parameters:

Name Type Description Default path str

Filesystem path where credentials will be stored. The file will be created or overwritten as needed.

required"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove persisted credentials from the local filesystem.

Notes

Lifecycle:

- This method deletes the credential file if it exists and should be treated as an idempotent operation\n
"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from the local filesystem.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If the credential file does not exist or cannot be successfully\n  deserialized, this method returns `None`.\n- The store does not attempt to validate or interpret the\n  returned credentials.\n
"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to the local filesystem.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials at the configured path are overwritten\n
"},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore","title":"RedisCredentialStore","text":"
RedisCredentialStore(\n    redis_client: Any,\n    key: str,\n    serialize: Callable[[T], bytes],\n    deserialize: Callable[[bytes], T],\n    ttl_seconds: int | None = None,\n)\n

Bases: CredentialStore[T]

Redis-backed implementation of CredentialStore.

This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.

Notes

Responsibilities:

- This class is responsible only for persistence and retrieval.\n- It does not interpret, validate, refresh, or otherwise manage the\n  lifecycle of the credentials being stored.\n

Guarantees:

- The store is intentionally generic and delegates all serialization\n  concerns to caller-provided functions.\n- This avoids unsafe mechanisms such as `pickle` and allows\n  credential formats to be explicitly controlled and audited.\n

Initialize a Redis-backed credential store.

Callers supply all runtime dependencies: redis_client is an initialized Redis client instance, key names the storage key, serialize/deserialize are the encoding and decoding callables, and ttl_seconds optionally limits credential lifetime.

"},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove stored credentials from Redis.

Notes

Lifecycle:

- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\n
"},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from Redis.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If no value exists for the configured key, or if the stored\n  payload cannot be successfully deserialized, this method\n  returns `None`.\n- The store does not attempt to validate the returned\n  credentials or determine whether they are expired or\n  otherwise usable.\n
"},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to Redis.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials under the same key are overwritten\n- If a TTL is configured, the credentials will expire automatically after the specified duration\n
"},{"location":"credentials/pickle/","title":"Pickle","text":""},{"location":"credentials/pickle/#mail_intake.credentials.pickle","title":"mail_intake.credentials.pickle","text":""},{"location":"credentials/pickle/#mail_intake.credentials.pickle--summary","title":"Summary","text":"

Local filesystem\u2013based credential persistence for Mail Intake.

This module provides a file-backed implementation of the CredentialStore abstraction using Python's pickle module.

The pickle-based credential store is intended for local development, single-node deployments, and controlled environments where credentials do not need to be shared across processes or machines.

Due to the security and portability risks associated with pickle-based serialization, this implementation is not suitable for distributed or untrusted environments.

"},{"location":"credentials/pickle/#mail_intake.credentials.pickle-classes","title":"Classes","text":""},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore","title":"PickleCredentialStore","text":"
PickleCredentialStore(path: str)\n

Bases: CredentialStore[T]

Filesystem-backed credential store using pickle serialization.

This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.

Notes

Guarantees:

- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\n

Constraints:

- Credential lifecycle management, validation, and refresh logic are\n  explicitly out of scope for this class.\n

Initialize a pickle-backed credential store.

Parameters:

Name Type Description Default path str

Filesystem path where credentials will be stored. The file will be created or overwritten as needed.

required"},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove persisted credentials from the local filesystem.

Notes

Lifecycle:

- This method deletes the credential file if it exists and should be treated as an idempotent operation\n
"},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from the local filesystem.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If the credential file does not exist or cannot be successfully\n  deserialized, this method returns `None`.\n- The store does not attempt to validate or interpret the\n  returned credentials.\n
"},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to the local filesystem.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials at the configured path are overwritten\n
"},{"location":"credentials/redis/","title":"Redis","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis","title":"mail_intake.credentials.redis","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis--summary","title":"Summary","text":"

Redis-backed credential persistence for Mail Intake.

This module provides a Redis-based implementation of the CredentialStore abstraction, enabling credential persistence across distributed and horizontally scaled deployments.

The Redis credential store is designed for environments where authentication credentials must be shared safely across multiple processes, containers, or nodes, such as container orchestration platforms and microservice architectures.

Key characteristics:

  • Distributed-safe, shared storage using Redis.
  • Explicit, caller-defined serialization and deserialization.
  • No reliance on unsafe mechanisms such as pickle.
  • Optional time-to-live (TTL) support for automatic credential expiry.

This module is responsible solely for persistence concerns. Credential validation, refresh, rotation, and acquisition remain the responsibility of authentication provider implementations.

"},{"location":"credentials/redis/#mail_intake.credentials.redis-classes","title":"Classes","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore","title":"RedisCredentialStore","text":"
RedisCredentialStore(\n    redis_client: Any,\n    key: str,\n    serialize: Callable[[T], bytes],\n    deserialize: Callable[[bytes], T],\n    ttl_seconds: int | None = None,\n)\n

Bases: CredentialStore[T]

Redis-backed implementation of CredentialStore.

This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.

Notes

Responsibilities:

- This class is responsible only for persistence and retrieval.\n- It does not interpret, validate, refresh, or otherwise manage the\n  lifecycle of the credentials being stored.\n

Guarantees:

- The store is intentionally generic and delegates all serialization\n  concerns to caller-provided functions.\n- This avoids unsafe mechanisms such as `pickle` and allows\n  credential formats to be explicitly controlled and audited.\n

Initialize a Redis-backed credential store.

Callers supply all runtime dependencies: redis_client is an initialized Redis client instance, key names the storage key, serialize/deserialize are the encoding and decoding callables, and ttl_seconds optionally limits credential lifetime.

"},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove stored credentials from Redis.

Notes

Lifecycle:

- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\n
"},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from Redis.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If no value exists for the configured key, or if the stored\n  payload cannot be successfully deserialized, this method\n  returns `None`.\n- The store does not attempt to validate the returned\n  credentials or determine whether they are expired or\n  otherwise usable.\n
"},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to Redis.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials under the same key are overwritten\n- If a TTL is configured, the credentials will expire automatically after the specified duration\n
"},{"location":"credentials/store/","title":"Store","text":""},{"location":"credentials/store/#mail_intake.credentials.store","title":"mail_intake.credentials.store","text":""},{"location":"credentials/store/#mail_intake.credentials.store--summary","title":"Summary","text":"

Credential persistence abstractions for Mail Intake.

This module defines the generic persistence contract used to store and retrieve authentication credentials across Mail Intake components.

The CredentialStore abstraction establishes a strict separation between credential lifecycle management and credential storage. Authentication providers are responsible for acquiring, validating, refreshing, and revoking credentials, while concrete store implementations are responsible solely for persistence concerns.

By remaining agnostic to credential structure, serialization format, and storage backend, this module enables multiple persistence strategies\u2014such as local files, in-memory caches, distributed stores, or secrets managers\u2014without coupling authentication logic to any specific storage mechanism.

"},{"location":"credentials/store/#mail_intake.credentials.store-classes","title":"Classes","text":""},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore","title":"CredentialStore","text":"

Bases: ABC, Generic[T]

Abstract base class defining a generic persistence interface.

Used for authentication credentials across different backends.

Notes

Responsibilities:

- Provide persistent storage separating life-cycle management from\n  storage mechanics.\n- Keep implementation focused only on persistence.\n

Constraints:

- The store is intentionally agnostic to:\n    - The concrete credential type being stored.\n    - The serialization format used to persist credentials.\n    - The underlying storage backend or durability guarantees.\n
"},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore-functions","title":"Functions","text":""},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore.clear","title":"clear abstractmethod","text":"
clear() -> None\n

Remove any persisted credentials from the store.

Notes

Lifecycle:

- This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n- Must ensure that no stale authentication material remains accessible\n

Guarantees:

- Implementations should treat this operation as idempotent\n
"},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore.load","title":"load abstractmethod","text":"
load() -> T | None\n

Load previously persisted credentials.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are available and loadable; otherwise None.

Notes

Guarantees:

- Implementations should return `None` when no credentials are\n  present or when stored credentials cannot be successfully\n  decoded or deserialized.\n- The store must not attempt to validate, refresh, or otherwise\n  interpret the returned credentials.\n
"},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore.save","title":"save abstractmethod","text":"
save(credentials: T) -> None\n

Persist credentials to the underlying storage backend.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Lifecycle:

- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n

Responsibilities:

- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n
"},{"location":"ingestion/","title":"Ingestion","text":""},{"location":"ingestion/#mail_intake.ingestion","title":"mail_intake.ingestion","text":""},{"location":"ingestion/#mail_intake.ingestion--summary","title":"Summary","text":"

Mail ingestion orchestration for Mail Intake.

This package contains high-level ingestion components responsible for coordinating mail retrieval, parsing, normalization, and model construction.

It represents the top of the ingestion pipeline and is intended to be the primary interaction surface for library consumers.

Components in this package:

  • Are provider-agnostic.
  • Depend only on adapter and parser contracts.
  • Contain no provider-specific API logic.
  • Expose read-only ingestion workflows.

Consumers are expected to construct a mail adapter and pass it to the ingestion layer to begin processing messages and threads.

"},{"location":"ingestion/#mail_intake.ingestion--public-api","title":"Public API","text":"
  • MailIntakeReader
"},{"location":"ingestion/#mail_intake.ingestion-classes","title":"Classes","text":""},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader","title":"MailIntakeReader","text":"
MailIntakeReader(adapter: MailIntakeAdapter)\n

High-level read-only ingestion interface.

Notes

Responsibilities:

- This class is the primary entry point for consumers of the\n  Mail Intake library.\n- It orchestrates the full ingestion pipeline:\n    - Querying the adapter for message references.\n    - Fetching raw provider messages.\n    - Parsing and normalizing message data.\n    - Constructing domain models.\n

Constraints:

- This class is intentionally: Provider-agnostic, stateless beyond\n  iteration scope, read-only.\n

Initialize the mail reader.

Parameters:

Name Type Description Default adapter MailIntakeAdapter

Mail adapter implementation used to retrieve raw messages and threads from a mail provider.

required"},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader-functions","title":"Functions","text":""},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader.iter_messages","title":"iter_messages","text":"
iter_messages(query: str) -> Iterator[MailIntakeMessage]\n

Iterate over parsed messages matching a provider query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeMessage MailIntakeMessage

Fully parsed and normalized MailIntakeMessage instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

"},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader.iter_threads","title":"iter_threads","text":"
iter_threads(query: str) -> Iterator[MailIntakeThread]\n

Iterate over threads constructed from messages matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[MailIntakeThread]

Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.

Raises:

Type Description `MailIntakeParsingError`

If a message cannot be parsed.

Notes

Guarantees:

- Messages are grouped by `thread_id` and yielded as complete\n  thread objects containing all associated messages.\n
"},{"location":"ingestion/reader/","title":"Reader","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader","title":"mail_intake.ingestion.reader","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader--summary","title":"Summary","text":"

High-level mail ingestion orchestration for Mail Intake.

This module provides the primary, provider-agnostic entry point for reading and processing mail data.

It coordinates:

  • Mail adapter access.
  • Message and thread iteration.
  • Header and body parsing.
  • Normalization and model construction.

No provider-specific logic or API semantics are permitted in this layer.

"},{"location":"ingestion/reader/#mail_intake.ingestion.reader-classes","title":"Classes","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader","title":"MailIntakeReader","text":"
MailIntakeReader(adapter: MailIntakeAdapter)\n

High-level read-only ingestion interface.

Notes

Responsibilities:

- This class is the primary entry point for consumers of the\n  Mail Intake library.\n- It orchestrates the full ingestion pipeline:\n    - Querying the adapter for message references.\n    - Fetching raw provider messages.\n    - Parsing and normalizing message data.\n    - Constructing domain models.\n

Constraints:

- This class is intentionally: Provider-agnostic, stateless beyond\n  iteration scope, read-only.\n

Initialize the mail reader.

Parameters:

Name Type Description Default adapter MailIntakeAdapter

Mail adapter implementation used to retrieve raw messages and threads from a mail provider.

required"},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader-functions","title":"Functions","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_messages","title":"iter_messages","text":"
iter_messages(query: str) -> Iterator[MailIntakeMessage]\n

Iterate over parsed messages matching a provider query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeMessage MailIntakeMessage

Fully parsed and normalized MailIntakeMessage instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

"},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_threads","title":"iter_threads","text":"
iter_threads(query: str) -> Iterator[MailIntakeThread]\n

Iterate over threads constructed from messages matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[MailIntakeThread]

Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.

Raises:

Type Description `MailIntakeParsingError`

If a message cannot be parsed.

Notes

Guarantees:

- Messages are grouped by `thread_id` and yielded as complete\n  thread objects containing all associated messages.\n
"},{"location":"ingestion/reader/#mail_intake.ingestion.reader-functions","title":"Functions","text":""},{"location":"mail_intake/","title":"Mail Intake","text":"
  • Adapters
  • Auth
  • Config
  • Credentials
  • Exceptions
  • Ingestion
  • Models
  • Parsers
"},{"location":"mail_intake/#mail_intake","title":"mail_intake","text":""},{"location":"mail_intake/#mail_intake--summary","title":"Summary","text":"

Mail Intake \u2014 provider-agnostic, read-only email ingestion framework.

Mail Intake is a contract-first library designed to ingest, parse, and normalize email data from external providers (such as Gmail) into clean, provider-agnostic domain models.

The library is intentionally structured around clear layers, each exposed as a first-class module at the package root:

  • adapters: Provider-specific access (e.g., Gmail).
  • auth: Authentication providers and credential lifecycle management.
  • credentials: Credential persistence abstractions and implementations.
  • parsers: Extraction and normalization of message content.
  • ingestion: Orchestration and high-level ingestion workflows.
  • models: Canonical, provider-agnostic data representations.
  • config: Explicit global configuration.
  • exceptions: Library-defined error hierarchy.

The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.

"},{"location":"mail_intake/#mail_intake--installation","title":"Installation","text":"

Install using pip:

pip install mail-intake\n

Or with Poetry:

poetry add mail-intake\n

Mail Intake is pure Python and has no runtime dependencies beyond those required by the selected provider (for example, Google APIs for Gmail).

"},{"location":"mail_intake/#mail_intake--quick-start","title":"Quick Start","text":"

Minimal Gmail ingestion example (local development):

from mail_intake.ingestion import MailIntakeReader\nfrom mail_intake.adapters import MailIntakeGmailAdapter\nfrom mail_intake.auth import MailIntakeGoogleAuth\nfrom mail_intake.credentials import PickleCredentialStore\n\nstore = PickleCredentialStore(path=\"token.pickle\")\n\nauth = MailIntakeGoogleAuth(\n    credentials_path=\"credentials.json\",\n    store=store,\n    scopes=[\"https://www.googleapis.com/auth/gmail.readonly\"],\n)\n\nadapter = MailIntakeGmailAdapter(auth_provider=auth)\nreader = MailIntakeReader(adapter)\n\nfor message in reader.iter_messages(\"from:recruiter@example.com\"):\n    print(message.subject, message.from_email)\n

Iterating over threads:

for thread in reader.iter_threads(\"subject:Interview\"):\n    print(thread.normalized_subject, len(thread.messages))\n
"},{"location":"mail_intake/#mail_intake--architecture","title":"Architecture","text":"

Mail Intake is designed to be extensible via public contracts exposed through its modules:

  • Users MAY implement their own mail adapters by subclassing adapters.MailIntakeAdapter.
  • Users MAY implement their own authentication providers by subclassing auth.MailIntakeAuthProvider[T].
  • Users MAY implement their own credential persistence layers by implementing credentials.CredentialStore[T].

Users SHOULD NOT subclass built-in adapter implementations. Built-in adapters (such as Gmail) are reference implementations and may change internally without notice.

Design Guarantees:

  • Read-only access: no mutation of provider state.
  • Provider-agnostic domain models.
  • Explicit configuration and dependency injection.
  • No implicit global state or environment reads.
  • Deterministic, testable behavior.
  • Distributed-safe authentication design.

Mail Intake favors correctness, clarity, and explicitness over convenience shortcuts.

Core Philosophy:

Mail Intake is built as a contract-first ingestion pipeline:

  1. Layered Decoupling: Adapters handle transport, Parsers handle format normalization, and Ingestion orchestrates.
  2. Provider Agnosticism: Domain models and core logic never depend on provider-specific (e.g., Gmail) API internals.
  3. Stateless Workflows: The library functions as a read-only pipe, ensuring side-effect-free ingestion.
"},{"location":"mail_intake/#mail_intake--public-api","title":"Public API","text":"

The supported public API consists of the following top-level modules:

  • mail_intake.ingestion
  • mail_intake.adapters
  • mail_intake.auth
  • mail_intake.credentials
  • mail_intake.parsers
  • mail_intake.models
  • mail_intake.config
  • mail_intake.exceptions

Classes and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.

"},{"location":"mail_intake/config/","title":"Config","text":""},{"location":"mail_intake/config/#mail_intake.config","title":"mail_intake.config","text":""},{"location":"mail_intake/config/#mail_intake.config--summary","title":"Summary","text":"

Global configuration models for Mail Intake.

This module defines the top-level configuration object used to control mail ingestion behavior across adapters, authentication providers, and ingestion workflows.

Configuration is intentionally explicit, immutable, and free of implicit environment reads to ensure predictability and testability.

"},{"location":"mail_intake/config/#mail_intake.config-classes","title":"Classes","text":""},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig","title":"MailIntakeConfig dataclass","text":"
MailIntakeConfig(\n    provider: str = ...,\n    user_id: str = ...,\n    readonly: bool = ...,\n    credentials_path: str | None = ...,\n    token_path: str | None = ...,\n)\n

Global configuration for mail-intake.

Notes

Guarantees:

- This configuration is intentionally explicit and immutable.\n- No implicit environment reads or global state.\n- Explicit configuration over implicit defaults.\n- No direct environment or filesystem access.\n- This model is safe to pass across layers and suitable for\n  serialization.\n
"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig-attributes","title":"Attributes","text":""},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.credentials_path","title":"credentials_path class-attribute instance-attribute","text":"
credentials_path: str | None = None\n

Optional path to provider credentials configuration.

"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.provider","title":"provider class-attribute instance-attribute","text":"
provider: str = 'gmail'\n

Identifier of the mail provider to use (e.g., \"gmail\").

"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.readonly","title":"readonly class-attribute instance-attribute","text":"
readonly: bool = True\n

Whether ingestion should operate in read-only mode.

"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.token_path","title":"token_path class-attribute instance-attribute","text":"
token_path: str | None = None\n

Optional path to persisted authentication tokens.

"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.user_id","title":"user_id class-attribute instance-attribute","text":"
user_id: str = 'me'\n

Provider-specific user identifier. Defaults to the authenticated user.

"},{"location":"mail_intake/exceptions/","title":"Exceptions","text":""},{"location":"mail_intake/exceptions/#mail_intake.exceptions","title":"mail_intake.exceptions","text":""},{"location":"mail_intake/exceptions/#mail_intake.exceptions--summary","title":"Summary","text":"

Exception hierarchy for Mail Intake.

This module defines the canonical exception types used throughout the Mail Intake library.

All library-raised errors derive from MailIntakeError. Consumers are encouraged to catch this base type (or specific subclasses) rather than provider-specific or third-party exceptions.

"},{"location":"mail_intake/exceptions/#mail_intake.exceptions-classes","title":"Classes","text":""},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeAdapterError","title":"MailIntakeAdapterError","text":"

Bases: MailIntakeError

Errors raised by mail provider adapters.

Notes

Lifecycle:

- Raised when a provider adapter encounters API errors, transport\n  failures, or invalid provider responses.\n
"},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeAuthError","title":"MailIntakeAuthError","text":"

Bases: MailIntakeError

Authentication and credential-related failures.

Notes

Lifecycle:

- Raised when authentication providers are unable to acquire,\n  refresh, or persist valid credentials.\n
"},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeError","title":"MailIntakeError","text":"

Bases: Exception

Base exception for all Mail Intake errors.

Notes

Guarantees:

- This is the root of the Mail Intake exception hierarchy\n- All errors raised by the library must derive from this class\n- Consumers should generally catch this type when handling library-level failures\n
"},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeParsingError","title":"MailIntakeParsingError","text":"

Bases: MailIntakeError

Errors encountered while parsing message content.

Notes

Lifecycle:

- Raised when raw provider payloads cannot be interpreted or\n  normalized into internal domain models.\n
"},{"location":"mail_intake/adapters/","title":"Adapters","text":"
  • Base
  • Gmail
"},{"location":"mail_intake/adapters/#mail_intake.adapters","title":"mail_intake.adapters","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters--summary","title":"Summary","text":"

Mail provider adapter implementations for Mail Intake.

This package contains adapter-layer implementations responsible for interfacing with external mail providers and exposing a normalized, provider-agnostic contract to the rest of the system.

Adapters in this package:

  • Implement the MailIntakeAdapter interface.
  • Encapsulate all provider-specific APIs and semantics.
  • Perform read-only access to mail data.
  • Return provider-native payloads without interpretation.

Provider-specific logic must not leak outside of adapter implementations. All parsings, normalizations, and transformations must be handled by downstream components.

"},{"location":"mail_intake/adapters/#mail_intake.adapters--public-api","title":"Public API","text":"
  • MailIntakeAdapter
  • MailIntakeGmailAdapter
"},{"location":"mail_intake/adapters/#mail_intake.adapters-classes","title":"Classes","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter","title":"MailIntakeAdapter","text":"

Bases: ABC

Base adapter interface for mail providers.

Notes

Guarantees:

- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\n

Lifecycle:

- Adapters are intentionally read-only and must not mutate provider state.\n
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_message","title":"fetch_message abstractmethod","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full raw message by message identifier.

Parameters:

Name Type Description Default message_id str

Provider-specific message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_thread","title":"fetch_thread abstractmethod","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full raw thread by thread identifier.

Parameters:

Name Type Description Default thread_id str

Provider-specific thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native thread payload.

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs abstractmethod","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over lightweight message references matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[dict[str, str]]

Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message and thread identifiers.

Notes

Guarantees:

- Implementations must yield dictionaries containing at least\n  `message_id` and `thread_id`.\n
Example

Typical yield:

{\n    \"message_id\": \"...\",\n    \"thread_id\": \"...\"\n}\n
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"
MailIntakeGmailAdapter(\n    auth_provider: MailIntakeAuthProvider[Any],\n    user_id: str = \"me\",\n)\n

Bases: MailIntakeAdapter

Gmail read-only adapter.

This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.

Notes

Responsibilities:

- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\n

Constraints:

- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\n

Initialize the Gmail adapter.

Parameters:

Name Type Description Default auth_provider MailIntakeAuthProvider

Authentication provider capable of supplying valid Gmail API credentials.

required user_id str

Gmail user identifier. Defaults to \"me\".

'me'"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.service","title":"service property","text":"
service: Any\n

Lazily initialize and return the Gmail API service client.

Raises:

Type Description MailIntakeAdapterError

If the Gmail service cannot be initialized.

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full Gmail message by message ID.

Parameters:

Name Type Description Default message_id str

Gmail message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail message payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full Gmail thread by thread ID.

Parameters:

Name Type Description Default thread_id str

Gmail thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail thread payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over message references matching the query.

Parameters:

Name Type Description Default query str

Gmail search query string.

required

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message_id and thread_id.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"mail_intake/adapters/base/","title":"Base","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base","title":"mail_intake.adapters.base","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base--summary","title":"Summary","text":"

Mail provider adapter contracts for Mail Intake.

This module defines the provider-agnostic adapter interface used for read-only mail ingestion.

Adapters encapsulate all provider-specific access logic and expose a minimal, normalized contract to the rest of the system. No provider-specific types or semantics should leak beyond implementations of this interface.

"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base-classes","title":"Classes","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter","title":"MailIntakeAdapter","text":"

Bases: ABC

Base adapter interface for mail providers.

Notes

Guarantees:

- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\n

Lifecycle:

- Adapters are intentionally read-only and must not mutate provider state.\n
"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_message","title":"fetch_message abstractmethod","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full raw message by message identifier.

Parameters:

Name Type Description Default message_id str

Provider-specific message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).

"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_thread","title":"fetch_thread abstractmethod","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full raw thread by thread identifier.

Parameters:

Name Type Description Default thread_id str

Provider-specific thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native thread payload.

"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs abstractmethod","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over lightweight message references matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[dict[str, str]]

Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message and thread identifiers.

Notes

Guarantees:

- Implementations must yield dictionaries containing at least\n  `message_id` and `thread_id`.\n
Example

Typical yield:

{\n    \"message_id\": \"...\",\n    \"thread_id\": \"...\"\n}\n
"},{"location":"mail_intake/adapters/gmail/","title":"Gmail","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail","title":"mail_intake.adapters.gmail","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail--summary","title":"Summary","text":"

Gmail adapter implementation for Mail Intake.

This module provides a Gmail-specific implementation of the MailIntakeAdapter contract.

It is the only place in the codebase where:

  • googleapiclient is imported.
  • Gmail REST API semantics are known.
  • Low-level .execute() calls are made.

All Gmail-specific behavior must be strictly contained within this module.

"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail-classes","title":"Classes","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"
MailIntakeGmailAdapter(\n    auth_provider: MailIntakeAuthProvider[Any],\n    user_id: str = \"me\",\n)\n

Bases: MailIntakeAdapter

Gmail read-only adapter.

This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.

Notes

Responsibilities:

- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\n

Constraints:

- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\n

Initialize the Gmail adapter.

Parameters:

Name Type Description Default auth_provider MailIntakeAuthProvider

Authentication provider capable of supplying valid Gmail API credentials.

required user_id str

Gmail user identifier. Defaults to \"me\".

'me'"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.service","title":"service property","text":"
service: Any\n

Lazily initialize and return the Gmail API service client.

Raises:

Type Description MailIntakeAdapterError

If the Gmail service cannot be initialized.

"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full Gmail message by message ID.

Parameters:

Name Type Description Default message_id str

Gmail message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail message payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full Gmail thread by thread ID.

Parameters:

Name Type Description Default thread_id str

Gmail thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail thread payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over message references matching the query.

Parameters:

Name Type Description Default query str

Gmail search query string.

required

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message_id and thread_id.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"mail_intake/auth/","title":"Auth","text":"
  • Base
  • Google
"},{"location":"mail_intake/auth/#mail_intake.auth","title":"mail_intake.auth","text":""},{"location":"mail_intake/auth/#mail_intake.auth--summary","title":"Summary","text":"

Authentication provider implementations for Mail Intake.

This package defines the authentication layer used by mail adapters to obtain provider-specific credentials.

It exposes:

  • A stable, provider-agnostic authentication contract.
  • Concrete authentication providers for supported platforms.

Authentication providers:

  • Are responsible for credential acquisition and lifecycle management.
  • Are intentionally decoupled from adapter logic.
  • May be extended by users to support additional providers.

Consumers should depend on the abstract interface and use concrete implementations only where explicitly required.

"},{"location":"mail_intake/auth/#mail_intake.auth--public-api","title":"Public API","text":"
  • MailIntakeAuthProvider
  • MailIntakeGoogleAuth
"},{"location":"mail_intake/auth/#mail_intake.auth-classes","title":"Classes","text":""},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"

Bases: ABC, Generic[T]

Abstract base class for authentication providers.

This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.

Notes

Responsibilities:

- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\n

Constraints:

- Mail adapters must treat returned credentials as opaque and\n  provider-specific.\n- Mail adapters rely only on the declared credential type expected\n  by the adapter.\n
"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeAuthProvider-functions","title":"Functions","text":""},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeAuthProvider.get_credentials","title":"get_credentials abstractmethod","text":"
get_credentials() -> T\n

Retrieve valid, provider-specific credentials.

Returns:

Name Type Description T T

Credentials of type T suitable for immediate use by the corresponding mail adapter.

Raises:

Type Description Exception

An authentication-specific exception indicating that credentials could not be obtained or validated.

Notes

Guarantees:

- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n  authentication material.\n- Implementations must either return credentials of the declared\n  type `T` that are valid at the time of return or raise an exception.\n
"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"
MailIntakeGoogleAuth(\n    credentials_path: str,\n    store: CredentialStore[Any],\n    scopes: Sequence[str],\n)\n

Bases: MailIntakeAuthProvider

Google OAuth provider for Gmail access.

This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.

Notes

Responsibilities:

- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\n

Guarantees:

- This class is synchronous by design and maintains a minimal\n  internal state.\n

Initialize the Google authentication provider.

Parameters:

Name Type Description Default credentials_path str

Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.

required store CredentialStore[Credentials]

Credential store responsible for persisting and retrieving Google OAuth credentials.

required scopes Sequence[str]

OAuth scopes required for Gmail access.

required"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"
get_credentials() -> Any\n

Retrieve valid Google OAuth credentials.

Returns:

Name Type Description Credentials Any

A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.

Raises:

Type Description MailIntakeAuthError

If credentials cannot be loaded, refreshed, or obtained via interactive authentication.

Notes

Lifecycle:

- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\n
"},{"location":"mail_intake/auth/base/","title":"Base","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base","title":"mail_intake.auth.base","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base--summary","title":"Summary","text":"

Authentication provider contracts for Mail Intake.

This module defines the authentication abstraction layer used by mail adapters to obtain provider-specific credentials.

Authentication concerns are intentionally decoupled from adapter logic. Adapters depend only on this interface and must not be aware of how credentials are acquired, refreshed, or persisted.

"},{"location":"mail_intake/auth/base/#mail_intake.auth.base-classes","title":"Classes","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"

Bases: ABC, Generic[T]

Abstract base class for authentication providers.

This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.

Notes

Responsibilities:

- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\n

Constraints:

- Mail adapters must treat returned credentials as opaque and\n  provider-specific.\n- Mail adapters rely only on the declared credential type expected\n  by the adapter.\n
"},{"location":"mail_intake/auth/base/#mail_intake.auth.base.MailIntakeAuthProvider-functions","title":"Functions","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base.MailIntakeAuthProvider.get_credentials","title":"get_credentials abstractmethod","text":"
get_credentials() -> T\n

Retrieve valid, provider-specific credentials.

Returns:

Name Type Description T T

Credentials of type T suitable for immediate use by the corresponding mail adapter.

Raises:

Type Description Exception

An authentication-specific exception indicating that credentials could not be obtained or validated.

Notes

Guarantees:

- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n  authentication material.\n- Implementations must either return credentials of the declared\n  type `T` that are valid at the time of return or raise an exception.\n
"},{"location":"mail_intake/auth/google/","title":"Google","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google","title":"mail_intake.auth.google","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google--summary","title":"Summary","text":"

Google authentication provider implementation for Mail Intake.

This module provides a Google OAuth\u2013based authentication provider used primarily for Gmail access.

It encapsulates all Google-specific authentication concerns, including:

  • Credential loading and persistence.
  • Token refresh handling.
  • Interactive OAuth flow initiation.
  • Coordination with a credential persistence layer.

No Google authentication details should leak outside this module.

"},{"location":"mail_intake/auth/google/#mail_intake.auth.google-classes","title":"Classes","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"
MailIntakeGoogleAuth(\n    credentials_path: str,\n    store: CredentialStore[Any],\n    scopes: Sequence[str],\n)\n

Bases: MailIntakeAuthProvider

Google OAuth provider for Gmail access.

This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.

Notes

Responsibilities:

- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\n

Guarantees:

- This class is synchronous by design and maintains a minimal\n  internal state.\n

Initialize the Google authentication provider.

Parameters:

Name Type Description Default credentials_path str

Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.

required store CredentialStore[Credentials]

Credential store responsible for persisting and retrieving Google OAuth credentials.

required scopes Sequence[str]

OAuth scopes required for Gmail access.

required"},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"
get_credentials() -> Any\n

Retrieve valid Google OAuth credentials.

Returns:

Name Type Description Credentials Any

A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.

Raises:

Type Description MailIntakeAuthError

If credentials cannot be loaded, refreshed, or obtained via interactive authentication.

Notes

Lifecycle:

- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\n
"},{"location":"mail_intake/credentials/","title":"Credentials","text":"
  • Pickle
  • Redis
  • Store
"},{"location":"mail_intake/credentials/#mail_intake.credentials","title":"mail_intake.credentials","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials--summary","title":"Summary","text":"

Credential persistence interfaces and implementations for Mail Intake.

This package defines the abstractions and concrete implementations used to persist authentication credentials across Mail Intake components.

The credential persistence layer is intentionally decoupled from authentication logic. Authentication providers are responsible for credential acquisition, validation, and refresh, while implementations within this package are responsible solely for storage and retrieval.

The package provides:

  • A generic CredentialStore abstraction defining the persistence contract.
  • Local filesystem\u2013based storage for development and single-node use.
  • Distributed, Redis-backed storage for production and scaled deployments.

Credential lifecycle management, interpretation, and security policy decisions remain the responsibility of authentication providers.

"},{"location":"mail_intake/credentials/#mail_intake.credentials--public-api","title":"Public API","text":"
  • CredentialStore
  • PickleCredentialStore
  • RedisCredentialStore
"},{"location":"mail_intake/credentials/#mail_intake.credentials-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore","title":"CredentialStore","text":"

Bases: ABC, Generic[T]

Abstract base class defining a generic persistence interface.

Used for authentication credentials across different backends.

Notes

Responsibilities:

- Provide persistent storage separating life-cycle management from\n  storage mechanics.\n- Keep implementation focused only on persistence.\n

Constraints:

- The store is intentionally agnostic to:\n    - The concrete credential type being stored.\n    - The serialization format used to persist credentials.\n    - The underlying storage backend or durability guarantees.\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore.clear","title":"clear abstractmethod","text":"
clear() -> None\n

Remove any persisted credentials from the store.

Notes

Lifecycle:

- This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n- Must ensure that no stale authentication material remains accessible\n

Guarantees:

- Implementations should treat this operation as idempotent\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore.load","title":"load abstractmethod","text":"
load() -> T | None\n

Load previously persisted credentials.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are available and loadable; otherwise None.

Notes

Guarantees:

- Implementations should return `None` when no credentials are\n  present or when stored credentials cannot be successfully\n  decoded or deserialized.\n- The store must not attempt to validate, refresh, or otherwise\n  interpret the returned credentials.\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore.save","title":"save abstractmethod","text":"
save(credentials: T) -> None\n

Persist credentials to the underlying storage backend.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Lifecycle:

- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n

Responsibilities:

- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore","title":"PickleCredentialStore","text":"
PickleCredentialStore(path: str)\n

Bases: CredentialStore[T]

Filesystem-backed credential store using pickle serialization.

This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.

Notes

Guarantees:

- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\n

Constraints:

- Credential lifecycle management, validation, and refresh logic are\n  explicitly out of scope for this class.\n

Initialize a pickle-backed credential store.

Parameters:

Name Type Description Default path str

Filesystem path where credentials will be stored. The file will be created or overwritten as needed.

required"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove persisted credentials from the local filesystem.

Notes

Lifecycle:

- This method deletes the credential file if it exists and should be treated as an idempotent operation\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from the local filesystem.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If the credential file does not exist or cannot be successfully\n  deserialized, this method returns `None`.\n- The store does not attempt to validate or interpret the\n  returned credentials.\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to the local filesystem.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials at the configured path are overwritten\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore","title":"RedisCredentialStore","text":"
RedisCredentialStore(\n    redis_client: Any,\n    key: str,\n    serialize: Callable[[T], bytes],\n    deserialize: Callable[[bytes], T],\n    ttl_seconds: int | None = None,\n)\n

Bases: CredentialStore[T]

Redis-backed implementation of CredentialStore.

This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.

Notes

Responsibilities:

- This class is responsible only for persistence and retrieval.\n- It does not interpret, validate, refresh, or otherwise manage the\n  lifecycle of the credentials being stored.\n

Guarantees:

- The store is intentionally generic and delegates all serialization\n  concerns to caller-provided functions.\n- This avoids unsafe mechanisms such as `pickle` and allows\n  credential formats to be explicitly controlled and audited.\n

Initialize a Redis-backed credential store.

Callers supply all runtime dependencies: redis_client is an initialized Redis client instance, key names the storage key, serialize/deserialize are the encoding and decoding callables, and ttl_seconds optionally limits credential lifetime.

"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove stored credentials from Redis.

Notes

Lifecycle:

- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from Redis.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If no value exists for the configured key, or if the stored\n  payload cannot be successfully deserialized, this method\n  returns `None`.\n- The store does not attempt to validate the returned\n  credentials or determine whether they are expired or\n  otherwise usable.\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to Redis.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials under the same key are overwritten\n- If a TTL is configured, the credentials will expire automatically after the specified duration\n
"},{"location":"mail_intake/credentials/pickle/","title":"Pickle","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle","title":"mail_intake.credentials.pickle","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle--summary","title":"Summary","text":"

Local filesystem\u2013based credential persistence for Mail Intake.

This module provides a file-backed implementation of the CredentialStore abstraction using Python's pickle module.

The pickle-based credential store is intended for local development, single-node deployments, and controlled environments where credentials do not need to be shared across processes or machines.

Due to the security and portability risks associated with pickle-based serialization, this implementation is not suitable for distributed or untrusted environments.

"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore","title":"PickleCredentialStore","text":"
PickleCredentialStore(path: str)\n

Bases: CredentialStore[T]

Filesystem-backed credential store using pickle serialization.

This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.

Notes

Guarantees:

- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\n

Constraints:

- Credential lifecycle management, validation, and refresh logic are\n  explicitly out of scope for this class.\n

Initialize a pickle-backed credential store.

Parameters:

Name Type Description Default path str

Filesystem path where credentials will be stored. The file will be created or overwritten as needed.

required"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove persisted credentials from the local filesystem.

Notes

Lifecycle:

- This method deletes the credential file if it exists and should be treated as an idempotent operation\n
"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from the local filesystem.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If the credential file does not exist or cannot be successfully\n  deserialized, this method returns `None`.\n- The store does not attempt to validate or interpret the\n  returned credentials.\n
"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to the local filesystem.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials at the configured path are overwritten\n
"},{"location":"mail_intake/credentials/redis/","title":"Redis","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis","title":"mail_intake.credentials.redis","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis--summary","title":"Summary","text":"

Redis-backed credential persistence for Mail Intake.

This module provides a Redis-based implementation of the CredentialStore abstraction, enabling credential persistence across distributed and horizontally scaled deployments.

The Redis credential store is designed for environments where authentication credentials must be shared safely across multiple processes, containers, or nodes, such as container orchestration platforms and microservice architectures.

Key characteristics:

  • Distributed-safe, shared storage using Redis.
  • Explicit, caller-defined serialization and deserialization.
  • No reliance on unsafe mechanisms such as pickle.
  • Optional time-to-live (TTL) support for automatic credential expiry.

This module is responsible solely for persistence concerns. Credential validation, refresh, rotation, and acquisition remain the responsibility of authentication provider implementations.

"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore","title":"RedisCredentialStore","text":"
RedisCredentialStore(\n    redis_client: Any,\n    key: str,\n    serialize: Callable[[T], bytes],\n    deserialize: Callable[[bytes], T],\n    ttl_seconds: int | None = None,\n)\n

Bases: CredentialStore[T]

Redis-backed implementation of CredentialStore.

This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.

Notes

Responsibilities:

- This class is responsible only for persistence and retrieval.\n- It does not interpret, validate, refresh, or otherwise manage the\n  lifecycle of the credentials being stored.\n

Guarantees:

- The store is intentionally generic and delegates all serialization\n  concerns to caller-provided functions.\n- This avoids unsafe mechanisms such as `pickle` and allows\n  credential formats to be explicitly controlled and audited.\n

Initialize a Redis-backed credential store.

Callers supply all runtime dependencies: redis_client is an initialized Redis client instance, key names the storage key, serialize/deserialize are the encoding and decoding callables, and ttl_seconds optionally limits credential lifetime.

"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove stored credentials from Redis.

Notes

Lifecycle:

- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\n
"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from Redis.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If no value exists for the configured key, or if the stored\n  payload cannot be successfully deserialized, this method\n  returns `None`.\n- The store does not attempt to validate the returned\n  credentials or determine whether they are expired or\n  otherwise usable.\n
"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to Redis.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials under the same key are overwritten\n- If a TTL is configured, the credentials will expire automatically after the specified duration\n
"},{"location":"mail_intake/credentials/store/","title":"Store","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store","title":"mail_intake.credentials.store","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store--summary","title":"Summary","text":"

Credential persistence abstractions for Mail Intake.

This module defines the generic persistence contract used to store and retrieve authentication credentials across Mail Intake components.

The CredentialStore abstraction establishes a strict separation between credential lifecycle management and credential storage. Authentication providers are responsible for acquiring, validating, refreshing, and revoking credentials, while concrete store implementations are responsible solely for persistence concerns.

By remaining agnostic to credential structure, serialization format, and storage backend, this module enables multiple persistence strategies\u2014such as local files, in-memory caches, distributed stores, or secrets managers\u2014without coupling authentication logic to any specific storage mechanism.

"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore","title":"CredentialStore","text":"

Bases: ABC, Generic[T]

Abstract base class defining a generic persistence interface.

Used for authentication credentials across different backends.

Notes

Responsibilities:

- Provide persistent storage separating life-cycle management from\n  storage mechanics.\n- Keep implementation focused only on persistence.\n

Constraints:

- The store is intentionally agnostic to:\n    - The concrete credential type being stored.\n    - The serialization format used to persist credentials.\n    - The underlying storage backend or durability guarantees.\n
"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore.clear","title":"clear abstractmethod","text":"
clear() -> None\n

Remove any persisted credentials from the store.

Notes

Lifecycle:

- This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n- Must ensure that no stale authentication material remains accessible\n

Guarantees:

- Implementations should treat this operation as idempotent\n
"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore.load","title":"load abstractmethod","text":"
load() -> T | None\n

Load previously persisted credentials.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are available and loadable; otherwise None.

Notes

Guarantees:

- Implementations should return `None` when no credentials are\n  present or when stored credentials cannot be successfully\n  decoded or deserialized.\n- The store must not attempt to validate, refresh, or otherwise\n  interpret the returned credentials.\n
"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore.save","title":"save abstractmethod","text":"
save(credentials: T) -> None\n

Persist credentials to the underlying storage backend.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Lifecycle:

- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n

Responsibilities:

- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n
"},{"location":"mail_intake/ingestion/","title":"Ingestion","text":"
  • Reader
"},{"location":"mail_intake/ingestion/#mail_intake.ingestion","title":"mail_intake.ingestion","text":""},{"location":"mail_intake/ingestion/#mail_intake.ingestion--summary","title":"Summary","text":"

Mail ingestion orchestration for Mail Intake.

This package contains high-level ingestion components responsible for coordinating mail retrieval, parsing, normalization, and model construction.

It represents the top of the ingestion pipeline and is intended to be the primary interaction surface for library consumers.

Components in this package:

  • Are provider-agnostic.
  • Depend only on adapter and parser contracts.
  • Contain no provider-specific API logic.
  • Expose read-only ingestion workflows.

Consumers are expected to construct a mail adapter and pass it to the ingestion layer to begin processing messages and threads.

"},{"location":"mail_intake/ingestion/#mail_intake.ingestion--public-api","title":"Public API","text":"
  • MailIntakeReader
"},{"location":"mail_intake/ingestion/#mail_intake.ingestion-classes","title":"Classes","text":""},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader","title":"MailIntakeReader","text":"
MailIntakeReader(adapter: MailIntakeAdapter)\n

High-level read-only ingestion interface.

Notes

Responsibilities:

- This class is the primary entry point for consumers of the\n  Mail Intake library.\n- It orchestrates the full ingestion pipeline:\n    - Querying the adapter for message references.\n    - Fetching raw provider messages.\n    - Parsing and normalizing message data.\n    - Constructing domain models.\n

Constraints:

- This class is intentionally: Provider-agnostic, stateless beyond\n  iteration scope, read-only.\n

Initialize the mail reader.

Parameters:

Name Type Description Default adapter MailIntakeAdapter

Mail adapter implementation used to retrieve raw messages and threads from a mail provider.

required"},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader-functions","title":"Functions","text":""},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader.iter_messages","title":"iter_messages","text":"
iter_messages(query: str) -> Iterator[MailIntakeMessage]\n

Iterate over parsed messages matching a provider query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeMessage MailIntakeMessage

Fully parsed and normalized MailIntakeMessage instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

"},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader.iter_threads","title":"iter_threads","text":"
iter_threads(query: str) -> Iterator[MailIntakeThread]\n

Iterate over threads constructed from messages matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[MailIntakeThread]

Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.

Raises:

Type Description `MailIntakeParsingError`

If a message cannot be parsed.

Notes

Guarantees:

- Messages are grouped by `thread_id` and yielded as complete\n  thread objects containing all associated messages.\n
"},{"location":"mail_intake/ingestion/reader/","title":"Reader","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader","title":"mail_intake.ingestion.reader","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader--summary","title":"Summary","text":"

High-level mail ingestion orchestration for Mail Intake.

This module provides the primary, provider-agnostic entry point for reading and processing mail data.

It coordinates:

  • Mail adapter access.
  • Message and thread iteration.
  • Header and body parsing.
  • Normalization and model construction.

No provider-specific logic or API semantics are permitted in this layer.

"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader-classes","title":"Classes","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader","title":"MailIntakeReader","text":"
MailIntakeReader(adapter: MailIntakeAdapter)\n

High-level read-only ingestion interface.

Notes

Responsibilities:

- This class is the primary entry point for consumers of the\n  Mail Intake library.\n- It orchestrates the full ingestion pipeline:\n    - Querying the adapter for message references.\n    - Fetching raw provider messages.\n    - Parsing and normalizing message data.\n    - Constructing domain models.\n

Constraints:

- This class is intentionally: Provider-agnostic, stateless beyond\n  iteration scope, read-only.\n

Initialize the mail reader.

Parameters:

Name Type Description Default adapter MailIntakeAdapter

Mail adapter implementation used to retrieve raw messages and threads from a mail provider.

required"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader-functions","title":"Functions","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_messages","title":"iter_messages","text":"
iter_messages(query: str) -> Iterator[MailIntakeMessage]\n

Iterate over parsed messages matching a provider query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeMessage MailIntakeMessage

Fully parsed and normalized MailIntakeMessage instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_threads","title":"iter_threads","text":"
iter_threads(query: str) -> Iterator[MailIntakeThread]\n

Iterate over threads constructed from messages matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[MailIntakeThread]

Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.

Raises:

Type Description `MailIntakeParsingError`

If a message cannot be parsed.

Notes

Guarantees:

- Messages are grouped by `thread_id` and yielded as complete\n  thread objects containing all associated messages.\n
"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader-functions","title":"Functions","text":""},{"location":"mail_intake/models/","title":"Models","text":"
  • Message
  • Thread
"},{"location":"mail_intake/models/#mail_intake.models","title":"mail_intake.models","text":""},{"location":"mail_intake/models/#mail_intake.models--summary","title":"Summary","text":"

Domain models for Mail Intake.

This package defines the canonical, provider-agnostic data models used throughout the Mail Intake ingestion pipeline.

Models in this package:

  • Represent fully parsed and normalized mail data.
  • Are safe to persist, serialize, and index.
  • Contain no provider-specific payloads or API semantics.
  • Serve as stable inputs for downstream processing and analysis.

These models form the core internal data contract of the library.

"},{"location":"mail_intake/models/#mail_intake.models--public-api","title":"Public API","text":"
  • MailIntakeMessage
  • MailIntakeThread
"},{"location":"mail_intake/models/#mail_intake.models-classes","title":"Classes","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage","title":"MailIntakeMessage dataclass","text":"
MailIntakeMessage(\n    message_id: str,\n    thread_id: str,\n    timestamp: datetime,\n    from_email: str,\n    from_name: str | None,\n    subject: str,\n    body_text: str,\n    snippet: str,\n    raw_headers: dict[str, str],\n)\n

Canonical internal representation of a single email message.

Notes

Guarantees:

- This model represents a fully parsed and normalized email message.\n- It is intentionally provider-agnostic and suitable for\n  persistence, indexing, and downstream processing.\n

Constraints:

- No provider-specific identifiers, payloads, or API semantics\n  should appear in this model.\n
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage-attributes","title":"Attributes","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.body_text","title":"body_text instance-attribute","text":"
body_text: str\n

Extracted plain-text body content of the message.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.from_email","title":"from_email instance-attribute","text":"
from_email: str\n

Sender email address.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.from_name","title":"from_name instance-attribute","text":"
from_name: str | None\n

Optional human-readable sender name.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.message_id","title":"message_id instance-attribute","text":"
message_id: str\n

Provider-specific message identifier.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.raw_headers","title":"raw_headers instance-attribute","text":"
raw_headers: dict[str, str]\n

Normalized mapping of message headers (header name \u2192 value).

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.snippet","title":"snippet instance-attribute","text":"
snippet: str\n

Short provider-supplied preview snippet of the message.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.subject","title":"subject instance-attribute","text":"
subject: str\n

Raw subject line of the message.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier to which this message belongs.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.timestamp","title":"timestamp instance-attribute","text":"
timestamp: datetime\n

Message timestamp as a timezone-naive UTC datetime.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread","title":"MailIntakeThread dataclass","text":"
MailIntakeThread(\n    thread_id: str,\n    normalized_subject: str,\n    participants: set[str] = ...,\n    messages: list[MailIntakeMessage] = ...,\n    last_activity_at: datetime | None = ...,\n)\n

Canonical internal representation of an email thread.

Notes

Guarantees:

- A thread groups multiple related messages under a single subject\n  and participant set.\n- It is designed to support reasoning over conversational context\n  such as job applications, interviews, follow-ups, and ongoing discussions.\n- This model is provider-agnostic and safe to persist.\n
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread-attributes","title":"Attributes","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.last_activity_at","title":"last_activity_at class-attribute instance-attribute","text":"
last_activity_at: datetime | None = None\n

Timestamp of the most recent message in the thread.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.messages","title":"messages class-attribute instance-attribute","text":"
messages: list[MailIntakeMessage] = field(\n    default_factory=list\n)\n

Ordered list of messages belonging to this thread.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.normalized_subject","title":"normalized_subject instance-attribute","text":"
normalized_subject: str\n

Normalized subject line used to group related messages.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.participants","title":"participants class-attribute instance-attribute","text":"
participants: set[str] = field(default_factory=set)\n

Set of unique participant email addresses observed in the thread.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread-functions","title":"Functions","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.add_message","title":"add_message","text":"
add_message(message: MailIntakeMessage) -> None\n

Add a message to the thread and update derived fields.

Parameters:

Name Type Description Default message MailIntakeMessage

Parsed mail message to add to the thread.

required Notes

Responsibilities:

- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\n
"},{"location":"mail_intake/models/message/","title":"Message","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message","title":"mail_intake.models.message","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message--summary","title":"Summary","text":"

Message domain models for Mail Intake.

This module defines the canonical, provider-agnostic representation of an individual email message as used internally by the Mail Intake ingestion pipeline.

Models in this module are safe to persist and must not contain any provider-specific fields or semantics.

"},{"location":"mail_intake/models/message/#mail_intake.models.message-classes","title":"Classes","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage","title":"MailIntakeMessage dataclass","text":"
MailIntakeMessage(\n    message_id: str,\n    thread_id: str,\n    timestamp: datetime,\n    from_email: str,\n    from_name: str | None,\n    subject: str,\n    body_text: str,\n    snippet: str,\n    raw_headers: dict[str, str],\n)\n

Canonical internal representation of a single email message.

Notes

Guarantees:

- This model represents a fully parsed and normalized email message.\n- It is intentionally provider-agnostic and suitable for\n  persistence, indexing, and downstream processing.\n

Constraints:

- No provider-specific identifiers, payloads, or API semantics\n  should appear in this model.\n
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage-attributes","title":"Attributes","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.body_text","title":"body_text instance-attribute","text":"
body_text: str\n

Extracted plain-text body content of the message.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.from_email","title":"from_email instance-attribute","text":"
from_email: str\n

Sender email address.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.from_name","title":"from_name instance-attribute","text":"
from_name: str | None\n

Optional human-readable sender name.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.message_id","title":"message_id instance-attribute","text":"
message_id: str\n

Provider-specific message identifier.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.raw_headers","title":"raw_headers instance-attribute","text":"
raw_headers: dict[str, str]\n

Normalized mapping of message headers (header name \u2192 value).

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.snippet","title":"snippet instance-attribute","text":"
snippet: str\n

Short provider-supplied preview snippet of the message.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.subject","title":"subject instance-attribute","text":"
subject: str\n

Raw subject line of the message.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier to which this message belongs.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.timestamp","title":"timestamp instance-attribute","text":"
timestamp: datetime\n

Message timestamp as a timezone-naive UTC datetime.

"},{"location":"mail_intake/models/thread/","title":"Thread","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread","title":"mail_intake.models.thread","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread--summary","title":"Summary","text":"

Thread domain models for Mail Intake.

This module defines the canonical, provider-agnostic representation of an email thread as used internally by the Mail Intake ingestion pipeline.

Threads group related messages and serve as the primary unit of reasoning for higher-level correspondence workflows.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread-classes","title":"Classes","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread","title":"MailIntakeThread dataclass","text":"
MailIntakeThread(\n    thread_id: str,\n    normalized_subject: str,\n    participants: set[str] = ...,\n    messages: list[MailIntakeMessage] = ...,\n    last_activity_at: datetime | None = ...,\n)\n

Canonical internal representation of an email thread.

Notes

Guarantees:

- A thread groups multiple related messages under a single subject\n  and participant set.\n- It is designed to support reasoning over conversational context\n  such as job applications, interviews, follow-ups, and ongoing discussions.\n- This model is provider-agnostic and safe to persist.\n
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread-attributes","title":"Attributes","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.last_activity_at","title":"last_activity_at class-attribute instance-attribute","text":"
last_activity_at: datetime | None = None\n

Timestamp of the most recent message in the thread.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.messages","title":"messages class-attribute instance-attribute","text":"
messages: list[MailIntakeMessage] = field(\n    default_factory=list\n)\n

Ordered list of messages belonging to this thread.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.normalized_subject","title":"normalized_subject instance-attribute","text":"
normalized_subject: str\n

Normalized subject line used to group related messages.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.participants","title":"participants class-attribute instance-attribute","text":"
participants: set[str] = field(default_factory=set)\n

Set of unique participant email addresses observed in the thread.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread-functions","title":"Functions","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.add_message","title":"add_message","text":"
add_message(message: MailIntakeMessage) -> None\n

Add a message to the thread and update derived fields.

Parameters:

Name Type Description Default message MailIntakeMessage

Parsed mail message to add to the thread.

required Notes

Responsibilities:

- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\n
"},{"location":"mail_intake/parsers/","title":"Parsers","text":"
  • Body
  • Headers
  • Subject
"},{"location":"mail_intake/parsers/#mail_intake.parsers","title":"mail_intake.parsers","text":""},{"location":"mail_intake/parsers/#mail_intake.parsers--summary","title":"Summary","text":"

Message parsing utilities for Mail Intake.

This package contains provider-aware but adapter-agnostic parsing helpers used to extract and normalize structured information from raw mail payloads.

Parsers in this package are responsible for:

  • Interpreting provider-native message structures.
  • Extracting meaningful fields such as headers, body text, and subjects.
  • Normalizing data into consistent internal representations.

This package does not:

  • Perform network or IO operations.
  • Contain provider API logic.
  • Construct domain models directly.

Parsing functions are designed to be composable and are orchestrated by the ingestion layer.

"},{"location":"mail_intake/parsers/#mail_intake.parsers--public-api","title":"Public API","text":"
  • extract_body
  • parse_headers
  • extract_sender
  • normalize_subject
"},{"location":"mail_intake/parsers/#mail_intake.parsers-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/#mail_intake.parsers.extract_body","title":"extract_body","text":"
extract_body(payload: dict[str, Any]) -> str\n

Extract the best-effort message body from a Gmail payload.

Priority:

  1. text/plain
  2. text/html (stripped to text)
  3. Single-part body
  4. Empty string (if nothing usable found)

Parameters:

Name Type Description Default payload dict[str, Any]

Provider-native message payload dictionary.

required

Returns:

Name Type Description str str

Extracted plain-text message body.

"},{"location":"mail_intake/parsers/#mail_intake.parsers.extract_sender","title":"extract_sender","text":"
extract_sender(\n    headers: dict[str, str],\n) -> tuple[str, str | None]\n

Extract sender email and optional display name from headers.

Parameters:

Name Type Description Default headers dict[str, str]

Normalized header dictionary as returned by parse_headers().

required

Returns:

Type Description tuple[str, str | None]

tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.

Notes

Responsibilities:

- This function parses the `From` header and attempts to extract\n  sender email address and optional human-readable display name.\n
Example

Typical values:

  • \"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")
  • \"john@example.com\" -> (\"john@example.com\", None)
"},{"location":"mail_intake/parsers/#mail_intake.parsers.normalize_subject","title":"normalize_subject","text":"
normalize_subject(subject: str) -> str\n

Normalize an email subject for thread-level comparison.

Parameters:

Name Type Description Default subject str

Raw subject line from a message header.

required

Returns:

Name Type Description str str

Normalized subject string suitable for thread grouping.

Notes

Responsibilities:

- Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n- Repeats prefix stripping to handle stacked prefixes.\n- Collapses excessive whitespace.\n- Preserves original casing (no lowercasing).\n

Guarantees:

- This function is intentionally conservative and avoids aggressive\n  transformations that could alter the semantic meaning of the subject.\n
"},{"location":"mail_intake/parsers/#mail_intake.parsers.parse_headers","title":"parse_headers","text":"
parse_headers(\n    raw_headers: list[dict[str, str]],\n) -> dict[str, str]\n

Convert a list of Gmail-style headers into a normalized dict.

Parameters:

Name Type Description Default raw_headers list[dict[str, str]]

List of header dictionaries, each containing name and value keys.

required

Returns:

Type Description dict[str, str]

dict[str, str]: Dictionary mapping lowercase header names to stripped values.

Notes

Guarantees:

- Provider payloads (such as Gmail) typically represent headers as a\n  list of name/value mappings.\n- This function normalizes them into a case-insensitive dictionary\n  keyed by lowercase header names.\n
Example

Typical usage:

Input:\n    [\n        {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n        {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n    ]\n\nOutput:\n    {\n        \"from\": \"John Doe <john@example.com>\",\n        \"subject\": \"Re: Interview Update\",\n    }\n
"},{"location":"mail_intake/parsers/body/","title":"Body","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body","title":"mail_intake.parsers.body","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body--summary","title":"Summary","text":"

Message body extraction utilities for Mail Intake.

This module contains helper functions for extracting a best-effort plain-text body from provider-native message payloads.

The logic is intentionally tolerant of malformed or partial data and prefers human-readable text over fidelity to original formatting.

"},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body-classes","title":"Classes","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body.extract_body","title":"extract_body","text":"
extract_body(payload: dict[str, Any]) -> str\n

Extract the best-effort message body from a Gmail payload.

Priority:

  1. text/plain
  2. text/html (stripped to text)
  3. Single-part body
  4. Empty string (if nothing usable found)

Parameters:

Name Type Description Default payload dict[str, Any]

Provider-native message payload dictionary.

required

Returns:

Name Type Description str str

Extracted plain-text message body.

"},{"location":"mail_intake/parsers/headers/","title":"Headers","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers","title":"mail_intake.parsers.headers","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers--summary","title":"Summary","text":"

Message header parsing utilities for Mail Intake.

This module provides helper functions for normalizing and extracting useful information from provider-native message headers.

The functions here are intentionally simple and tolerant of malformed or incomplete header data.

"},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers.extract_sender","title":"extract_sender","text":"
extract_sender(\n    headers: dict[str, str],\n) -> tuple[str, str | None]\n

Extract sender email and optional display name from headers.

Parameters:

Name Type Description Default headers dict[str, str]

Normalized header dictionary as returned by parse_headers().

required

Returns:

Type Description tuple[str, str | None]

tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.

Notes

Responsibilities:

- This function parses the `From` header and attempts to extract\n  sender email address and optional human-readable display name.\n
Example

Typical values:

  • \"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")
  • \"john@example.com\" -> (\"john@example.com\", None)
"},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers.parse_headers","title":"parse_headers","text":"
parse_headers(\n    raw_headers: list[dict[str, str]],\n) -> dict[str, str]\n

Convert a list of Gmail-style headers into a normalized dict.

Parameters:

Name Type Description Default raw_headers list[dict[str, str]]

List of header dictionaries, each containing name and value keys.

required

Returns:

Type Description dict[str, str]

dict[str, str]: Dictionary mapping lowercase header names to stripped values.

Notes

Guarantees:

- Provider payloads (such as Gmail) typically represent headers as a\n  list of name/value mappings.\n- This function normalizes them into a case-insensitive dictionary\n  keyed by lowercase header names.\n
Example

Typical usage:

Input:\n    [\n        {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n        {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n    ]\n\nOutput:\n    {\n        \"from\": \"John Doe <john@example.com>\",\n        \"subject\": \"Re: Interview Update\",\n    }\n
"},{"location":"mail_intake/parsers/subject/","title":"Subject","text":""},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject","title":"mail_intake.parsers.subject","text":""},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject--summary","title":"Summary","text":"

Subject line normalization utilities for Mail Intake.

This module provides helper functions for normalizing email subject lines to enable reliable thread-level comparison and grouping.

Normalization is intentionally conservative to avoid altering semantic meaning while removing common reply and forward prefixes.

"},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject.normalize_subject","title":"normalize_subject","text":"
normalize_subject(subject: str) -> str\n

Normalize an email subject for thread-level comparison.

Parameters:

Name Type Description Default subject str

Raw subject line from a message header.

required

Returns:

Name Type Description str str

Normalized subject string suitable for thread grouping.

Notes

Responsibilities:

- Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n- Repeats prefix stripping to handle stacked prefixes.\n- Collapses excessive whitespace.\n- Preserves original casing (no lowercasing).\n

Guarantees:

- This function is intentionally conservative and avoids aggressive\n  transformations that could alter the semantic meaning of the subject.\n
"},{"location":"models/","title":"Models","text":""},{"location":"models/#mail_intake.models","title":"mail_intake.models","text":""},{"location":"models/#mail_intake.models--summary","title":"Summary","text":"

Domain models for Mail Intake.

This package defines the canonical, provider-agnostic data models used throughout the Mail Intake ingestion pipeline.

Models in this package:

  • Represent fully parsed and normalized mail data.
  • Are safe to persist, serialize, and index.
  • Contain no provider-specific payloads or API semantics.
  • Serve as stable inputs for downstream processing and analysis.

These models form the core internal data contract of the library.

"},{"location":"models/#mail_intake.models--public-api","title":"Public API","text":"
  • MailIntakeMessage
  • MailIntakeThread
"},{"location":"models/#mail_intake.models-classes","title":"Classes","text":""},{"location":"models/#mail_intake.models.MailIntakeMessage","title":"MailIntakeMessage dataclass","text":"
MailIntakeMessage(\n    message_id: str,\n    thread_id: str,\n    timestamp: datetime,\n    from_email: str,\n    from_name: str | None,\n    subject: str,\n    body_text: str,\n    snippet: str,\n    raw_headers: dict[str, str],\n)\n

Canonical internal representation of a single email message.

Notes

Guarantees:

- This model represents a fully parsed and normalized email message.\n- It is intentionally provider-agnostic and suitable for\n  persistence, indexing, and downstream processing.\n

Constraints:

- No provider-specific identifiers, payloads, or API semantics\n  should appear in this model.\n
"},{"location":"models/#mail_intake.models.MailIntakeMessage-attributes","title":"Attributes","text":""},{"location":"models/#mail_intake.models.MailIntakeMessage.body_text","title":"body_text instance-attribute","text":"
body_text: str\n

Extracted plain-text body content of the message.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.from_email","title":"from_email instance-attribute","text":"
from_email: str\n

Sender email address.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.from_name","title":"from_name instance-attribute","text":"
from_name: str | None\n

Optional human-readable sender name.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.message_id","title":"message_id instance-attribute","text":"
message_id: str\n

Provider-specific message identifier.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.raw_headers","title":"raw_headers instance-attribute","text":"
raw_headers: dict[str, str]\n

Normalized mapping of message headers (header name \u2192 value).

"},{"location":"models/#mail_intake.models.MailIntakeMessage.snippet","title":"snippet instance-attribute","text":"
snippet: str\n

Short provider-supplied preview snippet of the message.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.subject","title":"subject instance-attribute","text":"
subject: str\n

Raw subject line of the message.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier to which this message belongs.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.timestamp","title":"timestamp instance-attribute","text":"
timestamp: datetime\n

Message timestamp as a timezone-naive UTC datetime.

"},{"location":"models/#mail_intake.models.MailIntakeThread","title":"MailIntakeThread dataclass","text":"
MailIntakeThread(\n    thread_id: str,\n    normalized_subject: str,\n    participants: set[str] = ...,\n    messages: list[MailIntakeMessage] = ...,\n    last_activity_at: datetime | None = ...,\n)\n

Canonical internal representation of an email thread.

Notes

Guarantees:

- A thread groups multiple related messages under a single subject\n  and participant set.\n- It is designed to support reasoning over conversational context\n  such as job applications, interviews, follow-ups, and ongoing discussions.\n- This model is provider-agnostic and safe to persist.\n
"},{"location":"models/#mail_intake.models.MailIntakeThread-attributes","title":"Attributes","text":""},{"location":"models/#mail_intake.models.MailIntakeThread.last_activity_at","title":"last_activity_at class-attribute instance-attribute","text":"
last_activity_at: datetime | None = None\n

Timestamp of the most recent message in the thread.

"},{"location":"models/#mail_intake.models.MailIntakeThread.messages","title":"messages class-attribute instance-attribute","text":"
messages: list[MailIntakeMessage] = field(\n    default_factory=list\n)\n

Ordered list of messages belonging to this thread.

"},{"location":"models/#mail_intake.models.MailIntakeThread.normalized_subject","title":"normalized_subject instance-attribute","text":"
normalized_subject: str\n

Normalized subject line used to group related messages.

"},{"location":"models/#mail_intake.models.MailIntakeThread.participants","title":"participants class-attribute instance-attribute","text":"
participants: set[str] = field(default_factory=set)\n

Set of unique participant email addresses observed in the thread.

"},{"location":"models/#mail_intake.models.MailIntakeThread.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier.

"},{"location":"models/#mail_intake.models.MailIntakeThread-functions","title":"Functions","text":""},{"location":"models/#mail_intake.models.MailIntakeThread.add_message","title":"add_message","text":"
add_message(message: MailIntakeMessage) -> None\n

Add a message to the thread and update derived fields.

Parameters:

Name Type Description Default message MailIntakeMessage

Parsed mail message to add to the thread.

required Notes

Responsibilities:

- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\n
"},{"location":"models/message/","title":"Message","text":""},{"location":"models/message/#mail_intake.models.message","title":"mail_intake.models.message","text":""},{"location":"models/message/#mail_intake.models.message--summary","title":"Summary","text":"

Message domain models for Mail Intake.

This module defines the canonical, provider-agnostic representation of an individual email message as used internally by the Mail Intake ingestion pipeline.

Models in this module are safe to persist and must not contain any provider-specific fields or semantics.

"},{"location":"models/message/#mail_intake.models.message-classes","title":"Classes","text":""},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage","title":"MailIntakeMessage dataclass","text":"
MailIntakeMessage(\n    message_id: str,\n    thread_id: str,\n    timestamp: datetime,\n    from_email: str,\n    from_name: str | None,\n    subject: str,\n    body_text: str,\n    snippet: str,\n    raw_headers: dict[str, str],\n)\n

Canonical internal representation of a single email message.

Notes

Guarantees:

- This model represents a fully parsed and normalized email message.\n- It is intentionally provider-agnostic and suitable for\n  persistence, indexing, and downstream processing.\n

Constraints:

- No provider-specific identifiers, payloads, or API semantics\n  should appear in this model.\n
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage-attributes","title":"Attributes","text":""},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.body_text","title":"body_text instance-attribute","text":"
body_text: str\n

Extracted plain-text body content of the message.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.from_email","title":"from_email instance-attribute","text":"
from_email: str\n

Sender email address.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.from_name","title":"from_name instance-attribute","text":"
from_name: str | None\n

Optional human-readable sender name.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.message_id","title":"message_id instance-attribute","text":"
message_id: str\n

Provider-specific message identifier.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.raw_headers","title":"raw_headers instance-attribute","text":"
raw_headers: dict[str, str]\n

Normalized mapping of message headers (header name \u2192 value).

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.snippet","title":"snippet instance-attribute","text":"
snippet: str\n

Short provider-supplied preview snippet of the message.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.subject","title":"subject instance-attribute","text":"
subject: str\n

Raw subject line of the message.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier to which this message belongs.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.timestamp","title":"timestamp instance-attribute","text":"
timestamp: datetime\n

Message timestamp as a timezone-naive UTC datetime.

"},{"location":"models/thread/","title":"Thread","text":""},{"location":"models/thread/#mail_intake.models.thread","title":"mail_intake.models.thread","text":""},{"location":"models/thread/#mail_intake.models.thread--summary","title":"Summary","text":"

Thread domain models for Mail Intake.

This module defines the canonical, provider-agnostic representation of an email thread as used internally by the Mail Intake ingestion pipeline.

Threads group related messages and serve as the primary unit of reasoning for higher-level correspondence workflows.

"},{"location":"models/thread/#mail_intake.models.thread-classes","title":"Classes","text":""},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread","title":"MailIntakeThread dataclass","text":"
MailIntakeThread(\n    thread_id: str,\n    normalized_subject: str,\n    participants: set[str] = ...,\n    messages: list[MailIntakeMessage] = ...,\n    last_activity_at: datetime | None = ...,\n)\n

Canonical internal representation of an email thread.

Notes

Guarantees:

- A thread groups multiple related messages under a single subject\n  and participant set.\n- It is designed to support reasoning over conversational context\n  such as job applications, interviews, follow-ups, and ongoing discussions.\n- This model is provider-agnostic and safe to persist.\n
"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread-attributes","title":"Attributes","text":""},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.last_activity_at","title":"last_activity_at class-attribute instance-attribute","text":"
last_activity_at: datetime | None = None\n

Timestamp of the most recent message in the thread.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.messages","title":"messages class-attribute instance-attribute","text":"
messages: list[MailIntakeMessage] = field(\n    default_factory=list\n)\n

Ordered list of messages belonging to this thread.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.normalized_subject","title":"normalized_subject instance-attribute","text":"
normalized_subject: str\n

Normalized subject line used to group related messages.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.participants","title":"participants class-attribute instance-attribute","text":"
participants: set[str] = field(default_factory=set)\n

Set of unique participant email addresses observed in the thread.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread-functions","title":"Functions","text":""},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.add_message","title":"add_message","text":"
add_message(message: MailIntakeMessage) -> None\n

Add a message to the thread and update derived fields.

Parameters:

Name Type Description Default message MailIntakeMessage

Parsed mail message to add to the thread.

required Notes

Responsibilities:

- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\n
"},{"location":"parsers/","title":"Parsers","text":""},{"location":"parsers/#mail_intake.parsers","title":"mail_intake.parsers","text":""},{"location":"parsers/#mail_intake.parsers--summary","title":"Summary","text":"

Message parsing utilities for Mail Intake.

This package contains provider-aware but adapter-agnostic parsing helpers used to extract and normalize structured information from raw mail payloads.

Parsers in this package are responsible for:

  • Interpreting provider-native message structures.
  • Extracting meaningful fields such as headers, body text, and subjects.
  • Normalizing data into consistent internal representations.

This package does not:

  • Perform network or IO operations.
  • Contain provider API logic.
  • Construct domain models directly.

Parsing functions are designed to be composable and are orchestrated by the ingestion layer.

"},{"location":"parsers/#mail_intake.parsers--public-api","title":"Public API","text":"
  • extract_body
  • parse_headers
  • extract_sender
  • normalize_subject
"},{"location":"parsers/#mail_intake.parsers-functions","title":"Functions","text":""},{"location":"parsers/#mail_intake.parsers.extract_body","title":"extract_body","text":"
extract_body(payload: dict[str, Any]) -> str\n

Extract the best-effort message body from a Gmail payload.

Priority:

  1. text/plain
  2. text/html (stripped to text)
  3. Single-part body
  4. Empty string (if nothing usable found)

Parameters:

Name Type Description Default payload dict[str, Any]

Provider-native message payload dictionary.

required

Returns:

Name Type Description str str

Extracted plain-text message body.

"},{"location":"parsers/#mail_intake.parsers.extract_sender","title":"extract_sender","text":"
extract_sender(\n    headers: dict[str, str],\n) -> tuple[str, str | None]\n

Extract sender email and optional display name from headers.

Parameters:

Name Type Description Default headers dict[str, str]

Normalized header dictionary as returned by parse_headers().

required

Returns:

Type Description tuple[str, str | None]

tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.

Notes

Responsibilities:

- This function parses the `From` header and attempts to extract\n  sender email address and optional human-readable display name.\n
Example

Typical values:

  • \"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")
  • \"john@example.com\" -> (\"john@example.com\", None)
"},{"location":"parsers/#mail_intake.parsers.normalize_subject","title":"normalize_subject","text":"
normalize_subject(subject: str) -> str\n

Normalize an email subject for thread-level comparison.

Parameters:

Name Type Description Default subject str

Raw subject line from a message header.

required

Returns:

Name Type Description str str

Normalized subject string suitable for thread grouping.

Notes

Responsibilities:

- Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n- Repeats prefix stripping to handle stacked prefixes.\n- Collapses excessive whitespace.\n- Preserves original casing (no lowercasing).\n

Guarantees:

- This function is intentionally conservative and avoids aggressive\n  transformations that could alter the semantic meaning of the subject.\n
"},{"location":"parsers/#mail_intake.parsers.parse_headers","title":"parse_headers","text":"
parse_headers(\n    raw_headers: list[dict[str, str]],\n) -> dict[str, str]\n

Convert a list of Gmail-style headers into a normalized dict.

Parameters:

Name Type Description Default raw_headers list[dict[str, str]]

List of header dictionaries, each containing name and value keys.

required

Returns:

Type Description dict[str, str]

dict[str, str]: Dictionary mapping lowercase header names to stripped values.

Notes

Guarantees:

- Provider payloads (such as Gmail) typically represent headers as a\n  list of name/value mappings.\n- This function normalizes them into a case-insensitive dictionary\n  keyed by lowercase header names.\n
Example

Typical usage:

Input:\n    [\n        {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n        {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n    ]\n\nOutput:\n    {\n        \"from\": \"John Doe <john@example.com>\",\n        \"subject\": \"Re: Interview Update\",\n    }\n
"},{"location":"parsers/body/","title":"Body","text":""},{"location":"parsers/body/#mail_intake.parsers.body","title":"mail_intake.parsers.body","text":""},{"location":"parsers/body/#mail_intake.parsers.body--summary","title":"Summary","text":"

Message body extraction utilities for Mail Intake.

This module contains helper functions for extracting a best-effort plain-text body from provider-native message payloads.

The logic is intentionally tolerant of malformed or partial data and prefers human-readable text over fidelity to original formatting.

"},{"location":"parsers/body/#mail_intake.parsers.body-classes","title":"Classes","text":""},{"location":"parsers/body/#mail_intake.parsers.body-functions","title":"Functions","text":""},{"location":"parsers/body/#mail_intake.parsers.body.extract_body","title":"extract_body","text":"
extract_body(payload: dict[str, Any]) -> str\n

Extract the best-effort message body from a Gmail payload.

Priority:

  1. text/plain
  2. text/html (stripped to text)
  3. Single-part body
  4. Empty string (if nothing usable found)

Parameters:

Name Type Description Default payload dict[str, Any]

Provider-native message payload dictionary.

required

Returns:

Name Type Description str str

Extracted plain-text message body.

"},{"location":"parsers/headers/","title":"Headers","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers","title":"mail_intake.parsers.headers","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers--summary","title":"Summary","text":"

Message header parsing utilities for Mail Intake.

This module provides helper functions for normalizing and extracting useful information from provider-native message headers.

The functions here are intentionally simple and tolerant of malformed or incomplete header data.

"},{"location":"parsers/headers/#mail_intake.parsers.headers-functions","title":"Functions","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers.extract_sender","title":"extract_sender","text":"
extract_sender(\n    headers: dict[str, str],\n) -> tuple[str, str | None]\n

Extract sender email and optional display name from headers.

Parameters:

Name Type Description Default headers dict[str, str]

Normalized header dictionary as returned by parse_headers().

required

Returns:

Type Description tuple[str, str | None]

tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.

Notes

Responsibilities:

- This function parses the `From` header and attempts to extract\n  sender email address and optional human-readable display name.\n
Example

Typical values:

  • \"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")
  • \"john@example.com\" -> (\"john@example.com\", None)
"},{"location":"parsers/headers/#mail_intake.parsers.headers.parse_headers","title":"parse_headers","text":"
parse_headers(\n    raw_headers: list[dict[str, str]],\n) -> dict[str, str]\n

Convert a list of Gmail-style headers into a normalized dict.

Parameters:

Name Type Description Default raw_headers list[dict[str, str]]

List of header dictionaries, each containing name and value keys.

required

Returns:

Type Description dict[str, str]

dict[str, str]: Dictionary mapping lowercase header names to stripped values.

Notes

Guarantees:

- Provider payloads (such as Gmail) typically represent headers as a\n  list of name/value mappings.\n- This function normalizes them into a case-insensitive dictionary\n  keyed by lowercase header names.\n
Example

Typical usage:

Input:\n    [\n        {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n        {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n    ]\n\nOutput:\n    {\n        \"from\": \"John Doe <john@example.com>\",\n        \"subject\": \"Re: Interview Update\",\n    }\n
"},{"location":"parsers/subject/","title":"Subject","text":""},{"location":"parsers/subject/#mail_intake.parsers.subject","title":"mail_intake.parsers.subject","text":""},{"location":"parsers/subject/#mail_intake.parsers.subject--summary","title":"Summary","text":"

Subject line normalization utilities for Mail Intake.

This module provides helper functions for normalizing email subject lines to enable reliable thread-level comparison and grouping.

Normalization is intentionally conservative to avoid altering semantic meaning while removing common reply and forward prefixes.

"},{"location":"parsers/subject/#mail_intake.parsers.subject-functions","title":"Functions","text":""},{"location":"parsers/subject/#mail_intake.parsers.subject.normalize_subject","title":"normalize_subject","text":"
normalize_subject(subject: str) -> str\n

Normalize an email subject for thread-level comparison.

Parameters:

Name Type Description Default subject str

Raw subject line from a message header.

required

Returns:

Name Type Description str str

Normalized subject string suitable for thread grouping.

Notes

Responsibilities:

- Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n- Repeats prefix stripping to handle stacked prefixes.\n- Collapses excessive whitespace.\n- Preserves original casing (no lowercasing).\n

Guarantees:

- This function is intentionally conservative and avoids aggressive\n  transformations that could alter the semantic meaning of the subject.\n
"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"mail_intake","text":"
  • Mail Intake
"},{"location":"#mail_intake","title":"mail_intake","text":""},{"location":"#mail_intake--summary","title":"Summary","text":"

Mail Intake \u2014 provider-agnostic, read-only email ingestion framework.

Mail Intake is a contract-first library designed to ingest, parse, and normalize email data from external providers (such as Gmail) into clean, provider-agnostic domain models.

The library is intentionally structured around clear layers, each exposed as a first-class module at the package root:

  • adapters: Provider-specific access (e.g., Gmail).
  • auth: Authentication providers and credential lifecycle management.
  • credentials: Credential persistence abstractions and implementations.
  • parsers: Extraction and normalization of message content.
  • ingestion: Orchestration and high-level ingestion workflows.
  • models: Canonical, provider-agnostic data representations.
  • config: Explicit global configuration.
  • exceptions: Library-defined error hierarchy.

The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.

"},{"location":"#mail_intake--installation","title":"Installation","text":"

Install using pip:

pip install mail-intake\n

Or with Poetry:

poetry add mail-intake\n

Mail Intake is pure Python and has no runtime dependencies beyond those required by the selected provider (for example, Google APIs for Gmail).

"},{"location":"#mail_intake--quick-start","title":"Quick Start","text":"

Minimal Gmail ingestion example (local development):

from mail_intake.ingestion import MailIntakeReader\nfrom mail_intake.adapters import MailIntakeGmailAdapter\nfrom mail_intake.auth import MailIntakeGoogleAuth\nfrom mail_intake.credentials import PickleCredentialStore\n\nstore = PickleCredentialStore(path=\"token.pickle\")\n\nauth = MailIntakeGoogleAuth(\n    credentials_path=\"credentials.json\",\n    store=store,\n    scopes=[\"https://www.googleapis.com/auth/gmail.readonly\"],\n)\n\nadapter = MailIntakeGmailAdapter(auth_provider=auth)\nreader = MailIntakeReader(adapter)\n\nfor message in reader.iter_messages(\"from:recruiter@example.com\"):\n    print(message.subject, message.from_email)\n

Iterating over threads:

for thread in reader.iter_threads(\"subject:Interview\"):\n    print(thread.normalized_subject, len(thread.messages))\n
"},{"location":"#mail_intake--architecture","title":"Architecture","text":"

Mail Intake is designed to be extensible via public contracts exposed through its modules:

  • Users MAY implement their own mail adapters by subclassing adapters.MailIntakeAdapter.
  • Users MAY implement their own authentication providers by subclassing auth.MailIntakeAuthProvider[T].
  • Users MAY implement their own credential persistence layers by implementing credentials.CredentialStore[T].

Users SHOULD NOT subclass built-in adapter implementations. Built-in adapters (such as Gmail) are reference implementations and may change internally without notice.

Design Guarantees:

  • Read-only access: no mutation of provider state.
  • Provider-agnostic domain models.
  • Explicit configuration and dependency injection.
  • No implicit global state or environment reads.
  • Deterministic, testable behavior.
  • Distributed-safe authentication design.

Mail Intake favors correctness, clarity, and explicitness over convenience shortcuts.

Core Philosophy:

Mail Intake is built as a contract-first ingestion pipeline:

  1. Layered Decoupling: Adapters handle transport, Parsers handle format normalization, and Ingestion orchestrates.
  2. Provider Agnosticism: Domain models and core logic never depend on provider-specific (e.g., Gmail) API internals.
  3. Stateless Workflows: The library functions as a read-only pipe, ensuring side-effect-free ingestion.
"},{"location":"#mail_intake--public-api","title":"Public API","text":"

The supported public API consists of the following top-level modules:

  • mail_intake.ingestion
  • mail_intake.adapters
  • mail_intake.auth
  • mail_intake.credentials
  • mail_intake.parsers
  • mail_intake.models
  • mail_intake.config
  • mail_intake.exceptions

Classes and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.

"},{"location":"config/","title":"Config","text":""},{"location":"config/#mail_intake.config","title":"mail_intake.config","text":""},{"location":"config/#mail_intake.config--summary","title":"Summary","text":"

Global configuration models for Mail Intake.

This module defines the top-level configuration object used to control mail ingestion behavior across adapters, authentication providers, and ingestion workflows.

Configuration is intentionally explicit, immutable, and free of implicit environment reads to ensure predictability and testability.

"},{"location":"config/#mail_intake.config-classes","title":"Classes","text":""},{"location":"config/#mail_intake.config.MailIntakeConfig","title":"MailIntakeConfig dataclass","text":"
MailIntakeConfig(\n    provider: str = ...,\n    user_id: str = ...,\n    readonly: bool = ...,\n    credentials_path: str | None = ...,\n    token_path: str | None = ...,\n)\n

Global configuration for mail-intake.

Notes

Guarantees:

- This configuration is intentionally explicit and immutable.\n- No implicit environment reads or global state.\n- Explicit configuration over implicit defaults.\n- No direct environment or filesystem access.\n- This model is safe to pass across layers and suitable for\n  serialization.\n
"},{"location":"config/#mail_intake.config.MailIntakeConfig-attributes","title":"Attributes","text":""},{"location":"config/#mail_intake.config.MailIntakeConfig.credentials_path","title":"credentials_path class-attribute instance-attribute","text":"
credentials_path: str | None = None\n

Optional path to provider credentials configuration.

"},{"location":"config/#mail_intake.config.MailIntakeConfig.provider","title":"provider class-attribute instance-attribute","text":"
provider: str = 'gmail'\n

Identifier of the mail provider to use (e.g., \"gmail\").

"},{"location":"config/#mail_intake.config.MailIntakeConfig.readonly","title":"readonly class-attribute instance-attribute","text":"
readonly: bool = True\n

Whether ingestion should operate in read-only mode.

"},{"location":"config/#mail_intake.config.MailIntakeConfig.token_path","title":"token_path class-attribute instance-attribute","text":"
token_path: str | None = None\n

Optional path to persisted authentication tokens.

"},{"location":"config/#mail_intake.config.MailIntakeConfig.user_id","title":"user_id class-attribute instance-attribute","text":"
user_id: str = 'me'\n

Provider-specific user identifier. Defaults to the authenticated user.

"},{"location":"exceptions/","title":"Exceptions","text":""},{"location":"exceptions/#mail_intake.exceptions","title":"mail_intake.exceptions","text":""},{"location":"exceptions/#mail_intake.exceptions--summary","title":"Summary","text":"

Exception hierarchy for Mail Intake.

This module defines the canonical exception types used throughout the Mail Intake library.

All library-raised errors derive from MailIntakeError. Consumers are encouraged to catch this base type (or specific subclasses) rather than provider-specific or third-party exceptions.

"},{"location":"exceptions/#mail_intake.exceptions-classes","title":"Classes","text":""},{"location":"exceptions/#mail_intake.exceptions.MailIntakeAdapterError","title":"MailIntakeAdapterError","text":"

Bases: MailIntakeError

Errors raised by mail provider adapters.

Notes

Lifecycle:

- Raised when a provider adapter encounters API errors, transport\n  failures, or invalid provider responses.\n
"},{"location":"exceptions/#mail_intake.exceptions.MailIntakeAuthError","title":"MailIntakeAuthError","text":"

Bases: MailIntakeError

Authentication and credential-related failures.

Notes

Lifecycle:

- Raised when authentication providers are unable to acquire,\n  refresh, or persist valid credentials.\n
"},{"location":"exceptions/#mail_intake.exceptions.MailIntakeError","title":"MailIntakeError","text":"

Bases: Exception

Base exception for all Mail Intake errors.

Notes

Guarantees:

- This is the root of the Mail Intake exception hierarchy\n- All errors raised by the library must derive from this class\n- Consumers should generally catch this type when handling library-level failures\n
"},{"location":"exceptions/#mail_intake.exceptions.MailIntakeParsingError","title":"MailIntakeParsingError","text":"

Bases: MailIntakeError

Errors encountered while parsing message content.

Notes

Lifecycle:

- Raised when raw provider payloads cannot be interpreted or\n  normalized into internal domain models.\n
"},{"location":"adapters/","title":"Adapters","text":""},{"location":"adapters/#mail_intake.adapters","title":"mail_intake.adapters","text":""},{"location":"adapters/#mail_intake.adapters--summary","title":"Summary","text":"

Mail provider adapter implementations for Mail Intake.

This package contains adapter-layer implementations responsible for interfacing with external mail providers and exposing a normalized, provider-agnostic contract to the rest of the system.

Adapters in this package:

  • Implement the MailIntakeAdapter interface.
  • Encapsulate all provider-specific APIs and semantics.
  • Perform read-only access to mail data.
  • Return provider-native payloads without interpretation.

Provider-specific logic must not leak outside of adapter implementations. All parsings, normalizations, and transformations must be handled by downstream components.

"},{"location":"adapters/#mail_intake.adapters--public-api","title":"Public API","text":"
  • MailIntakeAdapter
  • MailIntakeGmailAdapter
"},{"location":"adapters/#mail_intake.adapters-classes","title":"Classes","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter","title":"MailIntakeAdapter","text":"

Bases: ABC

Base adapter interface for mail providers.

Notes

Guarantees:

- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\n

Lifecycle:

- Adapters are intentionally read-only and must not mutate provider state.\n
"},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter-functions","title":"Functions","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_message","title":"fetch_message abstractmethod","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full raw message by message identifier.

Parameters:

Name Type Description Default message_id str

Provider-specific message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).

"},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_thread","title":"fetch_thread abstractmethod","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full raw thread by thread identifier.

Parameters:

Name Type Description Default thread_id str

Provider-specific thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native thread payload.

"},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs abstractmethod","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over lightweight message references matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[dict[str, str]]

Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message and thread identifiers.

Notes

Guarantees:

- Implementations must yield dictionaries containing at least\n  `message_id` and `thread_id`.\n
Example

Typical yield:

{\n    \"message_id\": \"...\",\n    \"thread_id\": \"...\"\n}\n
"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"
MailIntakeGmailAdapter(\n    auth_provider: MailIntakeAuthProvider[Any],\n    user_id: str = \"me\",\n)\n

Bases: MailIntakeAdapter

Gmail read-only adapter.

This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.

Notes

Responsibilities:

- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\n

Constraints:

- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\n

Initialize the Gmail adapter.

Parameters:

Name Type Description Default auth_provider MailIntakeAuthProvider

Authentication provider capable of supplying valid Gmail API credentials.

required user_id str

Gmail user identifier. Defaults to \"me\".

'me'"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.service","title":"service property","text":"
service: Any\n

Lazily initialize and return the Gmail API service client.

Raises:

Type Description MailIntakeAdapterError

If the Gmail service cannot be initialized.

"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full Gmail message by message ID.

Parameters:

Name Type Description Default message_id str

Gmail message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail message payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full Gmail thread by thread ID.

Parameters:

Name Type Description Default thread_id str

Gmail thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail thread payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over message references matching the query.

Parameters:

Name Type Description Default query str

Gmail search query string.

required

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message_id and thread_id.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"adapters/base/","title":"Base","text":""},{"location":"adapters/base/#mail_intake.adapters.base","title":"mail_intake.adapters.base","text":""},{"location":"adapters/base/#mail_intake.adapters.base--summary","title":"Summary","text":"

Mail provider adapter contracts for Mail Intake.

This module defines the provider-agnostic adapter interface used for read-only mail ingestion.

Adapters encapsulate all provider-specific access logic and expose a minimal, normalized contract to the rest of the system. No provider-specific types or semantics should leak beyond implementations of this interface.

"},{"location":"adapters/base/#mail_intake.adapters.base-classes","title":"Classes","text":""},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter","title":"MailIntakeAdapter","text":"

Bases: ABC

Base adapter interface for mail providers.

Notes

Guarantees:

- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\n

Lifecycle:

- Adapters are intentionally read-only and must not mutate provider state.\n
"},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter-functions","title":"Functions","text":""},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_message","title":"fetch_message abstractmethod","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full raw message by message identifier.

Parameters:

Name Type Description Default message_id str

Provider-specific message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).

"},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_thread","title":"fetch_thread abstractmethod","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full raw thread by thread identifier.

Parameters:

Name Type Description Default thread_id str

Provider-specific thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native thread payload.

"},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs abstractmethod","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over lightweight message references matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[dict[str, str]]

Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message and thread identifiers.

Notes

Guarantees:

- Implementations must yield dictionaries containing at least\n  `message_id` and `thread_id`.\n
Example

Typical yield:

{\n    \"message_id\": \"...\",\n    \"thread_id\": \"...\"\n}\n
"},{"location":"adapters/gmail/","title":"Gmail","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail","title":"mail_intake.adapters.gmail","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail--summary","title":"Summary","text":"

Gmail adapter implementation for Mail Intake.

This module provides a Gmail-specific implementation of the MailIntakeAdapter contract.

It is the only place in the codebase where:

  • googleapiclient is imported.
  • Gmail REST API semantics are known.
  • Low-level .execute() calls are made.

All Gmail-specific behavior must be strictly contained within this module.

"},{"location":"adapters/gmail/#mail_intake.adapters.gmail-classes","title":"Classes","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"
MailIntakeGmailAdapter(\n    auth_provider: MailIntakeAuthProvider[Any],\n    user_id: str = \"me\",\n)\n

Bases: MailIntakeAdapter

Gmail read-only adapter.

This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.

Notes

Responsibilities:

- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\n

Constraints:

- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\n

Initialize the Gmail adapter.

Parameters:

Name Type Description Default auth_provider MailIntakeAuthProvider

Authentication provider capable of supplying valid Gmail API credentials.

required user_id str

Gmail user identifier. Defaults to \"me\".

'me'"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.service","title":"service property","text":"
service: Any\n

Lazily initialize and return the Gmail API service client.

Raises:

Type Description MailIntakeAdapterError

If the Gmail service cannot be initialized.

"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full Gmail message by message ID.

Parameters:

Name Type Description Default message_id str

Gmail message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail message payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full Gmail thread by thread ID.

Parameters:

Name Type Description Default thread_id str

Gmail thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail thread payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over message references matching the query.

Parameters:

Name Type Description Default query str

Gmail search query string.

required

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message_id and thread_id.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"auth/","title":"Auth","text":""},{"location":"auth/#mail_intake.auth","title":"mail_intake.auth","text":""},{"location":"auth/#mail_intake.auth--summary","title":"Summary","text":"

Authentication provider implementations for Mail Intake.

This package defines the authentication layer used by mail adapters to obtain provider-specific credentials.

It exposes:

  • A stable, provider-agnostic authentication contract.
  • Concrete authentication providers for supported platforms.

Authentication providers:

  • Are responsible for credential acquisition and lifecycle management.
  • Are intentionally decoupled from adapter logic.
  • May be extended by users to support additional providers.

Consumers should depend on the abstract interface and use concrete implementations only where explicitly required.

"},{"location":"auth/#mail_intake.auth--public-api","title":"Public API","text":"
  • MailIntakeAuthProvider
  • MailIntakeGoogleAuth
"},{"location":"auth/#mail_intake.auth-classes","title":"Classes","text":""},{"location":"auth/#mail_intake.auth.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"

Bases: ABC, Generic[T]

Abstract base class for authentication providers.

This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.

Notes

Responsibilities:

- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\n

Constraints:

- Mail adapters must treat returned credentials as opaque and\n  provider-specific.\n- Mail adapters rely only on the declared credential type expected\n  by the adapter.\n
"},{"location":"auth/#mail_intake.auth.MailIntakeAuthProvider-functions","title":"Functions","text":""},{"location":"auth/#mail_intake.auth.MailIntakeAuthProvider.get_credentials","title":"get_credentials abstractmethod","text":"
get_credentials() -> T\n

Retrieve valid, provider-specific credentials.

Returns:

Name Type Description T T

Credentials of type T suitable for immediate use by the corresponding mail adapter.

Raises:

Type Description Exception

An authentication-specific exception indicating that credentials could not be obtained or validated.

Notes

Guarantees:

- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n  authentication material.\n- Implementations must either return credentials of the declared\n  type `T` that are valid at the time of return or raise an exception.\n
"},{"location":"auth/#mail_intake.auth.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"
MailIntakeGoogleAuth(\n    credentials_path: str,\n    store: CredentialStore[Any],\n    scopes: Sequence[str],\n)\n

Bases: MailIntakeAuthProvider

Google OAuth provider for Gmail access.

This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.

Notes

Responsibilities:

- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\n

Guarantees:

- This class is synchronous by design and maintains a minimal\n  internal state.\n

Initialize the Google authentication provider.

Parameters:

Name Type Description Default credentials_path str

Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.

required store CredentialStore[Credentials]

Credential store responsible for persisting and retrieving Google OAuth credentials.

required scopes Sequence[str]

OAuth scopes required for Gmail access.

required"},{"location":"auth/#mail_intake.auth.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"auth/#mail_intake.auth.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"
get_credentials() -> Any\n

Retrieve valid Google OAuth credentials.

Returns:

Name Type Description Credentials Any

A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.

Raises:

Type Description MailIntakeAuthError

If credentials cannot be loaded, refreshed, or obtained via interactive authentication.

Notes

Lifecycle:

- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\n
"},{"location":"auth/base/","title":"Base","text":""},{"location":"auth/base/#mail_intake.auth.base","title":"mail_intake.auth.base","text":""},{"location":"auth/base/#mail_intake.auth.base--summary","title":"Summary","text":"

Authentication provider contracts for Mail Intake.

This module defines the authentication abstraction layer used by mail adapters to obtain provider-specific credentials.

Authentication concerns are intentionally decoupled from adapter logic. Adapters depend only on this interface and must not be aware of how credentials are acquired, refreshed, or persisted.

"},{"location":"auth/base/#mail_intake.auth.base-classes","title":"Classes","text":""},{"location":"auth/base/#mail_intake.auth.base.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"

Bases: ABC, Generic[T]

Abstract base class for authentication providers.

This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.

Notes

Responsibilities:

- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\n

Constraints:

- Mail adapters must treat returned credentials as opaque and\n  provider-specific.\n- Mail adapters rely only on the declared credential type expected\n  by the adapter.\n
"},{"location":"auth/base/#mail_intake.auth.base.MailIntakeAuthProvider-functions","title":"Functions","text":""},{"location":"auth/base/#mail_intake.auth.base.MailIntakeAuthProvider.get_credentials","title":"get_credentials abstractmethod","text":"
get_credentials() -> T\n

Retrieve valid, provider-specific credentials.

Returns:

Name Type Description T T

Credentials of type T suitable for immediate use by the corresponding mail adapter.

Raises:

Type Description Exception

An authentication-specific exception indicating that credentials could not be obtained or validated.

Notes

Guarantees:

- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n  authentication material.\n- Implementations must either return credentials of the declared\n  type `T` that are valid at the time of return or raise an exception.\n
"},{"location":"auth/google/","title":"Google","text":""},{"location":"auth/google/#mail_intake.auth.google","title":"mail_intake.auth.google","text":""},{"location":"auth/google/#mail_intake.auth.google--summary","title":"Summary","text":"

Google authentication provider implementation for Mail Intake.

This module provides a Google OAuth\u2013based authentication provider used primarily for Gmail access.

It encapsulates all Google-specific authentication concerns, including:

  • Credential loading and persistence.
  • Token refresh handling.
  • Interactive OAuth flow initiation.
  • Coordination with a credential persistence layer.

No Google authentication details should leak outside this module.

"},{"location":"auth/google/#mail_intake.auth.google-classes","title":"Classes","text":""},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"
MailIntakeGoogleAuth(\n    credentials_path: str,\n    store: CredentialStore[Any],\n    scopes: Sequence[str],\n)\n

Bases: MailIntakeAuthProvider

Google OAuth provider for Gmail access.

This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.

Notes

Responsibilities:

- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\n

Guarantees:

- This class is synchronous by design and maintains a minimal\n  internal state.\n

Initialize the Google authentication provider.

Parameters:

Name Type Description Default credentials_path str

Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.

required store CredentialStore[Credentials]

Credential store responsible for persisting and retrieving Google OAuth credentials.

required scopes Sequence[str]

OAuth scopes required for Gmail access.

required"},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"
get_credentials() -> Any\n

Retrieve valid Google OAuth credentials.

Returns:

Name Type Description Credentials Any

A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.

Raises:

Type Description MailIntakeAuthError

If credentials cannot be loaded, refreshed, or obtained via interactive authentication.

Notes

Lifecycle:

- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\n
"},{"location":"credentials/","title":"Credentials","text":""},{"location":"credentials/#mail_intake.credentials","title":"mail_intake.credentials","text":""},{"location":"credentials/#mail_intake.credentials--summary","title":"Summary","text":"

Credential persistence interfaces and implementations for Mail Intake.

This package defines the abstractions and concrete implementations used to persist authentication credentials across Mail Intake components.

The credential persistence layer is intentionally decoupled from authentication logic. Authentication providers are responsible for credential acquisition, validation, and refresh, while implementations within this package are responsible solely for storage and retrieval.

The package provides:

  • A generic CredentialStore abstraction defining the persistence contract.
  • Local filesystem\u2013based storage for development and single-node use.
  • Distributed, Redis-backed storage for production and scaled deployments.

Credential lifecycle management, interpretation, and security policy decisions remain the responsibility of authentication providers.

"},{"location":"credentials/#mail_intake.credentials--public-api","title":"Public API","text":"
  • CredentialStore
  • PickleCredentialStore
  • RedisCredentialStore
"},{"location":"credentials/#mail_intake.credentials-classes","title":"Classes","text":""},{"location":"credentials/#mail_intake.credentials.CredentialStore","title":"CredentialStore","text":"

Bases: ABC, Generic[T]

Abstract base class defining a generic persistence interface.

Used for authentication credentials across different backends.

Notes

Responsibilities:

- Provide persistent storage separating life-cycle management from\n  storage mechanics.\n- Keep implementation focused only on persistence.\n

Constraints:

- The store is intentionally agnostic to:\n    - The concrete credential type being stored.\n    - The serialization format used to persist credentials.\n    - The underlying storage backend or durability guarantees.\n
"},{"location":"credentials/#mail_intake.credentials.CredentialStore-functions","title":"Functions","text":""},{"location":"credentials/#mail_intake.credentials.CredentialStore.clear","title":"clear abstractmethod","text":"
clear() -> None\n

Remove any persisted credentials from the store.

Notes

Lifecycle:

- This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n- Must ensure that no stale authentication material remains accessible\n

Guarantees:

- Implementations should treat this operation as idempotent\n
"},{"location":"credentials/#mail_intake.credentials.CredentialStore.load","title":"load abstractmethod","text":"
load() -> T | None\n

Load previously persisted credentials.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are available and loadable; otherwise None.

Notes

Guarantees:

- Implementations should return `None` when no credentials are\n  present or when stored credentials cannot be successfully\n  decoded or deserialized.\n- The store must not attempt to validate, refresh, or otherwise\n  interpret the returned credentials.\n
"},{"location":"credentials/#mail_intake.credentials.CredentialStore.save","title":"save abstractmethod","text":"
save(credentials: T) -> None\n

Persist credentials to the underlying storage backend.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Lifecycle:

- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n

Responsibilities:

- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n
"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore","title":"PickleCredentialStore","text":"
PickleCredentialStore(path: str)\n

Bases: CredentialStore[T]

Filesystem-backed credential store using pickle serialization.

This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.

Notes

Guarantees:

- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\n

Constraints:

- Credential lifecycle management, validation, and refresh logic are\n  explicitly out of scope for this class.\n

Initialize a pickle-backed credential store.

Parameters:

Name Type Description Default path str

Filesystem path where credentials will be stored. The file will be created or overwritten as needed.

required"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove persisted credentials from the local filesystem.

Notes

Lifecycle:

- This method deletes the credential file if it exists and should be treated as an idempotent operation\n
"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from the local filesystem.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If the credential file does not exist or cannot be successfully\n  deserialized, this method returns `None`.\n- The store does not attempt to validate or interpret the\n  returned credentials.\n
"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to the local filesystem.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials at the configured path are overwritten\n
"},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore","title":"RedisCredentialStore","text":"
RedisCredentialStore(\n    redis_client: Any,\n    key: str,\n    serialize: Callable[[T], bytes],\n    deserialize: Callable[[bytes], T],\n    ttl_seconds: int | None = None,\n)\n

Bases: CredentialStore[T]

Redis-backed implementation of CredentialStore.

This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.

Notes

Responsibilities:

- This class is responsible only for persistence and retrieval.\n- It does not interpret, validate, refresh, or otherwise manage the\n  lifecycle of the credentials being stored.\n

Guarantees:

- The store is intentionally generic and delegates all serialization\n  concerns to caller-provided functions.\n- This avoids unsafe mechanisms such as `pickle` and allows\n  credential formats to be explicitly controlled and audited.\n

Initialize a Redis-backed credential store.

Parameters:

Name Type Description Default redis_client Any

Initialized Redis client instance used for persistence.

required key str

Storage key under which credentials are persisted.

required serialize Callable[[T], bytes]

Callable that encodes credentials to bytes for storage.

required deserialize Callable[[bytes], T]

Callable that decodes stored bytes back into credentials.

required ttl_seconds int | None

Optional time-to-live in seconds after which stored credentials expire automatically. None disables expiry.

None"},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove stored credentials from Redis.

Notes

Lifecycle:

- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\n
"},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from Redis.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If no value exists for the configured key, or if the stored\n  payload cannot be successfully deserialized, this method\n  returns `None`.\n- The store does not attempt to validate the returned\n  credentials or determine whether they are expired or\n  otherwise usable.\n
"},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to Redis.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials under the same key are overwritten\n- If a TTL is configured, the credentials will expire automatically after the specified duration\n
"},{"location":"credentials/pickle/","title":"Pickle","text":""},{"location":"credentials/pickle/#mail_intake.credentials.pickle","title":"mail_intake.credentials.pickle","text":""},{"location":"credentials/pickle/#mail_intake.credentials.pickle--summary","title":"Summary","text":"

Local filesystem\u2013based credential persistence for Mail Intake.

This module provides a file-backed implementation of the CredentialStore abstraction using Python's pickle module.

The pickle-based credential store is intended for local development, single-node deployments, and controlled environments where credentials do not need to be shared across processes or machines.

Due to the security and portability risks associated with pickle-based serialization, this implementation is not suitable for distributed or untrusted environments.

"},{"location":"credentials/pickle/#mail_intake.credentials.pickle-classes","title":"Classes","text":""},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore","title":"PickleCredentialStore","text":"
PickleCredentialStore(path: str)\n

Bases: CredentialStore[T]

Filesystem-backed credential store using pickle serialization.

This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.

Notes

Guarantees:

- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\n

Constraints:

- Credential lifecycle management, validation, and refresh logic are\n  explicitly out of scope for this class.\n

Initialize a pickle-backed credential store.

Parameters:

Name Type Description Default path str

Filesystem path where credentials will be stored. The file will be created or overwritten as needed.

required"},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove persisted credentials from the local filesystem.

Notes

Lifecycle:

- This method deletes the credential file if it exists and should be treated as an idempotent operation\n
"},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from the local filesystem.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If the credential file does not exist or cannot be successfully\n  deserialized, this method returns `None`.\n- The store does not attempt to validate or interpret the\n  returned credentials.\n
"},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to the local filesystem.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials at the configured path are overwritten\n
"},{"location":"credentials/redis/","title":"Redis","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis","title":"mail_intake.credentials.redis","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis--summary","title":"Summary","text":"

Redis-backed credential persistence for Mail Intake.

This module provides a Redis-based implementation of the CredentialStore abstraction, enabling credential persistence across distributed and horizontally scaled deployments.

The Redis credential store is designed for environments where authentication credentials must be shared safely across multiple processes, containers, or nodes, such as container orchestration platforms and microservice architectures.

Key characteristics:

  • Distributed-safe, shared storage using Redis.
  • Explicit, caller-defined serialization and deserialization.
  • No reliance on unsafe mechanisms such as pickle.
  • Optional time-to-live (TTL) support for automatic credential expiry.

This module is responsible solely for persistence concerns. Credential validation, refresh, rotation, and acquisition remain the responsibility of authentication provider implementations.

"},{"location":"credentials/redis/#mail_intake.credentials.redis-classes","title":"Classes","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore","title":"RedisCredentialStore","text":"
RedisCredentialStore(\n    redis_client: Any,\n    key: str,\n    serialize: Callable[[T], bytes],\n    deserialize: Callable[[bytes], T],\n    ttl_seconds: int | None = None,\n)\n

Bases: CredentialStore[T]

Redis-backed implementation of CredentialStore.

This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.

Notes

Responsibilities:

- This class is responsible only for persistence and retrieval.\n- It does not interpret, validate, refresh, or otherwise manage the\n  lifecycle of the credentials being stored.\n

Guarantees:

- The store is intentionally generic and delegates all serialization\n  concerns to caller-provided functions.\n- This avoids unsafe mechanisms such as `pickle` and allows\n  credential formats to be explicitly controlled and audited.\n

Initialize a Redis-backed credential store.

Parameters:

Name Type Description Default redis_client Any

Initialized Redis client instance used for persistence.

required key str

Storage key under which credentials are persisted.

required serialize Callable[[T], bytes]

Callable that encodes credentials to bytes for storage.

required deserialize Callable[[bytes], T]

Callable that decodes stored bytes back into credentials.

required ttl_seconds int | None

Optional time-to-live in seconds after which stored credentials expire automatically. None disables expiry.

None"},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove stored credentials from Redis.

Notes

Lifecycle:

- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\n
"},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from Redis.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If no value exists for the configured key, or if the stored\n  payload cannot be successfully deserialized, this method\n  returns `None`.\n- The store does not attempt to validate the returned\n  credentials or determine whether they are expired or\n  otherwise usable.\n
"},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to Redis.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials under the same key are overwritten\n- If a TTL is configured, the credentials will expire automatically after the specified duration\n
"},{"location":"credentials/store/","title":"Store","text":""},{"location":"credentials/store/#mail_intake.credentials.store","title":"mail_intake.credentials.store","text":""},{"location":"credentials/store/#mail_intake.credentials.store--summary","title":"Summary","text":"

Credential persistence abstractions for Mail Intake.

This module defines the generic persistence contract used to store and retrieve authentication credentials across Mail Intake components.

The CredentialStore abstraction establishes a strict separation between credential lifecycle management and credential storage. Authentication providers are responsible for acquiring, validating, refreshing, and revoking credentials, while concrete store implementations are responsible solely for persistence concerns.

By remaining agnostic to credential structure, serialization format, and storage backend, this module enables multiple persistence strategies\u2014such as local files, in-memory caches, distributed stores, or secrets managers\u2014without coupling authentication logic to any specific storage mechanism.

"},{"location":"credentials/store/#mail_intake.credentials.store-classes","title":"Classes","text":""},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore","title":"CredentialStore","text":"

Bases: ABC, Generic[T]

Abstract base class defining a generic persistence interface.

Used for authentication credentials across different backends.

Notes

Responsibilities:

- Provide persistent storage separating life-cycle management from\n  storage mechanics.\n- Keep implementation focused only on persistence.\n

Constraints:

- The store is intentionally agnostic to:\n    - The concrete credential type being stored.\n    - The serialization format used to persist credentials.\n    - The underlying storage backend or durability guarantees.\n
"},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore-functions","title":"Functions","text":""},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore.clear","title":"clear abstractmethod","text":"
clear() -> None\n

Remove any persisted credentials from the store.

Notes

Lifecycle:

- This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n- Must ensure that no stale authentication material remains accessible\n

Guarantees:

- Implementations should treat this operation as idempotent\n
"},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore.load","title":"load abstractmethod","text":"
load() -> T | None\n

Load previously persisted credentials.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are available and loadable; otherwise None.

Notes

Guarantees:

- Implementations should return `None` when no credentials are\n  present or when stored credentials cannot be successfully\n  decoded or deserialized.\n- The store must not attempt to validate, refresh, or otherwise\n  interpret the returned credentials.\n
"},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore.save","title":"save abstractmethod","text":"
save(credentials: T) -> None\n

Persist credentials to the underlying storage backend.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Lifecycle:

- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n

Responsibilities:

- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n
"},{"location":"ingestion/","title":"Ingestion","text":""},{"location":"ingestion/#mail_intake.ingestion","title":"mail_intake.ingestion","text":""},{"location":"ingestion/#mail_intake.ingestion--summary","title":"Summary","text":"

Mail ingestion orchestration for Mail Intake.

This package contains high-level ingestion components responsible for coordinating mail retrieval, parsing, normalization, and model construction.

It represents the top of the ingestion pipeline and is intended to be the primary interaction surface for library consumers.

Components in this package:

  • Are provider-agnostic.
  • Depend only on adapter and parser contracts.
  • Contain no provider-specific API logic.
  • Expose read-only ingestion workflows.

Consumers are expected to construct a mail adapter and pass it to the ingestion layer to begin processing messages and threads.

"},{"location":"ingestion/#mail_intake.ingestion--public-api","title":"Public API","text":"
  • MailIntakeReader
"},{"location":"ingestion/#mail_intake.ingestion-classes","title":"Classes","text":""},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader","title":"MailIntakeReader","text":"
MailIntakeReader(adapter: MailIntakeAdapter)\n

High-level read-only ingestion interface.

Notes

Responsibilities:

- This class is the primary entry point for consumers of the\n  Mail Intake library.\n- It orchestrates the full ingestion pipeline:\n    - Querying the adapter for message references.\n    - Fetching raw provider messages.\n    - Parsing and normalizing message data.\n    - Constructing domain models.\n

Constraints:

- This class is intentionally: Provider-agnostic, stateless beyond\n  iteration scope, read-only.\n

Initialize the mail reader.

Parameters:

Name Type Description Default adapter MailIntakeAdapter

Mail adapter implementation used to retrieve raw messages and threads from a mail provider.

required"},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader-functions","title":"Functions","text":""},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader.iter_messages","title":"iter_messages","text":"
iter_messages(query: str) -> Iterator[MailIntakeMessage]\n

Iterate over parsed messages matching a provider query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeMessage MailIntakeMessage

Fully parsed and normalized MailIntakeMessage instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

"},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader.iter_threads","title":"iter_threads","text":"
iter_threads(query: str) -> Iterator[MailIntakeThread]\n

Iterate over threads constructed from messages matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[MailIntakeThread]

Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.

Raises:

Type Description `MailIntakeParsingError`

If a message cannot be parsed.

Notes

Guarantees:

- Messages are grouped by `thread_id` and yielded as complete\n  thread objects containing all associated messages.\n
"},{"location":"ingestion/reader/","title":"Reader","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader","title":"mail_intake.ingestion.reader","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader--summary","title":"Summary","text":"

High-level mail ingestion orchestration for Mail Intake.

This module provides the primary, provider-agnostic entry point for reading and processing mail data.

It coordinates:

  • Mail adapter access.
  • Message and thread iteration.
  • Header and body parsing.
  • Normalization and model construction.

No provider-specific logic or API semantics are permitted in this layer.

"},{"location":"ingestion/reader/#mail_intake.ingestion.reader-classes","title":"Classes","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader","title":"MailIntakeReader","text":"
MailIntakeReader(adapter: MailIntakeAdapter)\n

High-level read-only ingestion interface.

Notes

Responsibilities:

- This class is the primary entry point for consumers of the\n  Mail Intake library.\n- It orchestrates the full ingestion pipeline:\n    - Querying the adapter for message references.\n    - Fetching raw provider messages.\n    - Parsing and normalizing message data.\n    - Constructing domain models.\n

Constraints:

- This class is intentionally: Provider-agnostic, stateless beyond\n  iteration scope, read-only.\n

Initialize the mail reader.

Parameters:

Name Type Description Default adapter MailIntakeAdapter

Mail adapter implementation used to retrieve raw messages and threads from a mail provider.

required"},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader-functions","title":"Functions","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_messages","title":"iter_messages","text":"
iter_messages(query: str) -> Iterator[MailIntakeMessage]\n

Iterate over parsed messages matching a provider query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeMessage MailIntakeMessage

Fully parsed and normalized MailIntakeMessage instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

"},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_threads","title":"iter_threads","text":"
iter_threads(query: str) -> Iterator[MailIntakeThread]\n

Iterate over threads constructed from messages matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[MailIntakeThread]

Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.

Raises:

Type Description `MailIntakeParsingError`

If a message cannot be parsed.

Notes

Guarantees:

- Messages are grouped by `thread_id` and yielded as complete\n  thread objects containing all associated messages.\n
"},{"location":"ingestion/reader/#mail_intake.ingestion.reader-functions","title":"Functions","text":""},{"location":"mail_intake/","title":"Mail Intake","text":"
  • Adapters
  • Auth
  • Config
  • Credentials
  • Exceptions
  • Ingestion
  • Models
  • Parsers
"},{"location":"mail_intake/#mail_intake","title":"mail_intake","text":""},{"location":"mail_intake/#mail_intake--summary","title":"Summary","text":"

Mail Intake \u2014 provider-agnostic, read-only email ingestion framework.

Mail Intake is a contract-first library designed to ingest, parse, and normalize email data from external providers (such as Gmail) into clean, provider-agnostic domain models.

The library is intentionally structured around clear layers, each exposed as a first-class module at the package root:

  • adapters: Provider-specific access (e.g., Gmail).
  • auth: Authentication providers and credential lifecycle management.
  • credentials: Credential persistence abstractions and implementations.
  • parsers: Extraction and normalization of message content.
  • ingestion: Orchestration and high-level ingestion workflows.
  • models: Canonical, provider-agnostic data representations.
  • config: Explicit global configuration.
  • exceptions: Library-defined error hierarchy.

The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.

"},{"location":"mail_intake/#mail_intake--installation","title":"Installation","text":"

Install using pip:

pip install mail-intake\n

Or with Poetry:

poetry add mail-intake\n

Mail Intake is pure Python and has no runtime dependencies beyond those required by the selected provider (for example, Google APIs for Gmail).

"},{"location":"mail_intake/#mail_intake--quick-start","title":"Quick Start","text":"

Minimal Gmail ingestion example (local development):

from mail_intake.ingestion import MailIntakeReader\nfrom mail_intake.adapters import MailIntakeGmailAdapter\nfrom mail_intake.auth import MailIntakeGoogleAuth\nfrom mail_intake.credentials import PickleCredentialStore\n\nstore = PickleCredentialStore(path=\"token.pickle\")\n\nauth = MailIntakeGoogleAuth(\n    credentials_path=\"credentials.json\",\n    store=store,\n    scopes=[\"https://www.googleapis.com/auth/gmail.readonly\"],\n)\n\nadapter = MailIntakeGmailAdapter(auth_provider=auth)\nreader = MailIntakeReader(adapter)\n\nfor message in reader.iter_messages(\"from:recruiter@example.com\"):\n    print(message.subject, message.from_email)\n

Iterating over threads:

for thread in reader.iter_threads(\"subject:Interview\"):\n    print(thread.normalized_subject, len(thread.messages))\n
"},{"location":"mail_intake/#mail_intake--architecture","title":"Architecture","text":"

Mail Intake is designed to be extensible via public contracts exposed through its modules:

  • Users MAY implement their own mail adapters by subclassing adapters.MailIntakeAdapter.
  • Users MAY implement their own authentication providers by subclassing auth.MailIntakeAuthProvider[T].
  • Users MAY implement their own credential persistence layers by implementing credentials.CredentialStore[T].

Users SHOULD NOT subclass built-in adapter implementations. Built-in adapters (such as Gmail) are reference implementations and may change internally without notice.

Design Guarantees:

  • Read-only access: no mutation of provider state.
  • Provider-agnostic domain models.
  • Explicit configuration and dependency injection.
  • No implicit global state or environment reads.
  • Deterministic, testable behavior.
  • Distributed-safe authentication design.

Mail Intake favors correctness, clarity, and explicitness over convenience shortcuts.

Core Philosophy:

Mail Intake is built as a contract-first ingestion pipeline:

  1. Layered Decoupling: Adapters handle transport, Parsers handle format normalization, and Ingestion orchestrates.
  2. Provider Agnosticism: Domain models and core logic never depend on provider-specific (e.g., Gmail) API internals.
  3. Stateless Workflows: The library functions as a read-only pipe, ensuring side-effect-free ingestion.
"},{"location":"mail_intake/#mail_intake--public-api","title":"Public API","text":"

The supported public API consists of the following top-level modules:

  • mail_intake.ingestion
  • mail_intake.adapters
  • mail_intake.auth
  • mail_intake.credentials
  • mail_intake.parsers
  • mail_intake.models
  • mail_intake.config
  • mail_intake.exceptions

Classes and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.

"},{"location":"mail_intake/config/","title":"Config","text":""},{"location":"mail_intake/config/#mail_intake.config","title":"mail_intake.config","text":""},{"location":"mail_intake/config/#mail_intake.config--summary","title":"Summary","text":"

Global configuration models for Mail Intake.

This module defines the top-level configuration object used to control mail ingestion behavior across adapters, authentication providers, and ingestion workflows.

Configuration is intentionally explicit, immutable, and free of implicit environment reads to ensure predictability and testability.

"},{"location":"mail_intake/config/#mail_intake.config-classes","title":"Classes","text":""},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig","title":"MailIntakeConfig dataclass","text":"
MailIntakeConfig(\n    provider: str = ...,\n    user_id: str = ...,\n    readonly: bool = ...,\n    credentials_path: str | None = ...,\n    token_path: str | None = ...,\n)\n

Global configuration for mail-intake.

Notes

Guarantees:

- This configuration is intentionally explicit and immutable.\n- No implicit environment reads or global state.\n- Explicit configuration over implicit defaults.\n- No direct environment or filesystem access.\n- This model is safe to pass across layers and suitable for\n  serialization.\n
"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig-attributes","title":"Attributes","text":""},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.credentials_path","title":"credentials_path class-attribute instance-attribute","text":"
credentials_path: str | None = None\n

Optional path to provider credentials configuration.

"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.provider","title":"provider class-attribute instance-attribute","text":"
provider: str = 'gmail'\n

Identifier of the mail provider to use (e.g., \"gmail\").

"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.readonly","title":"readonly class-attribute instance-attribute","text":"
readonly: bool = True\n

Whether ingestion should operate in read-only mode.

"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.token_path","title":"token_path class-attribute instance-attribute","text":"
token_path: str | None = None\n

Optional path to persisted authentication tokens.

"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.user_id","title":"user_id class-attribute instance-attribute","text":"
user_id: str = 'me'\n

Provider-specific user identifier. Defaults to the authenticated user.

"},{"location":"mail_intake/exceptions/","title":"Exceptions","text":""},{"location":"mail_intake/exceptions/#mail_intake.exceptions","title":"mail_intake.exceptions","text":""},{"location":"mail_intake/exceptions/#mail_intake.exceptions--summary","title":"Summary","text":"

Exception hierarchy for Mail Intake.

This module defines the canonical exception types used throughout the Mail Intake library.

All library-raised errors derive from MailIntakeError. Consumers are encouraged to catch this base type (or specific subclasses) rather than provider-specific or third-party exceptions.

"},{"location":"mail_intake/exceptions/#mail_intake.exceptions-classes","title":"Classes","text":""},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeAdapterError","title":"MailIntakeAdapterError","text":"

Bases: MailIntakeError

Errors raised by mail provider adapters.

Notes

Lifecycle:

- Raised when a provider adapter encounters API errors, transport\n  failures, or invalid provider responses.\n
"},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeAuthError","title":"MailIntakeAuthError","text":"

Bases: MailIntakeError

Authentication and credential-related failures.

Notes

Lifecycle:

- Raised when authentication providers are unable to acquire,\n  refresh, or persist valid credentials.\n
"},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeError","title":"MailIntakeError","text":"

Bases: Exception

Base exception for all Mail Intake errors.

Notes

Guarantees:

- This is the root of the Mail Intake exception hierarchy\n- All errors raised by the library must derive from this class\n- Consumers should generally catch this type when handling library-level failures\n
"},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeParsingError","title":"MailIntakeParsingError","text":"

Bases: MailIntakeError

Errors encountered while parsing message content.

Notes

Lifecycle:

- Raised when raw provider payloads cannot be interpreted or\n  normalized into internal domain models.\n
"},{"location":"mail_intake/adapters/","title":"Adapters","text":"
  • Base
  • Gmail
"},{"location":"mail_intake/adapters/#mail_intake.adapters","title":"mail_intake.adapters","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters--summary","title":"Summary","text":"

Mail provider adapter implementations for Mail Intake.

This package contains adapter-layer implementations responsible for interfacing with external mail providers and exposing a normalized, provider-agnostic contract to the rest of the system.

Adapters in this package:

  • Implement the MailIntakeAdapter interface.
  • Encapsulate all provider-specific APIs and semantics.
  • Perform read-only access to mail data.
  • Return provider-native payloads without interpretation.

Provider-specific logic must not leak outside of adapter implementations. All parsings, normalizations, and transformations must be handled by downstream components.

"},{"location":"mail_intake/adapters/#mail_intake.adapters--public-api","title":"Public API","text":"
  • MailIntakeAdapter
  • MailIntakeGmailAdapter
"},{"location":"mail_intake/adapters/#mail_intake.adapters-classes","title":"Classes","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter","title":"MailIntakeAdapter","text":"

Bases: ABC

Base adapter interface for mail providers.

Notes

Guarantees:

- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\n

Lifecycle:

- Adapters are intentionally read-only and must not mutate provider state.\n
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_message","title":"fetch_message abstractmethod","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full raw message by message identifier.

Parameters:

Name Type Description Default message_id str

Provider-specific message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_thread","title":"fetch_thread abstractmethod","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full raw thread by thread identifier.

Parameters:

Name Type Description Default thread_id str

Provider-specific thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native thread payload.

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs abstractmethod","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over lightweight message references matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[dict[str, str]]

Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message and thread identifiers.

Notes

Guarantees:

- Implementations must yield dictionaries containing at least\n  `message_id` and `thread_id`.\n
Example

Typical yield:

{\n    \"message_id\": \"...\",\n    \"thread_id\": \"...\"\n}\n
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"
MailIntakeGmailAdapter(\n    auth_provider: MailIntakeAuthProvider[Any],\n    user_id: str = \"me\",\n)\n

Bases: MailIntakeAdapter

Gmail read-only adapter.

This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.

Notes

Responsibilities:

- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\n

Constraints:

- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\n

Initialize the Gmail adapter.

Parameters:

Name Type Description Default auth_provider MailIntakeAuthProvider

Authentication provider capable of supplying valid Gmail API credentials.

required user_id str

Gmail user identifier. Defaults to \"me\".

'me'"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.service","title":"service property","text":"
service: Any\n

Lazily initialize and return the Gmail API service client.

Raises:

Type Description MailIntakeAdapterError

If the Gmail service cannot be initialized.

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full Gmail message by message ID.

Parameters:

Name Type Description Default message_id str

Gmail message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail message payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full Gmail thread by thread ID.

Parameters:

Name Type Description Default thread_id str

Gmail thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail thread payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over message references matching the query.

Parameters:

Name Type Description Default query str

Gmail search query string.

required

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message_id and thread_id.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"mail_intake/adapters/base/","title":"Base","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base","title":"mail_intake.adapters.base","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base--summary","title":"Summary","text":"

Mail provider adapter contracts for Mail Intake.

This module defines the provider-agnostic adapter interface used for read-only mail ingestion.

Adapters encapsulate all provider-specific access logic and expose a minimal, normalized contract to the rest of the system. No provider-specific types or semantics should leak beyond implementations of this interface.

"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base-classes","title":"Classes","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter","title":"MailIntakeAdapter","text":"

Bases: ABC

Base adapter interface for mail providers.

Notes

Guarantees:

- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\n

Lifecycle:

- Adapters are intentionally read-only and must not mutate provider state.\n
"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_message","title":"fetch_message abstractmethod","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full raw message by message identifier.

Parameters:

Name Type Description Default message_id str

Provider-specific message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).

"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_thread","title":"fetch_thread abstractmethod","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full raw thread by thread identifier.

Parameters:

Name Type Description Default thread_id str

Provider-specific thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native thread payload.

"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs abstractmethod","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over lightweight message references matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[dict[str, str]]

Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message and thread identifiers.

Notes

Guarantees:

- Implementations must yield dictionaries containing at least\n  `message_id` and `thread_id`.\n
Example

Typical yield:

{\n    \"message_id\": \"...\",\n    \"thread_id\": \"...\"\n}\n
"},{"location":"mail_intake/adapters/gmail/","title":"Gmail","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail","title":"mail_intake.adapters.gmail","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail--summary","title":"Summary","text":"

Gmail adapter implementation for Mail Intake.

This module provides a Gmail-specific implementation of the MailIntakeAdapter contract.

It is the only place in the codebase where:

  • googleapiclient is imported.
  • Gmail REST API semantics are known.
  • Low-level .execute() calls are made.

All Gmail-specific behavior must be strictly contained within this module.

"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail-classes","title":"Classes","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"
MailIntakeGmailAdapter(\n    auth_provider: MailIntakeAuthProvider[Any],\n    user_id: str = \"me\",\n)\n

Bases: MailIntakeAdapter

Gmail read-only adapter.

This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.

Notes

Responsibilities:

- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\n

Constraints:

- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\n

Initialize the Gmail adapter.

Parameters:

Name Type Description Default auth_provider MailIntakeAuthProvider

Authentication provider capable of supplying valid Gmail API credentials.

required user_id str

Gmail user identifier. Defaults to \"me\".

'me'"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.service","title":"service property","text":"
service: Any\n

Lazily initialize and return the Gmail API service client.

Raises:

Type Description MailIntakeAdapterError

If the Gmail service cannot be initialized.

"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"
fetch_message(message_id: str) -> dict[str, Any]\n

Fetch a full Gmail message by message ID.

Parameters:

Name Type Description Default message_id str

Gmail message identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail message payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"
fetch_thread(thread_id: str) -> dict[str, Any]\n

Fetch a full Gmail thread by thread ID.

Parameters:

Name Type Description Default thread_id str

Gmail thread identifier.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Provider-native Gmail thread payload.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"
iter_message_refs(query: str) -> Iterator[dict[str, str]]\n

Iterate over message references matching the query.

Parameters:

Name Type Description Default query str

Gmail search query string.

required

Yields:

Type Description dict[str, str]

dict[str, str]: Dictionaries containing message_id and thread_id.

Raises:

Type Description MailIntakeAdapterError

If the Gmail API returns an error.

"},{"location":"mail_intake/auth/","title":"Auth","text":"
  • Base
  • Google
"},{"location":"mail_intake/auth/#mail_intake.auth","title":"mail_intake.auth","text":""},{"location":"mail_intake/auth/#mail_intake.auth--summary","title":"Summary","text":"

Authentication provider implementations for Mail Intake.

This package defines the authentication layer used by mail adapters to obtain provider-specific credentials.

It exposes:

  • A stable, provider-agnostic authentication contract.
  • Concrete authentication providers for supported platforms.

Authentication providers:

  • Are responsible for credential acquisition and lifecycle management.
  • Are intentionally decoupled from adapter logic.
  • May be extended by users to support additional providers.

Consumers should depend on the abstract interface and use concrete implementations only where explicitly required.

"},{"location":"mail_intake/auth/#mail_intake.auth--public-api","title":"Public API","text":"
  • MailIntakeAuthProvider
  • MailIntakeGoogleAuth
"},{"location":"mail_intake/auth/#mail_intake.auth-classes","title":"Classes","text":""},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"

Bases: ABC, Generic[T]

Abstract base class for authentication providers.

This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.

Notes

Responsibilities:

- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\n

Constraints:

- Mail adapters must treat returned credentials as opaque and\n  provider-specific.\n- Mail adapters rely only on the declared credential type expected\n  by the adapter.\n
"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeAuthProvider-functions","title":"Functions","text":""},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeAuthProvider.get_credentials","title":"get_credentials abstractmethod","text":"
get_credentials() -> T\n

Retrieve valid, provider-specific credentials.

Returns:

Name Type Description T T

Credentials of type T suitable for immediate use by the corresponding mail adapter.

Raises:

Type Description Exception

An authentication-specific exception indicating that credentials could not be obtained or validated.

Notes

Guarantees:

- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n  authentication material.\n- Implementations must either return credentials of the declared\n  type `T` that are valid at the time of return or raise an exception.\n
"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"
MailIntakeGoogleAuth(\n    credentials_path: str,\n    store: CredentialStore[Any],\n    scopes: Sequence[str],\n)\n

Bases: MailIntakeAuthProvider

Google OAuth provider for Gmail access.

This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.

Notes

Responsibilities:

- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\n

Guarantees:

- This class is synchronous by design and maintains a minimal\n  internal state.\n

Initialize the Google authentication provider.

Parameters:

Name Type Description Default credentials_path str

Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.

required store CredentialStore[Credentials]

Credential store responsible for persisting and retrieving Google OAuth credentials.

required scopes Sequence[str]

OAuth scopes required for Gmail access.

required"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"
get_credentials() -> Any\n

Retrieve valid Google OAuth credentials.

Returns:

Name Type Description Credentials Any

A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.

Raises:

Type Description MailIntakeAuthError

If credentials cannot be loaded, refreshed, or obtained via interactive authentication.

Notes

Lifecycle:

- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\n
"},{"location":"mail_intake/auth/base/","title":"Base","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base","title":"mail_intake.auth.base","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base--summary","title":"Summary","text":"

Authentication provider contracts for Mail Intake.

This module defines the authentication abstraction layer used by mail adapters to obtain provider-specific credentials.

Authentication concerns are intentionally decoupled from adapter logic. Adapters depend only on this interface and must not be aware of how credentials are acquired, refreshed, or persisted.

"},{"location":"mail_intake/auth/base/#mail_intake.auth.base-classes","title":"Classes","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"

Bases: ABC, Generic[T]

Abstract base class for authentication providers.

This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.

Notes

Responsibilities:

- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\n

Constraints:

- Mail adapters must treat returned credentials as opaque and\n  provider-specific.\n- Mail adapters rely only on the declared credential type expected\n  by the adapter.\n
"},{"location":"mail_intake/auth/base/#mail_intake.auth.base.MailIntakeAuthProvider-functions","title":"Functions","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base.MailIntakeAuthProvider.get_credentials","title":"get_credentials abstractmethod","text":"
get_credentials() -> T\n

Retrieve valid, provider-specific credentials.

Returns:

Name Type Description T T

Credentials of type T suitable for immediate use by the corresponding mail adapter.

Raises:

Type Description Exception

An authentication-specific exception indicating that credentials could not be obtained or validated.

Notes

Guarantees:

- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n  authentication material.\n- Implementations must either return credentials of the declared\n  type `T` that are valid at the time of return or raise an exception.\n
"},{"location":"mail_intake/auth/google/","title":"Google","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google","title":"mail_intake.auth.google","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google--summary","title":"Summary","text":"

Google authentication provider implementation for Mail Intake.

This module provides a Google OAuth\u2013based authentication provider used primarily for Gmail access.

It encapsulates all Google-specific authentication concerns, including:

  • Credential loading and persistence.
  • Token refresh handling.
  • Interactive OAuth flow initiation.
  • Coordination with a credential persistence layer.

No Google authentication details should leak outside this module.

"},{"location":"mail_intake/auth/google/#mail_intake.auth.google-classes","title":"Classes","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"
MailIntakeGoogleAuth(\n    credentials_path: str,\n    store: CredentialStore[Any],\n    scopes: Sequence[str],\n)\n

Bases: MailIntakeAuthProvider

Google OAuth provider for Gmail access.

This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.

Notes

Responsibilities:

- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\n

Guarantees:

- This class is synchronous by design and maintains a minimal\n  internal state.\n

Initialize the Google authentication provider.

Parameters:

Name Type Description Default credentials_path str

Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.

required store CredentialStore[Credentials]

Credential store responsible for persisting and retrieving Google OAuth credentials.

required scopes Sequence[str]

OAuth scopes required for Gmail access.

required"},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"
get_credentials() -> Any\n

Retrieve valid Google OAuth credentials.

Returns:

Name Type Description Credentials Any

A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.

Raises:

Type Description MailIntakeAuthError

If credentials cannot be loaded, refreshed, or obtained via interactive authentication.

Notes

Lifecycle:

- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\n
"},{"location":"mail_intake/credentials/","title":"Credentials","text":"
  • Pickle
  • Redis
  • Store
"},{"location":"mail_intake/credentials/#mail_intake.credentials","title":"mail_intake.credentials","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials--summary","title":"Summary","text":"

Credential persistence interfaces and implementations for Mail Intake.

This package defines the abstractions and concrete implementations used to persist authentication credentials across Mail Intake components.

The credential persistence layer is intentionally decoupled from authentication logic. Authentication providers are responsible for credential acquisition, validation, and refresh, while implementations within this package are responsible solely for storage and retrieval.

The package provides:

  • A generic CredentialStore abstraction defining the persistence contract.
  • Local filesystem\u2013based storage for development and single-node use.
  • Distributed, Redis-backed storage for production and scaled deployments.

Credential lifecycle management, interpretation, and security policy decisions remain the responsibility of authentication providers.

"},{"location":"mail_intake/credentials/#mail_intake.credentials--public-api","title":"Public API","text":"
  • CredentialStore
  • PickleCredentialStore
  • RedisCredentialStore
"},{"location":"mail_intake/credentials/#mail_intake.credentials-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore","title":"CredentialStore","text":"

Bases: ABC, Generic[T]

Abstract base class defining a generic persistence interface.

Used for authentication credentials across different backends.

Notes

Responsibilities:

- Provide persistent storage separating life-cycle management from\n  storage mechanics.\n- Keep implementation focused only on persistence.\n

Constraints:

- The store is intentionally agnostic to:\n    - The concrete credential type being stored.\n    - The serialization format used to persist credentials.\n    - The underlying storage backend or durability guarantees.\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore.clear","title":"clear abstractmethod","text":"
clear() -> None\n

Remove any persisted credentials from the store.

Notes

Lifecycle:

- This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n- Must ensure that no stale authentication material remains accessible\n

Guarantees:

- Implementations should treat this operation as idempotent\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore.load","title":"load abstractmethod","text":"
load() -> T | None\n

Load previously persisted credentials.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are available and loadable; otherwise None.

Notes

Guarantees:

- Implementations should return `None` when no credentials are\n  present or when stored credentials cannot be successfully\n  decoded or deserialized.\n- The store must not attempt to validate, refresh, or otherwise\n  interpret the returned credentials.\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore.save","title":"save abstractmethod","text":"
save(credentials: T) -> None\n

Persist credentials to the underlying storage backend.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Lifecycle:

- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n

Responsibilities:

- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore","title":"PickleCredentialStore","text":"
PickleCredentialStore(path: str)\n

Bases: CredentialStore[T]

Filesystem-backed credential store using pickle serialization.

This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.

Notes

Guarantees:

- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\n

Constraints:

- Credential lifecycle management, validation, and refresh logic are\n  explicitly out of scope for this class.\n

Initialize a pickle-backed credential store.

Parameters:

Name Type Description Default path str

Filesystem path where credentials will be stored. The file will be created or overwritten as needed.

required"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove persisted credentials from the local filesystem.

Notes

Lifecycle:

- This method deletes the credential file if it exists and should be treated as an idempotent operation\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from the local filesystem.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If the credential file does not exist or cannot be successfully\n  deserialized, this method returns `None`.\n- The store does not attempt to validate or interpret the\n  returned credentials.\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to the local filesystem.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials at the configured path are overwritten\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore","title":"RedisCredentialStore","text":"
RedisCredentialStore(\n    redis_client: Any,\n    key: str,\n    serialize: Callable[[T], bytes],\n    deserialize: Callable[[bytes], T],\n    ttl_seconds: int | None = None,\n)\n

Bases: CredentialStore[T]

Redis-backed implementation of CredentialStore.

This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.

Notes

Responsibilities:

- This class is responsible only for persistence and retrieval.\n- It does not interpret, validate, refresh, or otherwise manage the\n  lifecycle of the credentials being stored.\n

Guarantees:

- The store is intentionally generic and delegates all serialization\n  concerns to caller-provided functions.\n- This avoids unsafe mechanisms such as `pickle` and allows\n  credential formats to be explicitly controlled and audited.\n

Initialize a Redis-backed credential store.

Parameters:

Name Type Description Default redis_client Any

Initialized Redis client instance used for persistence.

required key str

Storage key under which credentials are persisted.

required serialize Callable[[T], bytes]

Callable that encodes credentials to bytes for storage.

required deserialize Callable[[bytes], T]

Callable that decodes stored bytes back into credentials.

required ttl_seconds int | None

Optional time-to-live in seconds after which stored credentials expire automatically. None disables expiry.

None"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove stored credentials from Redis.

Notes

Lifecycle:

- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from Redis.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If no value exists for the configured key, or if the stored\n  payload cannot be successfully deserialized, this method\n  returns `None`.\n- The store does not attempt to validate the returned\n  credentials or determine whether they are expired or\n  otherwise usable.\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to Redis.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials under the same key are overwritten\n- If a TTL is configured, the credentials will expire automatically after the specified duration\n
"},{"location":"mail_intake/credentials/pickle/","title":"Pickle","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle","title":"mail_intake.credentials.pickle","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle--summary","title":"Summary","text":"

Local filesystem\u2013based credential persistence for Mail Intake.

This module provides a file-backed implementation of the CredentialStore abstraction using Python's pickle module.

The pickle-based credential store is intended for local development, single-node deployments, and controlled environments where credentials do not need to be shared across processes or machines.

Due to the security and portability risks associated with pickle-based serialization, this implementation is not suitable for distributed or untrusted environments.

"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore","title":"PickleCredentialStore","text":"
PickleCredentialStore(path: str)\n

Bases: CredentialStore[T]

Filesystem-backed credential store using pickle serialization.

This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.

Notes

Guarantees:

- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\n

Constraints:

- Credential lifecycle management, validation, and refresh logic are\n  explicitly out of scope for this class.\n

Initialize a pickle-backed credential store.

Parameters:

Name Type Description Default path str

Filesystem path where credentials will be stored. The file will be created or overwritten as needed.

required"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove persisted credentials from the local filesystem.

Notes

Lifecycle:

- This method deletes the credential file if it exists and should be treated as an idempotent operation\n
"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from the local filesystem.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If the credential file does not exist or cannot be successfully\n  deserialized, this method returns `None`.\n- The store does not attempt to validate or interpret the\n  returned credentials.\n
"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to the local filesystem.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials at the configured path are overwritten\n
"},{"location":"mail_intake/credentials/redis/","title":"Redis","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis","title":"mail_intake.credentials.redis","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis--summary","title":"Summary","text":"

Redis-backed credential persistence for Mail Intake.

This module provides a Redis-based implementation of the CredentialStore abstraction, enabling credential persistence across distributed and horizontally scaled deployments.

The Redis credential store is designed for environments where authentication credentials must be shared safely across multiple processes, containers, or nodes, such as container orchestration platforms and microservice architectures.

Key characteristics:

  • Distributed-safe, shared storage using Redis.
  • Explicit, caller-defined serialization and deserialization.
  • No reliance on unsafe mechanisms such as pickle.
  • Optional time-to-live (TTL) support for automatic credential expiry.

This module is responsible solely for persistence concerns. Credential validation, refresh, rotation, and acquisition remain the responsibility of authentication provider implementations.

"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore","title":"RedisCredentialStore","text":"
RedisCredentialStore(\n    redis_client: Any,\n    key: str,\n    serialize: Callable[[T], bytes],\n    deserialize: Callable[[bytes], T],\n    ttl_seconds: int | None = None,\n)\n

Bases: CredentialStore[T]

Redis-backed implementation of CredentialStore.

This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.

Notes

Responsibilities:

- This class is responsible only for persistence and retrieval.\n- It does not interpret, validate, refresh, or otherwise manage the\n  lifecycle of the credentials being stored.\n

Guarantees:

- The store is intentionally generic and delegates all serialization\n  concerns to caller-provided functions.\n- This avoids unsafe mechanisms such as `pickle` and allows\n  credential formats to be explicitly controlled and audited.\n

Initialize a Redis-backed credential store.

Parameters:

Name Type Description Default redis_client Any

Initialized Redis client instance used for persistence.

required key str

Storage key under which credentials are persisted.

required serialize Callable[[T], bytes]

Callable that encodes credentials to bytes for storage.

required deserialize Callable[[bytes], T]

Callable that decodes stored bytes back into credentials.

required ttl_seconds int | None

Optional time-to-live in seconds after which stored credentials expire automatically. None disables expiry.

None"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove stored credentials from Redis.

Notes

Lifecycle:

- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\n
"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.load","title":"load","text":"
load() -> T | None\n

Load credentials from Redis.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If no value exists for the configured key, or if the stored\n  payload cannot be successfully deserialized, this method\n  returns `None`.\n- The store does not attempt to validate the returned\n  credentials or determine whether they are expired or\n  otherwise usable.\n
"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to Redis.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials under the same key are overwritten\n- If a TTL is configured, the credentials will expire automatically after the specified duration\n
"},{"location":"mail_intake/credentials/store/","title":"Store","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store","title":"mail_intake.credentials.store","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store--summary","title":"Summary","text":"

Credential persistence abstractions for Mail Intake.

This module defines the generic persistence contract used to store and retrieve authentication credentials across Mail Intake components.

The CredentialStore abstraction establishes a strict separation between credential lifecycle management and credential storage. Authentication providers are responsible for acquiring, validating, refreshing, and revoking credentials, while concrete store implementations are responsible solely for persistence concerns.

By remaining agnostic to credential structure, serialization format, and storage backend, this module enables multiple persistence strategies\u2014such as local files, in-memory caches, distributed stores, or secrets managers\u2014without coupling authentication logic to any specific storage mechanism.

"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore","title":"CredentialStore","text":"

Bases: ABC, Generic[T]

Abstract base class defining a generic persistence interface.

Used for authentication credentials across different backends.

Notes

Responsibilities:

- Provide persistent storage separating life-cycle management from\n  storage mechanics.\n- Keep implementation focused only on persistence.\n

Constraints:

- The store is intentionally agnostic to:\n    - The concrete credential type being stored.\n    - The serialization format used to persist credentials.\n    - The underlying storage backend or durability guarantees.\n
"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore.clear","title":"clear abstractmethod","text":"
clear() -> None\n

Remove any persisted credentials from the store.

Notes

Lifecycle:

- This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n- Must ensure that no stale authentication material remains accessible\n

Guarantees:

- Implementations should treat this operation as idempotent\n
"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore.load","title":"load abstractmethod","text":"
load() -> T | None\n

Load previously persisted credentials.

Returns:

Type Description T | None

T | None: An instance of type T if credentials are available and loadable; otherwise None.

Notes

Guarantees:

- Implementations should return `None` when no credentials are\n  present or when stored credentials cannot be successfully\n  decoded or deserialized.\n- The store must not attempt to validate, refresh, or otherwise\n  interpret the returned credentials.\n
"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore.save","title":"save abstractmethod","text":"
save(credentials: T) -> None\n

Persist credentials to the underlying storage backend.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Lifecycle:

- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n

Responsibilities:

- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n
"},{"location":"mail_intake/ingestion/","title":"Ingestion","text":"
  • Reader
"},{"location":"mail_intake/ingestion/#mail_intake.ingestion","title":"mail_intake.ingestion","text":""},{"location":"mail_intake/ingestion/#mail_intake.ingestion--summary","title":"Summary","text":"

Mail ingestion orchestration for Mail Intake.

This package contains high-level ingestion components responsible for coordinating mail retrieval, parsing, normalization, and model construction.

It represents the top of the ingestion pipeline and is intended to be the primary interaction surface for library consumers.

Components in this package:

  • Are provider-agnostic.
  • Depend only on adapter and parser contracts.
  • Contain no provider-specific API logic.
  • Expose read-only ingestion workflows.

Consumers are expected to construct a mail adapter and pass it to the ingestion layer to begin processing messages and threads.

"},{"location":"mail_intake/ingestion/#mail_intake.ingestion--public-api","title":"Public API","text":"
  • MailIntakeReader
"},{"location":"mail_intake/ingestion/#mail_intake.ingestion-classes","title":"Classes","text":""},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader","title":"MailIntakeReader","text":"
MailIntakeReader(adapter: MailIntakeAdapter)\n

High-level read-only ingestion interface.

Notes

Responsibilities:

- This class is the primary entry point for consumers of the\n  Mail Intake library.\n- It orchestrates the full ingestion pipeline:\n    - Querying the adapter for message references.\n    - Fetching raw provider messages.\n    - Parsing and normalizing message data.\n    - Constructing domain models.\n

Constraints:

- This class is intentionally: Provider-agnostic, stateless beyond\n  iteration scope, read-only.\n

Initialize the mail reader.

Parameters:

Name Type Description Default adapter MailIntakeAdapter

Mail adapter implementation used to retrieve raw messages and threads from a mail provider.

required"},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader-functions","title":"Functions","text":""},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader.iter_messages","title":"iter_messages","text":"
iter_messages(query: str) -> Iterator[MailIntakeMessage]\n

Iterate over parsed messages matching a provider query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeMessage MailIntakeMessage

Fully parsed and normalized MailIntakeMessage instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

"},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader.iter_threads","title":"iter_threads","text":"
iter_threads(query: str) -> Iterator[MailIntakeThread]\n

Iterate over threads constructed from messages matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[MailIntakeThread]

Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.

Raises:

Type Description `MailIntakeParsingError`

If a message cannot be parsed.

Notes

Guarantees:

- Messages are grouped by `thread_id` and yielded as complete\n  thread objects containing all associated messages.\n
"},{"location":"mail_intake/ingestion/reader/","title":"Reader","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader","title":"mail_intake.ingestion.reader","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader--summary","title":"Summary","text":"

High-level mail ingestion orchestration for Mail Intake.

This module provides the primary, provider-agnostic entry point for reading and processing mail data.

It coordinates:

  • Mail adapter access.
  • Message and thread iteration.
  • Header and body parsing.
  • Normalization and model construction.

No provider-specific logic or API semantics are permitted in this layer.

"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader-classes","title":"Classes","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader","title":"MailIntakeReader","text":"
MailIntakeReader(adapter: MailIntakeAdapter)\n

High-level read-only ingestion interface.

Notes

Responsibilities:

- This class is the primary entry point for consumers of the\n  Mail Intake library.\n- It orchestrates the full ingestion pipeline:\n    - Querying the adapter for message references.\n    - Fetching raw provider messages.\n    - Parsing and normalizing message data.\n    - Constructing domain models.\n

Constraints:

- This class is intentionally: Provider-agnostic, stateless beyond\n  iteration scope, read-only.\n

Initialize the mail reader.

Parameters:

Name Type Description Default adapter MailIntakeAdapter

Mail adapter implementation used to retrieve raw messages and threads from a mail provider.

required"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader-functions","title":"Functions","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_messages","title":"iter_messages","text":"
iter_messages(query: str) -> Iterator[MailIntakeMessage]\n

Iterate over parsed messages matching a provider query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeMessage MailIntakeMessage

Fully parsed and normalized MailIntakeMessage instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_threads","title":"iter_threads","text":"
iter_threads(query: str) -> Iterator[MailIntakeThread]\n

Iterate over threads constructed from messages matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Returns:

Type Description Iterator[MailIntakeThread]

Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.

Raises:

Type Description `MailIntakeParsingError`

If a message cannot be parsed.

Notes

Guarantees:

- Messages are grouped by `thread_id` and yielded as complete\n  thread objects containing all associated messages.\n
"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader-functions","title":"Functions","text":""},{"location":"mail_intake/models/","title":"Models","text":"
  • Message
  • Thread
"},{"location":"mail_intake/models/#mail_intake.models","title":"mail_intake.models","text":""},{"location":"mail_intake/models/#mail_intake.models--summary","title":"Summary","text":"

Domain models for Mail Intake.

This package defines the canonical, provider-agnostic data models used throughout the Mail Intake ingestion pipeline.

Models in this package:

  • Represent fully parsed and normalized mail data.
  • Are safe to persist, serialize, and index.
  • Contain no provider-specific payloads or API semantics.
  • Serve as stable inputs for downstream processing and analysis.

These models form the core internal data contract of the library.

"},{"location":"mail_intake/models/#mail_intake.models--public-api","title":"Public API","text":"
  • MailIntakeMessage
  • MailIntakeThread
"},{"location":"mail_intake/models/#mail_intake.models-classes","title":"Classes","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage","title":"MailIntakeMessage dataclass","text":"
MailIntakeMessage(\n    message_id: str,\n    thread_id: str,\n    timestamp: datetime,\n    from_email: str,\n    from_name: str | None,\n    subject: str,\n    body_text: str,\n    snippet: str,\n    raw_headers: dict[str, str],\n)\n

Canonical internal representation of a single email message.

Notes

Guarantees:

- This model represents a fully parsed and normalized email message.\n- It is intentionally provider-agnostic and suitable for\n  persistence, indexing, and downstream processing.\n

Constraints:

- No provider-specific identifiers, payloads, or API semantics\n  should appear in this model.\n
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage-attributes","title":"Attributes","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.body_text","title":"body_text instance-attribute","text":"
body_text: str\n

Extracted plain-text body content of the message.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.from_email","title":"from_email instance-attribute","text":"
from_email: str\n

Sender email address.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.from_name","title":"from_name instance-attribute","text":"
from_name: str | None\n

Optional human-readable sender name.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.message_id","title":"message_id instance-attribute","text":"
message_id: str\n

Provider-specific message identifier.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.raw_headers","title":"raw_headers instance-attribute","text":"
raw_headers: dict[str, str]\n

Normalized mapping of message headers (header name \u2192 value).

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.snippet","title":"snippet instance-attribute","text":"
snippet: str\n

Short provider-supplied preview snippet of the message.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.subject","title":"subject instance-attribute","text":"
subject: str\n

Raw subject line of the message.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier to which this message belongs.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.timestamp","title":"timestamp instance-attribute","text":"
timestamp: datetime\n

Message timestamp as a timezone-naive UTC datetime.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread","title":"MailIntakeThread dataclass","text":"
MailIntakeThread(\n    thread_id: str,\n    normalized_subject: str,\n    participants: set[str] = ...,\n    messages: list[MailIntakeMessage] = ...,\n    last_activity_at: datetime | None = ...,\n)\n

Canonical internal representation of an email thread.

Notes

Guarantees:

- A thread groups multiple related messages under a single subject\n  and participant set.\n- It is designed to support reasoning over conversational context\n  such as job applications, interviews, follow-ups, and ongoing discussions.\n- This model is provider-agnostic and safe to persist.\n
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread-attributes","title":"Attributes","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.last_activity_at","title":"last_activity_at class-attribute instance-attribute","text":"
last_activity_at: datetime | None = None\n

Timestamp of the most recent message in the thread.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.messages","title":"messages class-attribute instance-attribute","text":"
messages: list[MailIntakeMessage] = field(\n    default_factory=list\n)\n

Ordered list of messages belonging to this thread.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.normalized_subject","title":"normalized_subject instance-attribute","text":"
normalized_subject: str\n

Normalized subject line used to group related messages.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.participants","title":"participants class-attribute instance-attribute","text":"
participants: set[str] = field(default_factory=set)\n

Set of unique participant email addresses observed in the thread.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread-functions","title":"Functions","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.add_message","title":"add_message","text":"
add_message(message: MailIntakeMessage) -> None\n

Add a message to the thread and update derived fields.

Parameters:

Name Type Description Default message MailIntakeMessage

Parsed mail message to add to the thread.

required Notes

Responsibilities:

- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\n
"},{"location":"mail_intake/models/message/","title":"Message","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message","title":"mail_intake.models.message","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message--summary","title":"Summary","text":"

Message domain models for Mail Intake.

This module defines the canonical, provider-agnostic representation of an individual email message as used internally by the Mail Intake ingestion pipeline.

Models in this module are safe to persist and must not contain any provider-specific fields or semantics.

"},{"location":"mail_intake/models/message/#mail_intake.models.message-classes","title":"Classes","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage","title":"MailIntakeMessage dataclass","text":"
MailIntakeMessage(\n    message_id: str,\n    thread_id: str,\n    timestamp: datetime,\n    from_email: str,\n    from_name: str | None,\n    subject: str,\n    body_text: str,\n    snippet: str,\n    raw_headers: dict[str, str],\n)\n

Canonical internal representation of a single email message.

Notes

Guarantees:

- This model represents a fully parsed and normalized email message.\n- It is intentionally provider-agnostic and suitable for\n  persistence, indexing, and downstream processing.\n

Constraints:

- No provider-specific identifiers, payloads, or API semantics\n  should appear in this model.\n
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage-attributes","title":"Attributes","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.body_text","title":"body_text instance-attribute","text":"
body_text: str\n

Extracted plain-text body content of the message.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.from_email","title":"from_email instance-attribute","text":"
from_email: str\n

Sender email address.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.from_name","title":"from_name instance-attribute","text":"
from_name: str | None\n

Optional human-readable sender name.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.message_id","title":"message_id instance-attribute","text":"
message_id: str\n

Provider-specific message identifier.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.raw_headers","title":"raw_headers instance-attribute","text":"
raw_headers: dict[str, str]\n

Normalized mapping of message headers (header name \u2192 value).

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.snippet","title":"snippet instance-attribute","text":"
snippet: str\n

Short provider-supplied preview snippet of the message.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.subject","title":"subject instance-attribute","text":"
subject: str\n

Raw subject line of the message.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier to which this message belongs.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.timestamp","title":"timestamp instance-attribute","text":"
timestamp: datetime\n

Message timestamp as a timezone-naive UTC datetime.

"},{"location":"mail_intake/models/thread/","title":"Thread","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread","title":"mail_intake.models.thread","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread--summary","title":"Summary","text":"

Thread domain models for Mail Intake.

This module defines the canonical, provider-agnostic representation of an email thread as used internally by the Mail Intake ingestion pipeline.

Threads group related messages and serve as the primary unit of reasoning for higher-level correspondence workflows.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread-classes","title":"Classes","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread","title":"MailIntakeThread dataclass","text":"
MailIntakeThread(\n    thread_id: str,\n    normalized_subject: str,\n    participants: set[str] = ...,\n    messages: list[MailIntakeMessage] = ...,\n    last_activity_at: datetime | None = ...,\n)\n

Canonical internal representation of an email thread.

Notes

Guarantees:

- A thread groups multiple related messages under a single subject\n  and participant set.\n- It is designed to support reasoning over conversational context\n  such as job applications, interviews, follow-ups, and ongoing discussions.\n- This model is provider-agnostic and safe to persist.\n
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread-attributes","title":"Attributes","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.last_activity_at","title":"last_activity_at class-attribute instance-attribute","text":"
last_activity_at: datetime | None = None\n

Timestamp of the most recent message in the thread.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.messages","title":"messages class-attribute instance-attribute","text":"
messages: list[MailIntakeMessage] = field(\n    default_factory=list\n)\n

Ordered list of messages belonging to this thread.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.normalized_subject","title":"normalized_subject instance-attribute","text":"
normalized_subject: str\n

Normalized subject line used to group related messages.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.participants","title":"participants class-attribute instance-attribute","text":"
participants: set[str] = field(default_factory=set)\n

Set of unique participant email addresses observed in the thread.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread-functions","title":"Functions","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.add_message","title":"add_message","text":"
add_message(message: MailIntakeMessage) -> None\n

Add a message to the thread and update derived fields.

Parameters:

Name Type Description Default message MailIntakeMessage

Parsed mail message to add to the thread.

required Notes

Responsibilities:

- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\n
"},{"location":"mail_intake/parsers/","title":"Parsers","text":"
  • Body
  • Headers
  • Subject
"},{"location":"mail_intake/parsers/#mail_intake.parsers","title":"mail_intake.parsers","text":""},{"location":"mail_intake/parsers/#mail_intake.parsers--summary","title":"Summary","text":"

Message parsing utilities for Mail Intake.

This package contains provider-aware but adapter-agnostic parsing helpers used to extract and normalize structured information from raw mail payloads.

Parsers in this package are responsible for:

  • Interpreting provider-native message structures.
  • Extracting meaningful fields such as headers, body text, and subjects.
  • Normalizing data into consistent internal representations.

This package does not:

  • Perform network or IO operations.
  • Contain provider API logic.
  • Construct domain models directly.

Parsing functions are designed to be composable and are orchestrated by the ingestion layer.

"},{"location":"mail_intake/parsers/#mail_intake.parsers--public-api","title":"Public API","text":"
  • extract_body
  • parse_headers
  • extract_sender
  • normalize_subject
"},{"location":"mail_intake/parsers/#mail_intake.parsers-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/#mail_intake.parsers.extract_body","title":"extract_body","text":"
extract_body(payload: dict[str, Any]) -> str\n

Extract the best-effort message body from a Gmail payload.

Priority:

  1. text/plain
  2. text/html (stripped to text)
  3. Single-part body
  4. Empty string (if nothing usable found)

Parameters:

Name Type Description Default payload dict[str, Any]

Provider-native message payload dictionary.

required

Returns:

Name Type Description str str

Extracted plain-text message body.

"},{"location":"mail_intake/parsers/#mail_intake.parsers.extract_sender","title":"extract_sender","text":"
extract_sender(\n    headers: dict[str, str],\n) -> tuple[str, str | None]\n

Extract sender email and optional display name from headers.

Parameters:

Name Type Description Default headers dict[str, str]

Normalized header dictionary as returned by parse_headers().

required

Returns:

Type Description tuple[str, str | None]

tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.

Notes

Responsibilities:

- This function parses the `From` header and attempts to extract\n  sender email address and optional human-readable display name.\n
Example

Typical values:

  • \"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")
  • \"john@example.com\" -> (\"john@example.com\", None)
"},{"location":"mail_intake/parsers/#mail_intake.parsers.normalize_subject","title":"normalize_subject","text":"
normalize_subject(subject: str) -> str\n

Normalize an email subject for thread-level comparison.

Parameters:

Name Type Description Default subject str

Raw subject line from a message header.

required

Returns:

Name Type Description str str

Normalized subject string suitable for thread grouping.

Notes

Responsibilities:

- Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n- Repeats prefix stripping to handle stacked prefixes.\n- Collapses excessive whitespace.\n- Preserves original casing (no lowercasing).\n

Guarantees:

- This function is intentionally conservative and avoids aggressive\n  transformations that could alter the semantic meaning of the subject.\n
"},{"location":"mail_intake/parsers/#mail_intake.parsers.parse_headers","title":"parse_headers","text":"
parse_headers(\n    raw_headers: list[dict[str, str]],\n) -> dict[str, str]\n

Convert a list of Gmail-style headers into a normalized dict.

Parameters:

Name Type Description Default raw_headers list[dict[str, str]]

List of header dictionaries, each containing name and value keys.

required

Returns:

Type Description dict[str, str]

dict[str, str]: Dictionary mapping lowercase header names to stripped values.

Notes

Guarantees:

- Provider payloads (such as Gmail) typically represent headers as a\n  list of name/value mappings.\n- This function normalizes them into a case-insensitive dictionary\n  keyed by lowercase header names.\n
Example

Typical usage:

Input:\n    [\n        {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n        {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n    ]\n\nOutput:\n    {\n        \"from\": \"John Doe <john@example.com>\",\n        \"subject\": \"Re: Interview Update\",\n    }\n
"},{"location":"mail_intake/parsers/body/","title":"Body","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body","title":"mail_intake.parsers.body","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body--summary","title":"Summary","text":"

Message body extraction utilities for Mail Intake.

This module contains helper functions for extracting a best-effort plain-text body from provider-native message payloads.

The logic is intentionally tolerant of malformed or partial data and prefers human-readable text over fidelity to original formatting.

"},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body-classes","title":"Classes","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body.extract_body","title":"extract_body","text":"
extract_body(payload: dict[str, Any]) -> str\n

Extract the best-effort message body from a Gmail payload.

Priority:

  1. text/plain
  2. text/html (stripped to text)
  3. Single-part body
  4. Empty string (if nothing usable found)

Parameters:

Name Type Description Default payload dict[str, Any]

Provider-native message payload dictionary.

required

Returns:

Name Type Description str str

Extracted plain-text message body.

"},{"location":"mail_intake/parsers/headers/","title":"Headers","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers","title":"mail_intake.parsers.headers","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers--summary","title":"Summary","text":"

Message header parsing utilities for Mail Intake.

This module provides helper functions for normalizing and extracting useful information from provider-native message headers.

The functions here are intentionally simple and tolerant of malformed or incomplete header data.

"},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers.extract_sender","title":"extract_sender","text":"
extract_sender(\n    headers: dict[str, str],\n) -> tuple[str, str | None]\n

Extract sender email and optional display name from headers.

Parameters:

Name Type Description Default headers dict[str, str]

Normalized header dictionary as returned by parse_headers().

required

Returns:

Type Description tuple[str, str | None]

tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.

Notes

Responsibilities:

- This function parses the `From` header and attempts to extract\n  sender email address and optional human-readable display name.\n
Example

Typical values:

  • \"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")
  • \"john@example.com\" -> (\"john@example.com\", None)
"},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers.parse_headers","title":"parse_headers","text":"
parse_headers(\n    raw_headers: list[dict[str, str]],\n) -> dict[str, str]\n

Convert a list of Gmail-style headers into a normalized dict.

Parameters:

Name Type Description Default raw_headers list[dict[str, str]]

List of header dictionaries, each containing name and value keys.

required

Returns:

Type Description dict[str, str]

dict[str, str]: Dictionary mapping lowercase header names to stripped values.

Notes

Guarantees:

- Provider payloads (such as Gmail) typically represent headers as a\n  list of name/value mappings.\n- This function normalizes them into a case-insensitive dictionary\n  keyed by lowercase header names.\n
Example

Typical usage:

Input:\n    [\n        {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n        {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n    ]\n\nOutput:\n    {\n        \"from\": \"John Doe <john@example.com>\",\n        \"subject\": \"Re: Interview Update\",\n    }\n
"},{"location":"mail_intake/parsers/subject/","title":"Subject","text":""},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject","title":"mail_intake.parsers.subject","text":""},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject--summary","title":"Summary","text":"

Subject line normalization utilities for Mail Intake.

This module provides helper functions for normalizing email subject lines to enable reliable thread-level comparison and grouping.

Normalization is intentionally conservative to avoid altering semantic meaning while removing common reply and forward prefixes.

"},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject.normalize_subject","title":"normalize_subject","text":"
normalize_subject(subject: str) -> str\n

Normalize an email subject for thread-level comparison.

Parameters:

Name Type Description Default subject str

Raw subject line from a message header.

required

Returns:

Name Type Description str str

Normalized subject string suitable for thread grouping.

Notes

Responsibilities:

- Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n- Repeats prefix stripping to handle stacked prefixes.\n- Collapses excessive whitespace.\n- Preserves original casing (no lowercasing).\n

Guarantees:

- This function is intentionally conservative and avoids aggressive\n  transformations that could alter the semantic meaning of the subject.\n
"},{"location":"models/","title":"Models","text":""},{"location":"models/#mail_intake.models","title":"mail_intake.models","text":""},{"location":"models/#mail_intake.models--summary","title":"Summary","text":"

Domain models for Mail Intake.

This package defines the canonical, provider-agnostic data models used throughout the Mail Intake ingestion pipeline.

Models in this package:

  • Represent fully parsed and normalized mail data.
  • Are safe to persist, serialize, and index.
  • Contain no provider-specific payloads or API semantics.
  • Serve as stable inputs for downstream processing and analysis.

These models form the core internal data contract of the library.

"},{"location":"models/#mail_intake.models--public-api","title":"Public API","text":"
  • MailIntakeMessage
  • MailIntakeThread
"},{"location":"models/#mail_intake.models-classes","title":"Classes","text":""},{"location":"models/#mail_intake.models.MailIntakeMessage","title":"MailIntakeMessage dataclass","text":"
MailIntakeMessage(\n    message_id: str,\n    thread_id: str,\n    timestamp: datetime,\n    from_email: str,\n    from_name: str | None,\n    subject: str,\n    body_text: str,\n    snippet: str,\n    raw_headers: dict[str, str],\n)\n

Canonical internal representation of a single email message.

Notes

Guarantees:

- This model represents a fully parsed and normalized email message.\n- It is intentionally provider-agnostic and suitable for\n  persistence, indexing, and downstream processing.\n

Constraints:

- No provider-specific identifiers, payloads, or API semantics\n  should appear in this model.\n
"},{"location":"models/#mail_intake.models.MailIntakeMessage-attributes","title":"Attributes","text":""},{"location":"models/#mail_intake.models.MailIntakeMessage.body_text","title":"body_text instance-attribute","text":"
body_text: str\n

Extracted plain-text body content of the message.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.from_email","title":"from_email instance-attribute","text":"
from_email: str\n

Sender email address.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.from_name","title":"from_name instance-attribute","text":"
from_name: str | None\n

Optional human-readable sender name.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.message_id","title":"message_id instance-attribute","text":"
message_id: str\n

Provider-specific message identifier.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.raw_headers","title":"raw_headers instance-attribute","text":"
raw_headers: dict[str, str]\n

Normalized mapping of message headers (header name \u2192 value).

"},{"location":"models/#mail_intake.models.MailIntakeMessage.snippet","title":"snippet instance-attribute","text":"
snippet: str\n

Short provider-supplied preview snippet of the message.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.subject","title":"subject instance-attribute","text":"
subject: str\n

Raw subject line of the message.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier to which this message belongs.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.timestamp","title":"timestamp instance-attribute","text":"
timestamp: datetime\n

Message timestamp as a timezone-naive UTC datetime.

"},{"location":"models/#mail_intake.models.MailIntakeThread","title":"MailIntakeThread dataclass","text":"
MailIntakeThread(\n    thread_id: str,\n    normalized_subject: str,\n    participants: set[str] = ...,\n    messages: list[MailIntakeMessage] = ...,\n    last_activity_at: datetime | None = ...,\n)\n

Canonical internal representation of an email thread.

Notes

Guarantees:

- A thread groups multiple related messages under a single subject\n  and participant set.\n- It is designed to support reasoning over conversational context\n  such as job applications, interviews, follow-ups, and ongoing discussions.\n- This model is provider-agnostic and safe to persist.\n
"},{"location":"models/#mail_intake.models.MailIntakeThread-attributes","title":"Attributes","text":""},{"location":"models/#mail_intake.models.MailIntakeThread.last_activity_at","title":"last_activity_at class-attribute instance-attribute","text":"
last_activity_at: datetime | None = None\n

Timestamp of the most recent message in the thread.

"},{"location":"models/#mail_intake.models.MailIntakeThread.messages","title":"messages class-attribute instance-attribute","text":"
messages: list[MailIntakeMessage] = field(\n    default_factory=list\n)\n

Ordered list of messages belonging to this thread.

"},{"location":"models/#mail_intake.models.MailIntakeThread.normalized_subject","title":"normalized_subject instance-attribute","text":"
normalized_subject: str\n

Normalized subject line used to group related messages.

"},{"location":"models/#mail_intake.models.MailIntakeThread.participants","title":"participants class-attribute instance-attribute","text":"
participants: set[str] = field(default_factory=set)\n

Set of unique participant email addresses observed in the thread.

"},{"location":"models/#mail_intake.models.MailIntakeThread.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier.

"},{"location":"models/#mail_intake.models.MailIntakeThread-functions","title":"Functions","text":""},{"location":"models/#mail_intake.models.MailIntakeThread.add_message","title":"add_message","text":"
add_message(message: MailIntakeMessage) -> None\n

Add a message to the thread and update derived fields.

Parameters:

Name Type Description Default message MailIntakeMessage

Parsed mail message to add to the thread.

required Notes

Responsibilities:

- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\n
"},{"location":"models/message/","title":"Message","text":""},{"location":"models/message/#mail_intake.models.message","title":"mail_intake.models.message","text":""},{"location":"models/message/#mail_intake.models.message--summary","title":"Summary","text":"

Message domain models for Mail Intake.

This module defines the canonical, provider-agnostic representation of an individual email message as used internally by the Mail Intake ingestion pipeline.

Models in this module are safe to persist and must not contain any provider-specific fields or semantics.

"},{"location":"models/message/#mail_intake.models.message-classes","title":"Classes","text":""},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage","title":"MailIntakeMessage dataclass","text":"
MailIntakeMessage(\n    message_id: str,\n    thread_id: str,\n    timestamp: datetime,\n    from_email: str,\n    from_name: str | None,\n    subject: str,\n    body_text: str,\n    snippet: str,\n    raw_headers: dict[str, str],\n)\n

Canonical internal representation of a single email message.

Notes

Guarantees:

- This model represents a fully parsed and normalized email message.\n- It is intentionally provider-agnostic and suitable for\n  persistence, indexing, and downstream processing.\n

Constraints:

- No provider-specific identifiers, payloads, or API semantics\n  should appear in this model.\n
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage-attributes","title":"Attributes","text":""},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.body_text","title":"body_text instance-attribute","text":"
body_text: str\n

Extracted plain-text body content of the message.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.from_email","title":"from_email instance-attribute","text":"
from_email: str\n

Sender email address.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.from_name","title":"from_name instance-attribute","text":"
from_name: str | None\n

Optional human-readable sender name.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.message_id","title":"message_id instance-attribute","text":"
message_id: str\n

Provider-specific message identifier.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.raw_headers","title":"raw_headers instance-attribute","text":"
raw_headers: dict[str, str]\n

Normalized mapping of message headers (header name \u2192 value).

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.snippet","title":"snippet instance-attribute","text":"
snippet: str\n

Short provider-supplied preview snippet of the message.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.subject","title":"subject instance-attribute","text":"
subject: str\n

Raw subject line of the message.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier to which this message belongs.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.timestamp","title":"timestamp instance-attribute","text":"
timestamp: datetime\n

Message timestamp as a timezone-naive UTC datetime.

"},{"location":"models/thread/","title":"Thread","text":""},{"location":"models/thread/#mail_intake.models.thread","title":"mail_intake.models.thread","text":""},{"location":"models/thread/#mail_intake.models.thread--summary","title":"Summary","text":"

Thread domain models for Mail Intake.

This module defines the canonical, provider-agnostic representation of an email thread as used internally by the Mail Intake ingestion pipeline.

Threads group related messages and serve as the primary unit of reasoning for higher-level correspondence workflows.

"},{"location":"models/thread/#mail_intake.models.thread-classes","title":"Classes","text":""},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread","title":"MailIntakeThread dataclass","text":"
MailIntakeThread(\n    thread_id: str,\n    normalized_subject: str,\n    participants: set[str] = ...,\n    messages: list[MailIntakeMessage] = ...,\n    last_activity_at: datetime | None = ...,\n)\n

Canonical internal representation of an email thread.

Notes

Guarantees:

- A thread groups multiple related messages under a single subject\n  and participant set.\n- It is designed to support reasoning over conversational context\n  such as job applications, interviews, follow-ups, and ongoing discussions.\n- This model is provider-agnostic and safe to persist.\n
"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread-attributes","title":"Attributes","text":""},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.last_activity_at","title":"last_activity_at class-attribute instance-attribute","text":"
last_activity_at: datetime | None = None\n

Timestamp of the most recent message in the thread.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.messages","title":"messages class-attribute instance-attribute","text":"
messages: list[MailIntakeMessage] = field(\n    default_factory=list\n)\n

Ordered list of messages belonging to this thread.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.normalized_subject","title":"normalized_subject instance-attribute","text":"
normalized_subject: str\n

Normalized subject line used to group related messages.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.participants","title":"participants class-attribute instance-attribute","text":"
participants: set[str] = field(default_factory=set)\n

Set of unique participant email addresses observed in the thread.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread-functions","title":"Functions","text":""},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.add_message","title":"add_message","text":"
add_message(message: MailIntakeMessage) -> None\n

Add a message to the thread and update derived fields.

Parameters:

Name Type Description Default message MailIntakeMessage

Parsed mail message to add to the thread.

required Notes

Responsibilities:

- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\n
"},{"location":"parsers/","title":"Parsers","text":""},{"location":"parsers/#mail_intake.parsers","title":"mail_intake.parsers","text":""},{"location":"parsers/#mail_intake.parsers--summary","title":"Summary","text":"

Message parsing utilities for Mail Intake.

This package contains provider-aware but adapter-agnostic parsing helpers used to extract and normalize structured information from raw mail payloads.

Parsers in this package are responsible for:

  • Interpreting provider-native message structures.
  • Extracting meaningful fields such as headers, body text, and subjects.
  • Normalizing data into consistent internal representations.

This package does not:

  • Perform network or IO operations.
  • Contain provider API logic.
  • Construct domain models directly.

Parsing functions are designed to be composable and are orchestrated by the ingestion layer.

"},{"location":"parsers/#mail_intake.parsers--public-api","title":"Public API","text":"
  • extract_body
  • parse_headers
  • extract_sender
  • normalize_subject
"},{"location":"parsers/#mail_intake.parsers-functions","title":"Functions","text":""},{"location":"parsers/#mail_intake.parsers.extract_body","title":"extract_body","text":"
extract_body(payload: dict[str, Any]) -> str\n

Extract the best-effort message body from a Gmail payload.

Priority:

  1. text/plain
  2. text/html (stripped to text)
  3. Single-part body
  4. Empty string (if nothing usable found)

Parameters:

Name Type Description Default payload dict[str, Any]

Provider-native message payload dictionary.

required

Returns:

Name Type Description str str

Extracted plain-text message body.

"},{"location":"parsers/#mail_intake.parsers.extract_sender","title":"extract_sender","text":"
extract_sender(\n    headers: dict[str, str],\n) -> tuple[str, str | None]\n

Extract sender email and optional display name from headers.

Parameters:

Name Type Description Default headers dict[str, str]

Normalized header dictionary as returned by parse_headers().

required

Returns:

Type Description tuple[str, str | None]

tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.

Notes

Responsibilities:

- This function parses the `From` header and attempts to extract\n  sender email address and optional human-readable display name.\n
Example

Typical values:

  • \"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")
  • \"john@example.com\" -> (\"john@example.com\", None)
"},{"location":"parsers/#mail_intake.parsers.normalize_subject","title":"normalize_subject","text":"
normalize_subject(subject: str) -> str\n

Normalize an email subject for thread-level comparison.

Parameters:

Name Type Description Default subject str

Raw subject line from a message header.

required

Returns:

Name Type Description str str

Normalized subject string suitable for thread grouping.

Notes

Responsibilities:

- Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n- Repeats prefix stripping to handle stacked prefixes.\n- Collapses excessive whitespace.\n- Preserves original casing (no lowercasing).\n

Guarantees:

- This function is intentionally conservative and avoids aggressive\n  transformations that could alter the semantic meaning of the subject.\n
"},{"location":"parsers/#mail_intake.parsers.parse_headers","title":"parse_headers","text":"
parse_headers(\n    raw_headers: list[dict[str, str]],\n) -> dict[str, str]\n

Convert a list of Gmail-style headers into a normalized dict.

Parameters:

Name Type Description Default raw_headers list[dict[str, str]]

List of header dictionaries, each containing name and value keys.

required

Returns:

Type Description dict[str, str]

dict[str, str]: Dictionary mapping lowercase header names to stripped values.

Notes

Guarantees:

- Provider payloads (such as Gmail) typically represent headers as a\n  list of name/value mappings.\n- This function normalizes them into a case-insensitive dictionary\n  keyed by lowercase header names.\n
Example

Typical usage:

Input:\n    [\n        {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n        {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n    ]\n\nOutput:\n    {\n        \"from\": \"John Doe <john@example.com>\",\n        \"subject\": \"Re: Interview Update\",\n    }\n
"},{"location":"parsers/body/","title":"Body","text":""},{"location":"parsers/body/#mail_intake.parsers.body","title":"mail_intake.parsers.body","text":""},{"location":"parsers/body/#mail_intake.parsers.body--summary","title":"Summary","text":"

Message body extraction utilities for Mail Intake.

This module contains helper functions for extracting a best-effort plain-text body from provider-native message payloads.

The logic is intentionally tolerant of malformed or partial data and prefers human-readable text over fidelity to original formatting.

"},{"location":"parsers/body/#mail_intake.parsers.body-classes","title":"Classes","text":""},{"location":"parsers/body/#mail_intake.parsers.body-functions","title":"Functions","text":""},{"location":"parsers/body/#mail_intake.parsers.body.extract_body","title":"extract_body","text":"
extract_body(payload: dict[str, Any]) -> str\n

Extract the best-effort message body from a Gmail payload.

Priority:

  1. text/plain
  2. text/html (stripped to text)
  3. Single-part body
  4. Empty string (if nothing usable found)

Parameters:

Name Type Description Default payload dict[str, Any]

Provider-native message payload dictionary.

required

Returns:

Name Type Description str str

Extracted plain-text message body.

"},{"location":"parsers/headers/","title":"Headers","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers","title":"mail_intake.parsers.headers","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers--summary","title":"Summary","text":"

Message header parsing utilities for Mail Intake.

This module provides helper functions for normalizing and extracting useful information from provider-native message headers.

The functions here are intentionally simple and tolerant of malformed or incomplete header data.

"},{"location":"parsers/headers/#mail_intake.parsers.headers-functions","title":"Functions","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers.extract_sender","title":"extract_sender","text":"
extract_sender(\n    headers: dict[str, str],\n) -> tuple[str, str | None]\n

Extract sender email and optional display name from headers.

Parameters:

Name Type Description Default headers dict[str, str]

Normalized header dictionary as returned by parse_headers().

required

Returns:

Type Description tuple[str, str | None]

tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.

Notes

Responsibilities:

- This function parses the `From` header and attempts to extract\n  sender email address and optional human-readable display name.\n
Example

Typical values:

  • \"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")
  • \"john@example.com\" -> (\"john@example.com\", None)
"},{"location":"parsers/headers/#mail_intake.parsers.headers.parse_headers","title":"parse_headers","text":"
parse_headers(\n    raw_headers: list[dict[str, str]],\n) -> dict[str, str]\n

Convert a list of Gmail-style headers into a normalized dict.

Parameters:

Name Type Description Default raw_headers list[dict[str, str]]

List of header dictionaries, each containing name and value keys.

required

Returns:

Type Description dict[str, str]

dict[str, str]: Dictionary mapping lowercase header names to stripped values.

Notes

Guarantees:

- Provider payloads (such as Gmail) typically represent headers as a\n  list of name/value mappings.\n- This function normalizes them into a case-insensitive dictionary\n  keyed by lowercase header names.\n
Example

Typical usage:

Input:\n    [\n        {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n        {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n    ]\n\nOutput:\n    {\n        \"from\": \"John Doe <john@example.com>\",\n        \"subject\": \"Re: Interview Update\",\n    }\n
"},{"location":"parsers/subject/","title":"Subject","text":""},{"location":"parsers/subject/#mail_intake.parsers.subject","title":"mail_intake.parsers.subject","text":""},{"location":"parsers/subject/#mail_intake.parsers.subject--summary","title":"Summary","text":"

Subject line normalization utilities for Mail Intake.

This module provides helper functions for normalizing email subject lines to enable reliable thread-level comparison and grouping.

Normalization is intentionally conservative to avoid altering semantic meaning while removing common reply and forward prefixes.

"},{"location":"parsers/subject/#mail_intake.parsers.subject-functions","title":"Functions","text":""},{"location":"parsers/subject/#mail_intake.parsers.subject.normalize_subject","title":"normalize_subject","text":"
normalize_subject(subject: str) -> str\n

Normalize an email subject for thread-level comparison.

Parameters:

Name Type Description Default subject str

Raw subject line from a message header.

required

Returns:

Name Type Description str str

Normalized subject string suitable for thread grouping.

Notes

Responsibilities:

- Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n- Repeats prefix stripping to handle stacked prefixes.\n- Collapses excessive whitespace.\n- Preserves original casing (no lowercasing).\n

Guarantees:

- This function is intentionally conservative and avoids aggressive\n  transformations that could alter the semantic meaning of the subject.\n
"}]} \ No newline at end of file diff --git a/mcp/dagpipe/modules/dagpipe.engine.json b/mcp/dagpipe/modules/dagpipe.engine.json index 629fa2b..f24ead1 100644 --- a/mcp/dagpipe/modules/dagpipe.engine.json +++ b/mcp/dagpipe/modules/dagpipe.engine.json @@ -86,28 +86,28 @@ "kind": "function", "path": "dagpipe.engine.Graph.children", "signature": "", - "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Outgoing neighbors." + "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Outgoing neighbors." }, "parents": { "name": "parents", "kind": "function", "path": "dagpipe.engine.Graph.parents", "signature": "", - "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Incoming neighbors." + "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Incoming neighbors." }, "roots": { "name": "roots", "kind": "function", "path": "dagpipe.engine.Graph.roots", "signature": "", - "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n Tuple[Node, ...]:\n Entry point nodes." + "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n tuple[Node, ...]:\n Entry point nodes." }, "nodes": { "name": "nodes", "kind": "function", "path": "dagpipe.engine.Graph.nodes", "signature": "", - "docstring": "Return all nodes in the graph.\n\nReturns:\n Tuple[Node, ...]:\n All registered nodes." + "docstring": "Return all nodes in the graph.\n\nReturns:\n tuple[Node, ...]:\n All registered nodes." } } }, @@ -188,14 +188,14 @@ "kind": "function", "path": "dagpipe.engine.Node.fork", "signature": "", - "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Mapping[str, Any], optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Mapping[str, Any], optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." + "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Any, optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Any, optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." }, "resolve": { "name": "resolve", "kind": "function", "path": "dagpipe.engine.Node.resolve", "signature": "", - "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nYields:\n State:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." + "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n Iterable[State]:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." }, "is_async": { "name": "is_async", @@ -267,14 +267,14 @@ "kind": "function", "path": "dagpipe.engine.State.fork", "signature": "", - "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any], optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any], optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." + "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any] | None, optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str | None, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any] | None, optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." }, "lineage": { "name": "lineage", "kind": "function", "path": "dagpipe.engine.State.lineage", "signature": "", - "docstring": "Return lineage from root to this State.\n\nReturns:\n Tuple[State, ...]:\n Ordered execution lineage (root first)." + "docstring": "Return lineage from root to this State.\n\nReturns:\n tuple[State, ...]:\n Ordered execution lineage (root first)." }, "get": { "name": "get", @@ -382,8 +382,8 @@ "name": "StepResult", "kind": "class", "path": "dagpipe.engine.StepResult", - "signature": "", - "docstring": "A single checkpointed step within an async/resumable engine run.\n\nAttributes:\n index (int): Ordinal index of the step.\n node_id (str): Identifier of the node associated with this step.\n states (Tuple[State, ...]): States produced by running this step.\n completed (bool): Whether this step succeeded (vs. paused/interrupted).", + "signature": "", + "docstring": "A single checkpointed step within an async/resumable engine run.\n\nAttributes:\n index (int): Ordinal index of the step.\n node_id (str): Identifier of the node associated with this step.\n states (tuple[State, ...]): States produced by running this step.\n completed (bool): Whether this step succeeded (vs. paused/interrupted).", "members": { "index": { "name": "index", @@ -419,7 +419,7 @@ "name": "Engine", "kind": "class", "path": "dagpipe.engine.Engine", - "signature": "", + "signature": "", "docstring": "Execution engine responsible for running pipeline logic.\n\nNotes:\n **Responsibilities:**\n\n - Accepts either a linear sequence of `Node` objects or a `Graph`\n defining execution topology.\n - Propagates immutable `State` objects through `Node` objects and\n collects terminal states.\n - Supports synchronous (`run`) and asynchronous (`run_async`)\n execution, dispatching per-node.\n - Supports step-wise / resumable execution and progress hooks.\n\n **Guarantees:**\n\n - Never mutates `State`, `Node`, or `Graph` instances.\n - `State` objects are never modified in place; each branch produces\n independent instances.\n - Execution order is deterministic and follows graph or pipeline topology.\n - Thread-safe for concurrent execution.", "members": { "MODE_LINEAR": { @@ -440,29 +440,29 @@ "name": "run", "kind": "function", "path": "dagpipe.engine.Engine.run", - "signature": "", + "signature": "", "docstring": "Execute the pipeline starting from a root `State`.\n\nArgs:\n root (State):\n Initial execution state.\n\nReturns:\n list[State]:\n Terminal execution states produced by the pipeline.\n\nRaises:\n TypeError:\n If `root` is not a `State` instance.\n\n RuntimeError:\n If the engine execution mode is invalid.\n\nNotes:\n **Responsibilities:**\n\n - Selects execution mode, propagates state through nodes, creates\n new instances for branches, and collects terminal states." }, "run_async": { "name": "run_async", "kind": "function", "path": "dagpipe.engine.Engine.run_async", - "signature": "", + "signature": "", "docstring": "Execute the pipeline starting from `root`, dispatching sync vs async nodes.\n\nArgs:\n root (State):\n Initial execution state.\n\nReturns:\n list[State]:\n Terminal execution states produced by the pipeline.\n\nNotes:\n Each node is executed with `Node.run` when synchronous and\n `AsyncNode.run_async` when asynchronous. Linear and graph topologies\n are both supported." }, "run_steps": { "name": "run_steps", "kind": "function", "path": "dagpipe.engine.Engine.run_steps", - "signature": "", - "docstring": "Execute the pipeline step-by-step, yielding one `StepResult` per step.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int, optional):\n Skip steps at index < `resume_from` (for resume-after-partial).\n Steps are 0-indexed.\n\n on_step (StepHook, optional):\n Callback `(step, status, message)` invoked per step; falls back\n to the engine-level hook when unset.\n\nYields:\n StepResult:\n One per executed node/step, carrying the produced states.\n\nNotes:\n This is a synchronous, generator-based checkpoint interface compatible\n with the imperative resume-by-step behaviour of the legacy\n orchestrator. Use `run_steps_async` for async nodes." + "signature": "", + "docstring": "Execute the pipeline step-by-step, yielding one `StepResult` per step.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int | None, optional):\n Skip steps at index < `resume_from` (for resume-after-partial).\n Steps are 0-indexed.\n\n on_step (StepHook | None, optional):\n Callback `(step, status, message)` invoked per step; falls back\n to the engine-level hook when unset.\n\nYields:\n StepResult:\n One per executed node/step, carrying the produced states.\n\nNotes:\n This is a synchronous, generator-based checkpoint interface compatible\n with the imperative resume-by-step behaviour of the legacy\n orchestrator. Use `run_steps_async` for async nodes." }, "run_steps_async": { "name": "run_steps_async", "kind": "function", "path": "dagpipe.engine.Engine.run_steps_async", - "signature": "", - "docstring": "Async variant of `run_steps` supporting `AsyncNode` execution.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int, optional):\n Skip steps at index < `resume_from`.\n\n on_step (AsyncStepHook, optional):\n Async callback `(step, status, message)` invoked per step.\n\nYields:\n StepResult:\n One per executed node/step." + "signature": "", + "docstring": "Async variant of `run_steps` supporting `AsyncNode` execution.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int | None, optional):\n Skip steps at index < `resume_from`.\n\n on_step (AsyncStepHook | None, optional):\n Async callback `(step, status, message)` invoked per step.\n\nYields:\n StepResult:\n One per executed node/step." }, "nodes": { "name": "nodes", diff --git a/mcp/dagpipe/modules/dagpipe.graph.json b/mcp/dagpipe/modules/dagpipe.graph.json index 232ee8a..a467bfb 100644 --- a/mcp/dagpipe/modules/dagpipe.graph.json +++ b/mcp/dagpipe/modules/dagpipe.graph.json @@ -58,14 +58,14 @@ "kind": "function", "path": "dagpipe.graph.Node.fork", "signature": "", - "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Mapping[str, Any], optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Mapping[str, Any], optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." + "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Any, optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Any, optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." }, "resolve": { "name": "resolve", "kind": "function", "path": "dagpipe.graph.Node.resolve", "signature": "", - "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nYields:\n State:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." + "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n Iterable[State]:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." }, "is_async": { "name": "is_async", @@ -102,28 +102,28 @@ "kind": "function", "path": "dagpipe.graph.Graph.children", "signature": "", - "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Outgoing neighbors." + "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Outgoing neighbors." }, "parents": { "name": "parents", "kind": "function", "path": "dagpipe.graph.Graph.parents", "signature": "", - "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Incoming neighbors." + "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Incoming neighbors." }, "roots": { "name": "roots", "kind": "function", "path": "dagpipe.graph.Graph.roots", "signature": "", - "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n Tuple[Node, ...]:\n Entry point nodes." + "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n tuple[Node, ...]:\n Entry point nodes." }, "nodes": { "name": "nodes", "kind": "function", "path": "dagpipe.graph.Graph.nodes", "signature": "", - "docstring": "Return all nodes in the graph.\n\nReturns:\n Tuple[Node, ...]:\n All registered nodes." + "docstring": "Return all nodes in the graph.\n\nReturns:\n tuple[Node, ...]:\n All registered nodes." } } } diff --git a/mcp/dagpipe/modules/dagpipe.json b/mcp/dagpipe/modules/dagpipe.json index b270f60..b476b07 100644 --- a/mcp/dagpipe/modules/dagpipe.json +++ b/mcp/dagpipe/modules/dagpipe.json @@ -65,14 +65,14 @@ "kind": "function", "path": "dagpipe.State.fork", "signature": "", - "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any], optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any], optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." + "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any] | None, optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str | None, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any] | None, optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." }, "lineage": { "name": "lineage", "kind": "function", "path": "dagpipe.State.lineage", "signature": "", - "docstring": "Return lineage from root to this State.\n\nReturns:\n Tuple[State, ...]:\n Ordered execution lineage (root first)." + "docstring": "Return lineage from root to this State.\n\nReturns:\n tuple[State, ...]:\n Ordered execution lineage (root first)." }, "get": { "name": "get", @@ -102,7 +102,7 @@ "kind": "function", "path": "dagpipe.Payload.iter_paths", "signature": "", - "docstring": "Recursively yield dot-paths for all leaf nodes.\n\nArgs:\n data (Mapping[str, Any]):\n The mapping to iterate over.\n prefix (str, optional):\n Current path prefix.\n\nReturns:\n Iterable[str]:\n Generator yielding dot-paths." + "docstring": "Recursively yield dot-paths for all leaf nodes.\n\nArgs:\n data (Mapping[str, Any]):\n The mapping to iterate over.\n prefix (str, optional):\n Current path prefix.\n\nYields:\n str:\n Dot-path for each leaf node." }, "get": { "name": "get", @@ -225,14 +225,14 @@ "kind": "function", "path": "dagpipe.Node.fork", "signature": "", - "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Mapping[str, Any], optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Mapping[str, Any], optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." + "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Any, optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Any, optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." }, "resolve": { "name": "resolve", "kind": "function", "path": "dagpipe.Node.resolve", "signature": "", - "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nYields:\n State:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." + "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n Iterable[State]:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." }, "is_async": { "name": "is_async", @@ -299,28 +299,28 @@ "kind": "function", "path": "dagpipe.Graph.children", "signature": "", - "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Outgoing neighbors." + "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Outgoing neighbors." }, "parents": { "name": "parents", "kind": "function", "path": "dagpipe.Graph.parents", "signature": "", - "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Incoming neighbors." + "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Incoming neighbors." }, "roots": { "name": "roots", "kind": "function", "path": "dagpipe.Graph.roots", "signature": "", - "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n Tuple[Node, ...]:\n Entry point nodes." + "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n tuple[Node, ...]:\n Entry point nodes." }, "nodes": { "name": "nodes", "kind": "function", "path": "dagpipe.Graph.nodes", "signature": "", - "docstring": "Return all nodes in the graph.\n\nReturns:\n Tuple[Node, ...]:\n All registered nodes." + "docstring": "Return all nodes in the graph.\n\nReturns:\n tuple[Node, ...]:\n All registered nodes." } } }, @@ -364,14 +364,14 @@ "kind": "function", "path": "dagpipe.Engine.run_steps", "signature": "", - "docstring": "Execute the pipeline step-by-step, yielding one `StepResult` per step.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int, optional):\n Skip steps at index < `resume_from` (for resume-after-partial).\n Steps are 0-indexed.\n\n on_step (StepHook, optional):\n Callback `(step, status, message)` invoked per step; falls back\n to the engine-level hook when unset.\n\nYields:\n StepResult:\n One per executed node/step, carrying the produced states.\n\nNotes:\n This is a synchronous, generator-based checkpoint interface compatible\n with the imperative resume-by-step behaviour of the legacy\n orchestrator. Use `run_steps_async` for async nodes." + "docstring": "Execute the pipeline step-by-step, yielding one `StepResult` per step.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int | None, optional):\n Skip steps at index < `resume_from` (for resume-after-partial).\n Steps are 0-indexed.\n\n on_step (StepHook | None, optional):\n Callback `(step, status, message)` invoked per step; falls back\n to the engine-level hook when unset.\n\nYields:\n StepResult:\n One per executed node/step, carrying the produced states.\n\nNotes:\n This is a synchronous, generator-based checkpoint interface compatible\n with the imperative resume-by-step behaviour of the legacy\n orchestrator. Use `run_steps_async` for async nodes." }, "run_steps_async": { "name": "run_steps_async", "kind": "function", "path": "dagpipe.Engine.run_steps_async", "signature": "", - "docstring": "Async variant of `run_steps` supporting `AsyncNode` execution.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int, optional):\n Skip steps at index < `resume_from`.\n\n on_step (AsyncStepHook, optional):\n Async callback `(step, status, message)` invoked per step.\n\nYields:\n StepResult:\n One per executed node/step." + "docstring": "Async variant of `run_steps` supporting `AsyncNode` execution.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int | None, optional):\n Skip steps at index < `resume_from`.\n\n on_step (AsyncStepHook | None, optional):\n Async callback `(step, status, message)` invoked per step.\n\nYields:\n StepResult:\n One per executed node/step." }, "nodes": { "name": "nodes", @@ -459,7 +459,7 @@ "kind": "class", "path": "dagpipe.StepResult", "signature": "", - "docstring": "A single checkpointed step within an async/resumable engine run.\n\nAttributes:\n index (int): Ordinal index of the step.\n node_id (str): Identifier of the node associated with this step.\n states (Tuple[State, ...]): States produced by running this step.\n completed (bool): Whether this step succeeded (vs. paused/interrupted).", + "docstring": "A single checkpointed step within an async/resumable engine run.\n\nAttributes:\n index (int): Ordinal index of the step.\n node_id (str): Identifier of the node associated with this step.\n states (tuple[State, ...]): States produced by running this step.\n completed (bool): Whether this step succeeded (vs. paused/interrupted).", "members": { "index": { "name": "index", @@ -524,7 +524,7 @@ "kind": "function", "path": "dagpipe.Pipeline.run", "signature": "", - "docstring": "Execute the pipeline.\n\nArgs:\n payload_override (Mapping[str, Any], optional):\n Payload values overriding initial payload.\n\nReturns:\n list[State]:\n Terminal execution states.\n\nNotes:\n **Responsibilities:**\n\n - Merges override payload with initial payload.\n - Creates root `State` and executes engine." + "docstring": "Execute the pipeline.\n\nArgs:\n payload_override (Mapping[str, Any] | None, optional):\n Payload values overriding initial payload.\n\nReturns:\n list[State]:\n Terminal execution states.\n\nNotes:\n **Responsibilities:**\n\n - Merges override payload with initial payload.\n - Creates root `State` and executes engine." } } }, @@ -624,28 +624,28 @@ "kind": "function", "path": "dagpipe.engine.Graph.children", "signature": "", - "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Outgoing neighbors." + "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Outgoing neighbors." }, "parents": { "name": "parents", "kind": "function", "path": "dagpipe.engine.Graph.parents", "signature": "", - "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Incoming neighbors." + "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Incoming neighbors." }, "roots": { "name": "roots", "kind": "function", "path": "dagpipe.engine.Graph.roots", "signature": "", - "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n Tuple[Node, ...]:\n Entry point nodes." + "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n tuple[Node, ...]:\n Entry point nodes." }, "nodes": { "name": "nodes", "kind": "function", "path": "dagpipe.engine.Graph.nodes", "signature": "", - "docstring": "Return all nodes in the graph.\n\nReturns:\n Tuple[Node, ...]:\n All registered nodes." + "docstring": "Return all nodes in the graph.\n\nReturns:\n tuple[Node, ...]:\n All registered nodes." } } }, @@ -726,14 +726,14 @@ "kind": "function", "path": "dagpipe.engine.Node.fork", "signature": "", - "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Mapping[str, Any], optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Mapping[str, Any], optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." + "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Any, optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Any, optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." }, "resolve": { "name": "resolve", "kind": "function", "path": "dagpipe.engine.Node.resolve", "signature": "", - "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nYields:\n State:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." + "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n Iterable[State]:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." }, "is_async": { "name": "is_async", @@ -805,14 +805,14 @@ "kind": "function", "path": "dagpipe.engine.State.fork", "signature": "", - "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any], optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any], optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." + "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any] | None, optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str | None, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any] | None, optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." }, "lineage": { "name": "lineage", "kind": "function", "path": "dagpipe.engine.State.lineage", "signature": "", - "docstring": "Return lineage from root to this State.\n\nReturns:\n Tuple[State, ...]:\n Ordered execution lineage (root first)." + "docstring": "Return lineage from root to this State.\n\nReturns:\n tuple[State, ...]:\n Ordered execution lineage (root first)." }, "get": { "name": "get", @@ -920,8 +920,8 @@ "name": "StepResult", "kind": "class", "path": "dagpipe.engine.StepResult", - "signature": "", - "docstring": "A single checkpointed step within an async/resumable engine run.\n\nAttributes:\n index (int): Ordinal index of the step.\n node_id (str): Identifier of the node associated with this step.\n states (Tuple[State, ...]): States produced by running this step.\n completed (bool): Whether this step succeeded (vs. paused/interrupted).", + "signature": "", + "docstring": "A single checkpointed step within an async/resumable engine run.\n\nAttributes:\n index (int): Ordinal index of the step.\n node_id (str): Identifier of the node associated with this step.\n states (tuple[State, ...]): States produced by running this step.\n completed (bool): Whether this step succeeded (vs. paused/interrupted).", "members": { "index": { "name": "index", @@ -957,7 +957,7 @@ "name": "Engine", "kind": "class", "path": "dagpipe.engine.Engine", - "signature": "", + "signature": "", "docstring": "Execution engine responsible for running pipeline logic.\n\nNotes:\n **Responsibilities:**\n\n - Accepts either a linear sequence of `Node` objects or a `Graph`\n defining execution topology.\n - Propagates immutable `State` objects through `Node` objects and\n collects terminal states.\n - Supports synchronous (`run`) and asynchronous (`run_async`)\n execution, dispatching per-node.\n - Supports step-wise / resumable execution and progress hooks.\n\n **Guarantees:**\n\n - Never mutates `State`, `Node`, or `Graph` instances.\n - `State` objects are never modified in place; each branch produces\n independent instances.\n - Execution order is deterministic and follows graph or pipeline topology.\n - Thread-safe for concurrent execution.", "members": { "MODE_LINEAR": { @@ -978,29 +978,29 @@ "name": "run", "kind": "function", "path": "dagpipe.engine.Engine.run", - "signature": "", + "signature": "", "docstring": "Execute the pipeline starting from a root `State`.\n\nArgs:\n root (State):\n Initial execution state.\n\nReturns:\n list[State]:\n Terminal execution states produced by the pipeline.\n\nRaises:\n TypeError:\n If `root` is not a `State` instance.\n\n RuntimeError:\n If the engine execution mode is invalid.\n\nNotes:\n **Responsibilities:**\n\n - Selects execution mode, propagates state through nodes, creates\n new instances for branches, and collects terminal states." }, "run_async": { "name": "run_async", "kind": "function", "path": "dagpipe.engine.Engine.run_async", - "signature": "", + "signature": "", "docstring": "Execute the pipeline starting from `root`, dispatching sync vs async nodes.\n\nArgs:\n root (State):\n Initial execution state.\n\nReturns:\n list[State]:\n Terminal execution states produced by the pipeline.\n\nNotes:\n Each node is executed with `Node.run` when synchronous and\n `AsyncNode.run_async` when asynchronous. Linear and graph topologies\n are both supported." }, "run_steps": { "name": "run_steps", "kind": "function", "path": "dagpipe.engine.Engine.run_steps", - "signature": "", - "docstring": "Execute the pipeline step-by-step, yielding one `StepResult` per step.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int, optional):\n Skip steps at index < `resume_from` (for resume-after-partial).\n Steps are 0-indexed.\n\n on_step (StepHook, optional):\n Callback `(step, status, message)` invoked per step; falls back\n to the engine-level hook when unset.\n\nYields:\n StepResult:\n One per executed node/step, carrying the produced states.\n\nNotes:\n This is a synchronous, generator-based checkpoint interface compatible\n with the imperative resume-by-step behaviour of the legacy\n orchestrator. Use `run_steps_async` for async nodes." + "signature": "", + "docstring": "Execute the pipeline step-by-step, yielding one `StepResult` per step.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int | None, optional):\n Skip steps at index < `resume_from` (for resume-after-partial).\n Steps are 0-indexed.\n\n on_step (StepHook | None, optional):\n Callback `(step, status, message)` invoked per step; falls back\n to the engine-level hook when unset.\n\nYields:\n StepResult:\n One per executed node/step, carrying the produced states.\n\nNotes:\n This is a synchronous, generator-based checkpoint interface compatible\n with the imperative resume-by-step behaviour of the legacy\n orchestrator. Use `run_steps_async` for async nodes." }, "run_steps_async": { "name": "run_steps_async", "kind": "function", "path": "dagpipe.engine.Engine.run_steps_async", - "signature": "", - "docstring": "Async variant of `run_steps` supporting `AsyncNode` execution.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int, optional):\n Skip steps at index < `resume_from`.\n\n on_step (AsyncStepHook, optional):\n Async callback `(step, status, message)` invoked per step.\n\nYields:\n StepResult:\n One per executed node/step." + "signature": "", + "docstring": "Async variant of `run_steps` supporting `AsyncNode` execution.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int | None, optional):\n Skip steps at index < `resume_from`.\n\n on_step (AsyncStepHook | None, optional):\n Async callback `(step, status, message)` invoked per step.\n\nYields:\n StepResult:\n One per executed node/step." }, "nodes": { "name": "nodes", @@ -1081,14 +1081,14 @@ "kind": "function", "path": "dagpipe.graph.Node.fork", "signature": "", - "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Mapping[str, Any], optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Mapping[str, Any], optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." + "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Any, optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Any, optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." }, "resolve": { "name": "resolve", "kind": "function", "path": "dagpipe.graph.Node.resolve", "signature": "", - "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nYields:\n State:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." + "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n Iterable[State]:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." }, "is_async": { "name": "is_async", @@ -1125,28 +1125,28 @@ "kind": "function", "path": "dagpipe.graph.Graph.children", "signature": "", - "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Outgoing neighbors." + "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Outgoing neighbors." }, "parents": { "name": "parents", "kind": "function", "path": "dagpipe.graph.Graph.parents", "signature": "", - "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Incoming neighbors." + "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Incoming neighbors." }, "roots": { "name": "roots", "kind": "function", "path": "dagpipe.graph.Graph.roots", "signature": "", - "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n Tuple[Node, ...]:\n Entry point nodes." + "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n tuple[Node, ...]:\n Entry point nodes." }, "nodes": { "name": "nodes", "kind": "function", "path": "dagpipe.graph.Graph.nodes", "signature": "", - "docstring": "Return all nodes in the graph.\n\nReturns:\n Tuple[Node, ...]:\n All registered nodes." + "docstring": "Return all nodes in the graph.\n\nReturns:\n tuple[Node, ...]:\n All registered nodes." } } } @@ -1276,14 +1276,14 @@ "kind": "function", "path": "dagpipe.node.State.fork", "signature": "", - "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any], optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any], optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." + "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any] | None, optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str | None, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any] | None, optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." }, "lineage": { "name": "lineage", "kind": "function", "path": "dagpipe.node.State.lineage", "signature": "", - "docstring": "Return lineage from root to this State.\n\nReturns:\n Tuple[State, ...]:\n Ordered execution lineage (root first)." + "docstring": "Return lineage from root to this State.\n\nReturns:\n tuple[State, ...]:\n Ordered execution lineage (root first)." }, "get": { "name": "get", @@ -1348,14 +1348,14 @@ "kind": "function", "path": "dagpipe.node.Node.fork", "signature": "", - "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Mapping[str, Any], optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Mapping[str, Any], optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." + "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Any, optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Any, optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." }, "resolve": { "name": "resolve", "kind": "function", "path": "dagpipe.node.Node.resolve", "signature": "", - "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nYields:\n State:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." + "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n Iterable[State]:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." }, "is_async": { "name": "is_async", @@ -1494,7 +1494,7 @@ "kind": "function", "path": "dagpipe.state.Payload.iter_paths", "signature": "", - "docstring": "Recursively yield dot-paths for all leaf nodes.\n\nArgs:\n data (Mapping[str, Any]):\n The mapping to iterate over.\n prefix (str, optional):\n Current path prefix.\n\nReturns:\n Iterable[str]:\n Generator yielding dot-paths." + "docstring": "Recursively yield dot-paths for all leaf nodes.\n\nArgs:\n data (Mapping[str, Any]):\n The mapping to iterate over.\n prefix (str, optional):\n Current path prefix.\n\nYields:\n str:\n Dot-path for each leaf node." }, "get": { "name": "get", @@ -1638,14 +1638,14 @@ "kind": "function", "path": "dagpipe.state.State.fork", "signature": "", - "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any], optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any], optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." + "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any] | None, optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str | None, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any] | None, optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." }, "lineage": { "name": "lineage", "kind": "function", "path": "dagpipe.state.State.lineage", "signature": "", - "docstring": "Return lineage from root to this State.\n\nReturns:\n Tuple[State, ...]:\n Ordered execution lineage (root first)." + "docstring": "Return lineage from root to this State.\n\nReturns:\n tuple[State, ...]:\n Ordered execution lineage (root first)." }, "get": { "name": "get", @@ -1768,14 +1768,14 @@ "kind": "function", "path": "dagpipe.yaml_loader.Engine.run_steps", "signature": "", - "docstring": "Execute the pipeline step-by-step, yielding one `StepResult` per step.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int, optional):\n Skip steps at index < `resume_from` (for resume-after-partial).\n Steps are 0-indexed.\n\n on_step (StepHook, optional):\n Callback `(step, status, message)` invoked per step; falls back\n to the engine-level hook when unset.\n\nYields:\n StepResult:\n One per executed node/step, carrying the produced states.\n\nNotes:\n This is a synchronous, generator-based checkpoint interface compatible\n with the imperative resume-by-step behaviour of the legacy\n orchestrator. Use `run_steps_async` for async nodes." + "docstring": "Execute the pipeline step-by-step, yielding one `StepResult` per step.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int | None, optional):\n Skip steps at index < `resume_from` (for resume-after-partial).\n Steps are 0-indexed.\n\n on_step (StepHook | None, optional):\n Callback `(step, status, message)` invoked per step; falls back\n to the engine-level hook when unset.\n\nYields:\n StepResult:\n One per executed node/step, carrying the produced states.\n\nNotes:\n This is a synchronous, generator-based checkpoint interface compatible\n with the imperative resume-by-step behaviour of the legacy\n orchestrator. Use `run_steps_async` for async nodes." }, "run_steps_async": { "name": "run_steps_async", "kind": "function", "path": "dagpipe.yaml_loader.Engine.run_steps_async", "signature": "", - "docstring": "Async variant of `run_steps` supporting `AsyncNode` execution.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int, optional):\n Skip steps at index < `resume_from`.\n\n on_step (AsyncStepHook, optional):\n Async callback `(step, status, message)` invoked per step.\n\nYields:\n StepResult:\n One per executed node/step." + "docstring": "Async variant of `run_steps` supporting `AsyncNode` execution.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int | None, optional):\n Skip steps at index < `resume_from`.\n\n on_step (AsyncStepHook | None, optional):\n Async callback `(step, status, message)` invoked per step.\n\nYields:\n StepResult:\n One per executed node/step." }, "nodes": { "name": "nodes", @@ -1812,28 +1812,28 @@ "kind": "function", "path": "dagpipe.yaml_loader.Graph.children", "signature": "", - "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Outgoing neighbors." + "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Outgoing neighbors." }, "parents": { "name": "parents", "kind": "function", "path": "dagpipe.yaml_loader.Graph.parents", "signature": "", - "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Incoming neighbors." + "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Incoming neighbors." }, "roots": { "name": "roots", "kind": "function", "path": "dagpipe.yaml_loader.Graph.roots", "signature": "", - "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n Tuple[Node, ...]:\n Entry point nodes." + "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n tuple[Node, ...]:\n Entry point nodes." }, "nodes": { "name": "nodes", "kind": "function", "path": "dagpipe.yaml_loader.Graph.nodes", "signature": "", - "docstring": "Return all nodes in the graph.\n\nReturns:\n Tuple[Node, ...]:\n All registered nodes." + "docstring": "Return all nodes in the graph.\n\nReturns:\n tuple[Node, ...]:\n All registered nodes." } } }, @@ -1884,14 +1884,14 @@ "kind": "function", "path": "dagpipe.yaml_loader.Node.fork", "signature": "", - "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Mapping[str, Any], optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Mapping[str, Any], optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." + "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Any, optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Any, optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." }, "resolve": { "name": "resolve", "kind": "function", "path": "dagpipe.yaml_loader.Node.resolve", "signature": "", - "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nYields:\n State:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." + "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n Iterable[State]:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." }, "is_async": { "name": "is_async", @@ -1914,7 +1914,7 @@ "kind": "function", "path": "dagpipe.yaml_loader.Payload.iter_paths", "signature": "", - "docstring": "Recursively yield dot-paths for all leaf nodes.\n\nArgs:\n data (Mapping[str, Any]):\n The mapping to iterate over.\n prefix (str, optional):\n Current path prefix.\n\nReturns:\n Iterable[str]:\n Generator yielding dot-paths." + "docstring": "Recursively yield dot-paths for all leaf nodes.\n\nArgs:\n data (Mapping[str, Any]):\n The mapping to iterate over.\n prefix (str, optional):\n Current path prefix.\n\nYields:\n str:\n Dot-path for each leaf node." }, "get": { "name": "get", @@ -2044,14 +2044,14 @@ "kind": "function", "path": "dagpipe.yaml_loader.State.fork", "signature": "", - "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any], optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any], optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." + "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any] | None, optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str | None, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any] | None, optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." }, "lineage": { "name": "lineage", "kind": "function", "path": "dagpipe.yaml_loader.State.lineage", "signature": "", - "docstring": "Return lineage from root to this State.\n\nReturns:\n Tuple[State, ...]:\n Ordered execution lineage (root first)." + "docstring": "Return lineage from root to this State.\n\nReturns:\n tuple[State, ...]:\n Ordered execution lineage (root first)." }, "get": { "name": "get", @@ -2102,7 +2102,7 @@ "kind": "function", "path": "dagpipe.yaml_loader.Pipeline.run", "signature": "", - "docstring": "Execute the pipeline.\n\nArgs:\n payload_override (Mapping[str, Any], optional):\n Payload values overriding initial payload.\n\nReturns:\n list[State]:\n Terminal execution states.\n\nNotes:\n **Responsibilities:**\n\n - Merges override payload with initial payload.\n - Creates root `State` and executes engine." + "docstring": "Execute the pipeline.\n\nArgs:\n payload_override (Mapping[str, Any] | None, optional):\n Payload values overriding initial payload.\n\nReturns:\n list[State]:\n Terminal execution states.\n\nNotes:\n **Responsibilities:**\n\n - Merges override payload with initial payload.\n - Creates root `State` and executes engine." } } }, diff --git a/mcp/dagpipe/modules/dagpipe.node.json b/mcp/dagpipe/modules/dagpipe.node.json index f60361b..dea1dbc 100644 --- a/mcp/dagpipe/modules/dagpipe.node.json +++ b/mcp/dagpipe/modules/dagpipe.node.json @@ -121,14 +121,14 @@ "kind": "function", "path": "dagpipe.node.State.fork", "signature": "", - "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any], optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any], optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." + "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any] | None, optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str | None, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any] | None, optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." }, "lineage": { "name": "lineage", "kind": "function", "path": "dagpipe.node.State.lineage", "signature": "", - "docstring": "Return lineage from root to this State.\n\nReturns:\n Tuple[State, ...]:\n Ordered execution lineage (root first)." + "docstring": "Return lineage from root to this State.\n\nReturns:\n tuple[State, ...]:\n Ordered execution lineage (root first)." }, "get": { "name": "get", @@ -193,14 +193,14 @@ "kind": "function", "path": "dagpipe.node.Node.fork", "signature": "", - "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Mapping[str, Any], optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Mapping[str, Any], optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." + "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Any, optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Any, optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." }, "resolve": { "name": "resolve", "kind": "function", "path": "dagpipe.node.Node.resolve", "signature": "", - "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nYields:\n State:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." + "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n Iterable[State]:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." }, "is_async": { "name": "is_async", diff --git a/mcp/dagpipe/modules/dagpipe.state.json b/mcp/dagpipe/modules/dagpipe.state.json index 84357fd..eae3b66 100644 --- a/mcp/dagpipe/modules/dagpipe.state.json +++ b/mcp/dagpipe/modules/dagpipe.state.json @@ -86,7 +86,7 @@ "kind": "function", "path": "dagpipe.state.Payload.iter_paths", "signature": "", - "docstring": "Recursively yield dot-paths for all leaf nodes.\n\nArgs:\n data (Mapping[str, Any]):\n The mapping to iterate over.\n prefix (str, optional):\n Current path prefix.\n\nReturns:\n Iterable[str]:\n Generator yielding dot-paths." + "docstring": "Recursively yield dot-paths for all leaf nodes.\n\nArgs:\n data (Mapping[str, Any]):\n The mapping to iterate over.\n prefix (str, optional):\n Current path prefix.\n\nYields:\n str:\n Dot-path for each leaf node." }, "get": { "name": "get", @@ -230,14 +230,14 @@ "kind": "function", "path": "dagpipe.state.State.fork", "signature": "", - "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any], optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any], optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." + "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any] | None, optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str | None, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any] | None, optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." }, "lineage": { "name": "lineage", "kind": "function", "path": "dagpipe.state.State.lineage", "signature": "", - "docstring": "Return lineage from root to this State.\n\nReturns:\n Tuple[State, ...]:\n Ordered execution lineage (root first)." + "docstring": "Return lineage from root to this State.\n\nReturns:\n tuple[State, ...]:\n Ordered execution lineage (root first)." }, "get": { "name": "get", diff --git a/mcp/dagpipe/modules/dagpipe.yaml_loader.json b/mcp/dagpipe/modules/dagpipe.yaml_loader.json index 79d020f..0017462 100644 --- a/mcp/dagpipe/modules/dagpipe.yaml_loader.json +++ b/mcp/dagpipe/modules/dagpipe.yaml_loader.json @@ -93,14 +93,14 @@ "kind": "function", "path": "dagpipe.yaml_loader.Engine.run_steps", "signature": "", - "docstring": "Execute the pipeline step-by-step, yielding one `StepResult` per step.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int, optional):\n Skip steps at index < `resume_from` (for resume-after-partial).\n Steps are 0-indexed.\n\n on_step (StepHook, optional):\n Callback `(step, status, message)` invoked per step; falls back\n to the engine-level hook when unset.\n\nYields:\n StepResult:\n One per executed node/step, carrying the produced states.\n\nNotes:\n This is a synchronous, generator-based checkpoint interface compatible\n with the imperative resume-by-step behaviour of the legacy\n orchestrator. Use `run_steps_async` for async nodes." + "docstring": "Execute the pipeline step-by-step, yielding one `StepResult` per step.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int | None, optional):\n Skip steps at index < `resume_from` (for resume-after-partial).\n Steps are 0-indexed.\n\n on_step (StepHook | None, optional):\n Callback `(step, status, message)` invoked per step; falls back\n to the engine-level hook when unset.\n\nYields:\n StepResult:\n One per executed node/step, carrying the produced states.\n\nNotes:\n This is a synchronous, generator-based checkpoint interface compatible\n with the imperative resume-by-step behaviour of the legacy\n orchestrator. Use `run_steps_async` for async nodes." }, "run_steps_async": { "name": "run_steps_async", "kind": "function", "path": "dagpipe.yaml_loader.Engine.run_steps_async", "signature": "", - "docstring": "Async variant of `run_steps` supporting `AsyncNode` execution.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int, optional):\n Skip steps at index < `resume_from`.\n\n on_step (AsyncStepHook, optional):\n Async callback `(step, status, message)` invoked per step.\n\nYields:\n StepResult:\n One per executed node/step." + "docstring": "Async variant of `run_steps` supporting `AsyncNode` execution.\n\nArgs:\n root (State):\n Initial execution state.\n\n resume_from (int | None, optional):\n Skip steps at index < `resume_from`.\n\n on_step (AsyncStepHook | None, optional):\n Async callback `(step, status, message)` invoked per step.\n\nYields:\n StepResult:\n One per executed node/step." }, "nodes": { "name": "nodes", @@ -137,28 +137,28 @@ "kind": "function", "path": "dagpipe.yaml_loader.Graph.children", "signature": "", - "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Outgoing neighbors." + "docstring": "Return child nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Outgoing neighbors." }, "parents": { "name": "parents", "kind": "function", "path": "dagpipe.yaml_loader.Graph.parents", "signature": "", - "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n Tuple[Node, ...]:\n Incoming neighbors." + "docstring": "Return parent nodes of a node.\n\nArgs:\n node (Node):\n Node to query.\n\nReturns:\n tuple[Node, ...]:\n Incoming neighbors." }, "roots": { "name": "roots", "kind": "function", "path": "dagpipe.yaml_loader.Graph.roots", "signature": "", - "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n Tuple[Node, ...]:\n Entry point nodes." + "docstring": "Return root nodes (nodes with no incoming edges).\n\nReturns:\n tuple[Node, ...]:\n Entry point nodes." }, "nodes": { "name": "nodes", "kind": "function", "path": "dagpipe.yaml_loader.Graph.nodes", "signature": "", - "docstring": "Return all nodes in the graph.\n\nReturns:\n Tuple[Node, ...]:\n All registered nodes." + "docstring": "Return all nodes in the graph.\n\nReturns:\n tuple[Node, ...]:\n All registered nodes." } } }, @@ -209,14 +209,14 @@ "kind": "function", "path": "dagpipe.yaml_loader.Node.fork", "signature": "", - "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Mapping[str, Any], optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Mapping[str, Any], optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." + "docstring": "Create a child `State` attributed to this node.\n\nArgs:\n state (State):\n Parent execution state.\n\n payload_update (Any, optional):\n Dot-path payload updates.\n\n confidence_delta (float, optional):\n Confidence adjustment.\n\n metadata_update (Any, optional):\n Metadata updates.\n\nReturns:\n State:\n New child execution state.\n\nNotes:\n **Responsibilities:**\n\n - Convenience wrapper around `State.fork()` that automatically\n records this node's ID in state history." }, "resolve": { "name": "resolve", "kind": "function", "path": "dagpipe.yaml_loader.Node.resolve", "signature": "", - "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nYields:\n State:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." + "docstring": "Execute node logic.\n\nArgs:\n state (State):\n Input execution state.\n\nReturns:\n Iterable[State]:\n Derived execution state(s).\n\nNotes:\n **Responsibilities:**\n\n - Subclasses implement specific resolution behavior.\n - Must not mutate input state.\n - Should use `fork()` to create child states.\n - May yield zero states to terminate a branch." }, "is_async": { "name": "is_async", @@ -239,7 +239,7 @@ "kind": "function", "path": "dagpipe.yaml_loader.Payload.iter_paths", "signature": "", - "docstring": "Recursively yield dot-paths for all leaf nodes.\n\nArgs:\n data (Mapping[str, Any]):\n The mapping to iterate over.\n prefix (str, optional):\n Current path prefix.\n\nReturns:\n Iterable[str]:\n Generator yielding dot-paths." + "docstring": "Recursively yield dot-paths for all leaf nodes.\n\nArgs:\n data (Mapping[str, Any]):\n The mapping to iterate over.\n prefix (str, optional):\n Current path prefix.\n\nYields:\n str:\n Dot-path for each leaf node." }, "get": { "name": "get", @@ -369,14 +369,14 @@ "kind": "function", "path": "dagpipe.yaml_loader.State.fork", "signature": "", - "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any], optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any], optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." + "docstring": "Create a new child `State` derived from this state.\n\nArgs:\n payload_update (Mapping[str, Any] | None, optional):\n Dot-path updates applied to the payload.\n\n confidence_delta (float, optional):\n Adjustment applied to current confidence.\n\n node_id (str | None, optional):\n Identifier of the node creating this state.\n\n metadata_update (Mapping[str, Any] | None, optional):\n Updates merged into state metadata.\n\nReturns:\n State:\n A new immutable `State` instance.\n\nNotes:\n **Guarantees:**\n\n - This is the only supported mechanism for modifying execution data.\n - Validates payload updates, preserves lineage, increments depth,\n and appends to history." }, "lineage": { "name": "lineage", "kind": "function", "path": "dagpipe.yaml_loader.State.lineage", "signature": "", - "docstring": "Return lineage from root to this State.\n\nReturns:\n Tuple[State, ...]:\n Ordered execution lineage (root first)." + "docstring": "Return lineage from root to this State.\n\nReturns:\n tuple[State, ...]:\n Ordered execution lineage (root first)." }, "get": { "name": "get", @@ -427,7 +427,7 @@ "kind": "function", "path": "dagpipe.yaml_loader.Pipeline.run", "signature": "", - "docstring": "Execute the pipeline.\n\nArgs:\n payload_override (Mapping[str, Any], optional):\n Payload values overriding initial payload.\n\nReturns:\n list[State]:\n Terminal execution states.\n\nNotes:\n **Responsibilities:**\n\n - Merges override payload with initial payload.\n - Creates root `State` and executes engine." + "docstring": "Execute the pipeline.\n\nArgs:\n payload_override (Mapping[str, Any] | None, optional):\n Payload values overriding initial payload.\n\nReturns:\n list[State]:\n Terminal execution states.\n\nNotes:\n **Responsibilities:**\n\n - Merges override payload with initial payload.\n - Creates root `State` and executes engine." } } }, diff --git a/mcp/dagpipe/nav.json b/mcp/dagpipe/nav.json index 688069f..5f200f5 100644 --- a/mcp/dagpipe/nav.json +++ b/mcp/dagpipe/nav.json @@ -1,26 +1,26 @@ [ { "module": "dagpipe", - "resource": "doc://modules/dagpipe" + "resource": "docs://modules/dagpipe" }, { "module": "dagpipe.engine", - "resource": "doc://modules/dagpipe.engine" + "resource": "docs://modules/dagpipe.engine" }, { "module": "dagpipe.graph", - "resource": "doc://modules/dagpipe.graph" + "resource": "docs://modules/dagpipe.graph" }, { "module": "dagpipe.node", - "resource": "doc://modules/dagpipe.node" + "resource": "docs://modules/dagpipe.node" }, { "module": "dagpipe.state", - "resource": "doc://modules/dagpipe.state" + "resource": "docs://modules/dagpipe.state" }, { "module": "dagpipe.yaml_loader", - "resource": "doc://modules/dagpipe.yaml_loader" + "resource": "docs://modules/dagpipe.yaml_loader" } ] \ No newline at end of file diff --git a/mcp/mail-intake/modules/mail_intake.credentials.json b/mcp/mail-intake/modules/mail_intake.credentials.json index 3d5a3b7..f18c4df 100644 --- a/mcp/mail-intake/modules/mail_intake.credentials.json +++ b/mcp/mail-intake/modules/mail_intake.credentials.json @@ -247,6 +247,13 @@ "signature": "", "docstring": null }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.credentials.redis.Any", + "signature": "", + "docstring": null + }, "TypeVar": { "name": "TypeVar", "kind": "alias", @@ -295,7 +302,7 @@ "name": "RedisCredentialStore", "kind": "class", "path": "mail_intake.credentials.redis.RedisCredentialStore", - "signature": "", + "signature": "", "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.", "members": { "redis": { @@ -337,31 +344,24 @@ "name": "load", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.load", - "signature": "", + "signature": "", "docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.save", - "signature": "", + "signature": "", "docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.clear", - "signature": "", + "signature": "", "docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent" } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "mail_intake.credentials.redis.Any", - "signature": "", - "docstring": null } } }, diff --git a/mcp/mail-intake/modules/mail_intake.credentials.redis.json b/mcp/mail-intake/modules/mail_intake.credentials.redis.json index 8c39459..4325f23 100644 --- a/mcp/mail-intake/modules/mail_intake.credentials.redis.json +++ b/mcp/mail-intake/modules/mail_intake.credentials.redis.json @@ -11,6 +11,13 @@ "signature": "", "docstring": null }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.credentials.redis.Any", + "signature": "", + "docstring": null + }, "TypeVar": { "name": "TypeVar", "kind": "alias", @@ -59,7 +66,7 @@ "name": "RedisCredentialStore", "kind": "class", "path": "mail_intake.credentials.redis.RedisCredentialStore", - "signature": "", + "signature": "", "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.", "members": { "redis": { @@ -101,31 +108,24 @@ "name": "load", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.load", - "signature": "", + "signature": "", "docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.save", - "signature": "", + "signature": "", "docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.clear", - "signature": "", + "signature": "", "docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent" } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "mail_intake.credentials.redis.Any", - "signature": "", - "docstring": null } } } diff --git a/mcp/mail-intake/modules/mail_intake.json b/mcp/mail-intake/modules/mail_intake.json index ba08875..041d5b5 100644 --- a/mcp/mail-intake/modules/mail_intake.json +++ b/mcp/mail-intake/modules/mail_intake.json @@ -891,6 +891,13 @@ "signature": "", "docstring": null }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "mail_intake.credentials.redis.Any", + "signature": "", + "docstring": null + }, "TypeVar": { "name": "TypeVar", "kind": "alias", @@ -939,7 +946,7 @@ "name": "RedisCredentialStore", "kind": "class", "path": "mail_intake.credentials.redis.RedisCredentialStore", - "signature": "", + "signature": "", "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.", "members": { "redis": { @@ -981,31 +988,24 @@ "name": "load", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.load", - "signature": "", + "signature": "", "docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable." }, "save": { "name": "save", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.save", - "signature": "", + "signature": "", "docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration" }, "clear": { "name": "clear", "kind": "function", "path": "mail_intake.credentials.redis.RedisCredentialStore.clear", - "signature": "", + "signature": "", "docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent" } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "mail_intake.credentials.redis.Any", - "signature": "", - "docstring": null } } }, diff --git a/mcp/openapi-first/modules/openapi_first.app.json b/mcp/openapi-first/modules/openapi_first.app.json index c8df6bc..fdb22ca 100644 --- a/mcp/openapi-first/modules/openapi_first.app.json +++ b/mcp/openapi-first/modules/openapi_first.app.json @@ -18,6 +18,13 @@ "signature": "", "docstring": null }, + "ModuleType": { + "name": "ModuleType", + "kind": "alias", + "path": "openapi_first.app.ModuleType", + "signature": "", + "docstring": null + }, "Any": { "name": "Any", "kind": "alias", @@ -37,7 +44,7 @@ "kind": "function", "path": "openapi_first.app.bind_routes", "signature": "", - "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n app (Any):\n The FastAPI application instance to which routes will be added.\n spec (dict):\n Parsed OpenAPI 3.x specification dictionary.\n routes_module (Any):\n Python module containing handler functions. Each handler's name MUST\n exactly match an OpenAPI `operationId`.\n security_deps (dict[str, list[Any]] | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n handler function exists in the routes module.\n\nNotes:\n **Responsibilities:**\n\n - Iterates through the OpenAPI specification paths and methods.\n - Resolves each ``operationId`` to a handler function, and registers\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." + "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n app (FastAPI):\n The FastAPI application instance to which routes will be added.\n spec (dict[str, Any]):\n Parsed OpenAPI 3.x specification dictionary.\n routes_module (ModuleType):\n Python module containing handler functions. Each handler's name MUST\n exactly match an OpenAPI `operationId`.\n security_deps (dict[str, list[Any]] | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n handler function exists in the routes module.\n\nNotes:\n **Responsibilities:**\n\n - Iterates through the OpenAPI specification paths and methods.\n - Resolves each ``operationId`` to a handler function, and registers\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." }, "load_openapi": { "name": "load_openapi", @@ -64,7 +71,7 @@ "name": "OpenAPIFirstApp", "kind": "class", "path": "openapi_first.app.OpenAPIFirstApp", - "signature": "", + "signature": "", "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n **Responsibilities:**\n\n - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n registration with OpenAPI-driven binding.\n - All routes are derived from the provided OpenAPI specification,\n and each ``operationId`` is mapped to a Python function in the\n supplied routes module.\n - Auth dependencies are auto-injected from the spec's\n ``securitySchemes`` and per-operation ``security`` fields.\n\n **Guarantees:**\n\n - No route can exist without an OpenAPI declaration.\n - No OpenAPI operation can exist without a handler.\n - Swagger UI and ``/openapi.json`` always reflect the provided spec.\n - Handler functions remain framework-agnostic and testable.\n - Auth enforcement is driven entirely by the spec — no manual\n middleware or decorators required.\n\nExample:\n ```python\n from openapi_first import OpenAPIFirstApp\n import app.routes as routes\n\n app = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n )\n ```", "members": { "openapi": { diff --git a/mcp/openapi-first/modules/openapi_first.binder.json b/mcp/openapi-first/modules/openapi_first.binder.json index 7fe0ba1..605a031 100644 --- a/mcp/openapi-first/modules/openapi_first.binder.json +++ b/mcp/openapi-first/modules/openapi_first.binder.json @@ -4,6 +4,13 @@ "path": "openapi_first.binder", "docstring": "# Summary\n\nOpenAPI-driven route binding for FastAPI.\n\nThis module is responsible for translating an OpenAPI 3.x specification\ninto concrete FastAPI routes. It enforces a strict one-to-one mapping\nbetween OpenAPI operations and Python handler functions using `operationId`.\n\nNotes:\n **Core Responsibility:**\n\n - Read path + method definitions from an OpenAPI specification.\n - Resolve each `operationId` to a Python callable.\n - Register routes with FastAPI using `APIRoute`.\n - Fail fast when contract violations are detected.\n\n **Design Constraints:**\n\n - All routes MUST be declared in the OpenAPI specification.\n - All OpenAPI operations MUST define an `operationId`.\n - Every `operationId` MUST resolve to a handler function.\n - Handlers are plain Python callables (no decorators required).\n - No implicit route creation or inference is allowed.\n\n **Constraints:**\n\n - This module intentionally does NOT:\n - Perform request or response validation.\n - Generate Pydantic models.\n - Modify FastAPI dependency injection.\n - Interpret OpenAPI semantics beyond routing metadata.", "objects": { + "ModuleType": { + "name": "ModuleType", + "kind": "alias", + "path": "openapi_first.binder.ModuleType", + "signature": "", + "docstring": null + }, "Any": { "name": "Any", "kind": "alias", @@ -11,6 +18,13 @@ "signature": "", "docstring": null }, + "FastAPI": { + "name": "FastAPI", + "kind": "alias", + "path": "openapi_first.binder.FastAPI", + "signature": "", + "docstring": null + }, "APIRoute": { "name": "APIRoute", "kind": "alias", @@ -29,15 +43,8 @@ "name": "bind_routes", "kind": "function", "path": "openapi_first.binder.bind_routes", - "signature": "", - "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n app (Any):\n The FastAPI application instance to which routes will be added.\n spec (dict):\n Parsed OpenAPI 3.x specification dictionary.\n routes_module (Any):\n Python module containing handler functions. Each handler's name MUST\n exactly match an OpenAPI `operationId`.\n security_deps (dict[str, list[Any]] | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n handler function exists in the routes module.\n\nNotes:\n **Responsibilities:**\n\n - Iterates through the OpenAPI specification paths and methods.\n - Resolves each ``operationId`` to a handler function, and registers\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." - }, - "FastAPI": { - "name": "FastAPI", - "kind": "alias", - "path": "openapi_first.binder.FastAPI", - "signature": "", - "docstring": null + "signature": "", + "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n app (FastAPI):\n The FastAPI application instance to which routes will be added.\n spec (dict[str, Any]):\n Parsed OpenAPI 3.x specification dictionary.\n routes_module (ModuleType):\n Python module containing handler functions. Each handler's name MUST\n exactly match an OpenAPI `operationId`.\n security_deps (dict[str, list[Any]] | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n handler function exists in the routes module.\n\nNotes:\n **Responsibilities:**\n\n - Iterates through the OpenAPI specification paths and methods.\n - Resolves each ``operationId`` to a handler function, and registers\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." } } } diff --git a/mcp/openapi-first/modules/openapi_first.json b/mcp/openapi-first/modules/openapi_first.json index a9d481e..0ebae41 100644 --- a/mcp/openapi-first/modules/openapi_first.json +++ b/mcp/openapi-first/modules/openapi_first.json @@ -25,6 +25,13 @@ "signature": "", "docstring": null }, + "ModuleType": { + "name": "ModuleType", + "kind": "alias", + "path": "openapi_first.app.ModuleType", + "signature": "", + "docstring": null + }, "Any": { "name": "Any", "kind": "alias", @@ -44,7 +51,7 @@ "kind": "function", "path": "openapi_first.app.bind_routes", "signature": "", - "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n app (Any):\n The FastAPI application instance to which routes will be added.\n spec (dict):\n Parsed OpenAPI 3.x specification dictionary.\n routes_module (Any):\n Python module containing handler functions. Each handler's name MUST\n exactly match an OpenAPI `operationId`.\n security_deps (dict[str, list[Any]] | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n handler function exists in the routes module.\n\nNotes:\n **Responsibilities:**\n\n - Iterates through the OpenAPI specification paths and methods.\n - Resolves each ``operationId`` to a handler function, and registers\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." + "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n app (FastAPI):\n The FastAPI application instance to which routes will be added.\n spec (dict[str, Any]):\n Parsed OpenAPI 3.x specification dictionary.\n routes_module (ModuleType):\n Python module containing handler functions. Each handler's name MUST\n exactly match an OpenAPI `operationId`.\n security_deps (dict[str, list[Any]] | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n handler function exists in the routes module.\n\nNotes:\n **Responsibilities:**\n\n - Iterates through the OpenAPI specification paths and methods.\n - Resolves each ``operationId`` to a handler function, and registers\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." }, "load_openapi": { "name": "load_openapi", @@ -71,7 +78,7 @@ "name": "OpenAPIFirstApp", "kind": "class", "path": "openapi_first.app.OpenAPIFirstApp", - "signature": "", + "signature": "", "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n **Responsibilities:**\n\n - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n registration with OpenAPI-driven binding.\n - All routes are derived from the provided OpenAPI specification,\n and each ``operationId`` is mapped to a Python function in the\n supplied routes module.\n - Auth dependencies are auto-injected from the spec's\n ``securitySchemes`` and per-operation ``security`` fields.\n\n **Guarantees:**\n\n - No route can exist without an OpenAPI declaration.\n - No OpenAPI operation can exist without a handler.\n - Swagger UI and ``/openapi.json`` always reflect the provided spec.\n - Handler functions remain framework-agnostic and testable.\n - Auth enforcement is driven entirely by the spec — no manual\n middleware or decorators required.\n\nExample:\n ```python\n from openapi_first import OpenAPIFirstApp\n import app.routes as routes\n\n app = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n )\n ```", "members": { "openapi": { @@ -92,6 +99,13 @@ "signature": null, "docstring": "# Summary\n\nOpenAPI-driven route binding for FastAPI.\n\nThis module is responsible for translating an OpenAPI 3.x specification\ninto concrete FastAPI routes. It enforces a strict one-to-one mapping\nbetween OpenAPI operations and Python handler functions using `operationId`.\n\nNotes:\n **Core Responsibility:**\n\n - Read path + method definitions from an OpenAPI specification.\n - Resolve each `operationId` to a Python callable.\n - Register routes with FastAPI using `APIRoute`.\n - Fail fast when contract violations are detected.\n\n **Design Constraints:**\n\n - All routes MUST be declared in the OpenAPI specification.\n - All OpenAPI operations MUST define an `operationId`.\n - Every `operationId` MUST resolve to a handler function.\n - Handlers are plain Python callables (no decorators required).\n - No implicit route creation or inference is allowed.\n\n **Constraints:**\n\n - This module intentionally does NOT:\n - Perform request or response validation.\n - Generate Pydantic models.\n - Modify FastAPI dependency injection.\n - Interpret OpenAPI semantics beyond routing metadata.", "members": { + "ModuleType": { + "name": "ModuleType", + "kind": "alias", + "path": "openapi_first.binder.ModuleType", + "signature": "", + "docstring": null + }, "Any": { "name": "Any", "kind": "alias", @@ -99,6 +113,13 @@ "signature": "", "docstring": null }, + "FastAPI": { + "name": "FastAPI", + "kind": "alias", + "path": "openapi_first.binder.FastAPI", + "signature": "", + "docstring": null + }, "APIRoute": { "name": "APIRoute", "kind": "alias", @@ -117,15 +138,8 @@ "name": "bind_routes", "kind": "function", "path": "openapi_first.binder.bind_routes", - "signature": "", - "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n app (Any):\n The FastAPI application instance to which routes will be added.\n spec (dict):\n Parsed OpenAPI 3.x specification dictionary.\n routes_module (Any):\n Python module containing handler functions. Each handler's name MUST\n exactly match an OpenAPI `operationId`.\n security_deps (dict[str, list[Any]] | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n handler function exists in the routes module.\n\nNotes:\n **Responsibilities:**\n\n - Iterates through the OpenAPI specification paths and methods.\n - Resolves each ``operationId`` to a handler function, and registers\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." - }, - "FastAPI": { - "name": "FastAPI", - "kind": "alias", - "path": "openapi_first.binder.FastAPI", - "signature": "", - "docstring": null + "signature": "", + "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n app (FastAPI):\n The FastAPI application instance to which routes will be added.\n spec (dict[str, Any]):\n Parsed OpenAPI 3.x specification dictionary.\n routes_module (ModuleType):\n Python module containing handler functions. Each handler's name MUST\n exactly match an OpenAPI `operationId`.\n security_deps (dict[str, list[Any]] | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n handler function exists in the routes module.\n\nNotes:\n **Responsibilities:**\n\n - Iterates through the OpenAPI specification paths and methods.\n - Resolves each ``operationId`` to a handler function, and registers\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." } } }, diff --git a/openapi-first/lib/app/index.html b/openapi-first/lib/app/index.html index bf06905..4280106 100644 --- a/openapi-first/lib/app/index.html +++ b/openapi-first/lib/app/index.html @@ -938,7 +938,7 @@ specification is treated as the authoritative API contract.

routes_module - Any + ModuleType
diff --git a/openapi-first/lib/binder/index.html b/openapi-first/lib/binder/index.html index 2a03e42..921bb86 100644 --- a/openapi-first/lib/binder/index.html +++ b/openapi-first/lib/binder/index.html @@ -811,7 +811,7 @@ between OpenAPI operations and Python handler functions using operationId< 6
bind_routes(
     app: FastAPI,
     spec: dict[str, Any],
-    routes_module: Any,
+    routes_module: ModuleType,
     security_deps: dict[str, list[Any]] | None = None,
 ) -> None
@@ -835,7 +835,7 @@ between OpenAPI operations and Python handler functions using operationId< app - Any + FastAPI
@@ -849,7 +849,7 @@ between OpenAPI operations and Python handler functions using operationId< spec - dict + dict[str, Any]
@@ -863,7 +863,7 @@ between OpenAPI operations and Python handler functions using operationId< routes_module - Any + ModuleType
diff --git a/openapi-first/lib/openapi_first/app/index.html b/openapi-first/lib/openapi_first/app/index.html index 3fc0cb2..520ab1a 100644 --- a/openapi-first/lib/openapi_first/app/index.html +++ b/openapi-first/lib/openapi_first/app/index.html @@ -820,7 +820,7 @@ specification is treated as the authoritative API contract.

routes_module - Any + ModuleType
diff --git a/openapi-first/lib/openapi_first/binder/index.html b/openapi-first/lib/openapi_first/binder/index.html index 0bb9d7d..89f2565 100644 --- a/openapi-first/lib/openapi_first/binder/index.html +++ b/openapi-first/lib/openapi_first/binder/index.html @@ -708,7 +708,7 @@ between OpenAPI operations and Python handler functions using operationId< 6
bind_routes(
     app: FastAPI,
     spec: dict[str, Any],
-    routes_module: Any,
+    routes_module: ModuleType,
     security_deps: dict[str, list[Any]] | None = None,
 ) -> None
@@ -732,7 +732,7 @@ between OpenAPI operations and Python handler functions using operationId< app - Any + FastAPI
@@ -746,7 +746,7 @@ between OpenAPI operations and Python handler functions using operationId< spec - dict + dict[str, Any]
@@ -760,7 +760,7 @@ between OpenAPI operations and Python handler functions using operationId< routes_module - Any + ModuleType
diff --git a/openapi-first/lib/search/search_index.json b/openapi-first/lib/search/search_index.json index 026feec..81e230a 100644 --- a/openapi-first/lib/search/search_index.json +++ b/openapi-first/lib/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"openapi_first","text":"
  • Openapi First
"},{"location":"#openapi_first","title":"openapi_first","text":""},{"location":"#openapi_first--summary","title":"Summary","text":"

FastAPI OpenAPI First \u2014 strict OpenAPI-first application bootstrap for FastAPI.

FastAPI OpenAPI First is a contract-first infrastructure library that enforces OpenAPI as the single source of truth for FastAPI services.

The library removes decorator-driven routing and replaces it with deterministic, spec-driven application assembly. Every HTTP route, method, and operation is defined in OpenAPI first and bound to Python handlers explicitly via operationId.

"},{"location":"#openapi_first--installation","title":"Installation","text":"

Install using pip:

pip install openapi-first\n

Or with Poetry:

poetry add openapi-first\n
"},{"location":"#openapi_first--quick-start","title":"Quick Start","text":"

Minimal OpenAPI-first FastAPI application:

from openapi_first import app\nimport my_service.routes as routes\n\napi = app.OpenAPIFirstApp(\n    openapi_path=\"openapi.yaml\",\n    routes_module=routes,\n    title=\"My Service\",\n    version=\"1.0.0\",\n)\n

OperationId-driven HTTP client:

from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\nresponse = client.get_health()\n
"},{"location":"#openapi_first--architecture","title":"Architecture","text":"

The library is structured around four core responsibilities:

  • loader: Load and validate OpenAPI 3.x specifications (JSON/YAML).
  • binder: Bind OpenAPI operations to FastAPI routes via operationId.
  • app: OpenAPI-first FastAPI application bootstrap.
  • client: OpenAPI-first HTTP client driven by the same specification.
  • errors: Explicit error hierarchy for contract violations.
"},{"location":"#openapi_first--public-api","title":"Public API","text":"

The supported public API consists of the following top-level modules:

  • openapi_first.app
  • openapi_first.binder
  • openapi_first.loader
  • openapi_first.client
  • openapi_first.errors
"},{"location":"#openapi_first--design-guarantees","title":"Design Guarantees","text":"
  • OpenAPI is the single source of truth.
  • No undocumented routes can exist.
  • No OpenAPI operation can exist without a handler or client callable.
  • All contract violations fail at application startup or client creation.
  • No hidden FastAPI magic or implicit behavior.
  • Deterministic, testable application assembly.
"},{"location":"app/","title":"App","text":""},{"location":"app/#openapi_first.app","title":"openapi_first.app","text":""},{"location":"app/#openapi_first.app--summary","title":"Summary","text":"

OpenAPI-first application bootstrap for FastAPI.

This module provides OpenAPIFirstApp, a thin but strict abstraction that enforces OpenAPI as the single source of truth for a FastAPI service.

Notes

Core Principles:

- The OpenAPI specification (JSON or YAML) defines the entire API surface.\n- Every `operationId` in the OpenAPI spec must have a corresponding\n  Python handler function.\n- Handlers are plain Python callables (no FastAPI decorators).\n- FastAPI route registration is derived exclusively from the spec.\n- FastAPI's autogenerated OpenAPI schema is fully overridden.\n

Responsibilities:

- Loads and validates an OpenAPI 3.x specification.\n- Dynamically binds HTTP routes to handler functions using `operationId`.\n- Registers routes with FastAPI at application startup.\n- Ensures runtime behavior matches the OpenAPI contract exactly.\n

Constraints:

- This module intentionally does NOT:\n    - Generate OpenAPI specs.\n    - Generate client code.\n    - Introduce a new framework or lifecycle.\n    - Alter FastAPI dependency injection semantics.\n
"},{"location":"app/#openapi_first.app-classes","title":"Classes","text":""},{"location":"app/#openapi_first.app.OpenAPIFirstApp","title":"OpenAPIFirstApp","text":"
OpenAPIFirstApp(\n    *,\n    openapi_path: str,\n    routes_module: Any,\n    **fastapi_kwargs: Any\n)\n

Bases: FastAPI

FastAPI application enforcing OpenAPI-first design.

Notes

Responsibilities:

- `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n  registration with OpenAPI-driven binding.\n- All routes are derived from the provided OpenAPI specification,\n  and each ``operationId`` is mapped to a Python function in the\n  supplied routes module.\n- Auth dependencies are auto-injected from the spec's\n  ``securitySchemes`` and per-operation ``security`` fields.\n

Guarantees:

- No route can exist without an OpenAPI declaration.\n- No OpenAPI operation can exist without a handler.\n- Swagger UI and ``/openapi.json`` always reflect the provided spec.\n- Handler functions remain framework-agnostic and testable.\n- Auth enforcement is driven entirely by the spec \u2014 no manual\n  middleware or decorators required.\n
Example 
from openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n    openapi_path=\"app/openapi.json\",\n    routes_module=routes,\n    title=\"Example Service\",\n)\n

Initialize the application.

Parameters:

Name Type Description Default openapi_path str

Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract.

required routes_module Any

Python module containing handler functions whose names correspond exactly to OpenAPI operationId values.

required **fastapi_kwargs Any

Additional keyword arguments passed directly to fastapi.FastAPI (e.g., title, version, middleware, lifespan handlers).

{}

Raises:

Type Description OpenAPIFirstError

If the OpenAPI specification is invalid, or if any declared operationId does not have a corresponding handler function.

"},{"location":"app/#openapi_first.app.OpenAPIFirstApp-functions","title":"Functions","text":""},{"location":"app/#openapi_first.app-functions","title":"Functions","text":""},{"location":"binder/","title":"Binder","text":""},{"location":"binder/#openapi_first.binder","title":"openapi_first.binder","text":""},{"location":"binder/#openapi_first.binder--summary","title":"Summary","text":"

OpenAPI-driven route binding for FastAPI.

This module is responsible for translating an OpenAPI 3.x specification into concrete FastAPI routes. It enforces a strict one-to-one mapping between OpenAPI operations and Python handler functions using operationId.

Notes

Core Responsibility:

- Read path + method definitions from an OpenAPI specification.\n- Resolve each `operationId` to a Python callable.\n- Register routes with FastAPI using `APIRoute`.\n- Fail fast when contract violations are detected.\n

Design Constraints:

- All routes MUST be declared in the OpenAPI specification.\n- All OpenAPI operations MUST define an `operationId`.\n- Every `operationId` MUST resolve to a handler function.\n- Handlers are plain Python callables (no decorators required).\n- No implicit route creation or inference is allowed.\n

Constraints:

- This module intentionally does NOT:\n    - Perform request or response validation.\n    - Generate Pydantic models.\n    - Modify FastAPI dependency injection.\n    - Interpret OpenAPI semantics beyond routing metadata.\n
"},{"location":"binder/#openapi_first.binder-classes","title":"Classes","text":""},{"location":"binder/#openapi_first.binder-functions","title":"Functions","text":""},{"location":"binder/#openapi_first.binder.bind_routes","title":"bind_routes","text":"
bind_routes(\n    app: FastAPI,\n    spec: dict[str, Any],\n    routes_module: Any,\n    security_deps: dict[str, list[Any]] | None = None,\n) -> None\n

Bind OpenAPI operations to FastAPI routes.

Parameters:

Name Type Description Default app Any

The FastAPI application instance to which routes will be added.

required spec dict

Parsed OpenAPI 3.x specification dictionary.

required routes_module Any

Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.

required security_deps dict[str, list[Any]] | None

Optional mapping of METHOD:/path \u2192 list[Depends(...)] generated from the spec's securitySchemes and per-operation security fields.

None

Raises:

Type Description MissingOperationHandler

If an operationId is missing from the spec or if no corresponding handler function exists in the routes module.

Notes

Responsibilities:

- Iterates through the OpenAPI specification paths and methods.\n- Resolves each ``operationId`` to a handler function, and registers\n  a corresponding ``APIRoute`` on the FastAPI application.\n- Injects FastAPI ``Depends()`` for each security requirement found\n  on the operation or inherited from the top-level ``security`` field.\n

Guarantees:

- Route registration is deterministic and spec-driven. No route\n  decorators are required or supported. Handler resolution errors\n  surface at application startup.\n
"},{"location":"cli/","title":"Cli","text":""},{"location":"cli/#openapi_first.cli","title":"openapi_first.cli","text":""},{"location":"cli/#openapi_first.cli--summary","title":"Summary","text":"

Command-line interface for FastAPI OpenAPI-first scaffolding utilities.

This CLI bootstraps OpenAPI-first FastAPI applications from versioned, bundled templates packaged with the library.

"},{"location":"cli/#openapi_first.cli-functions","title":"Functions","text":""},{"location":"cli/#openapi_first.cli.available_templates","title":"available_templates","text":"
available_templates() -> list[str]\n

Return a list of available application templates.

Returns:

Type Description list[str]

list[str]: Sorted list of template names found in the internal templates directory.

"},{"location":"cli/#openapi_first.cli.copy_template","title":"copy_template","text":"
copy_template(template: str, target_dir: Path) -> None\n

Copy a bundled OpenAPI-first application template into a directory.

Parameters:

Name Type Description Default template str

Name of the template to copy.

required target_dir Path

Filesystem path where the template should be copied.

required

Raises:

Type Description FileNotFoundError

If the requested template does not exist.

"},{"location":"client/","title":"Client","text":""},{"location":"client/#openapi_first.client","title":"openapi_first.client","text":""},{"location":"client/#openapi_first.client--summary","title":"Summary","text":"

OpenAPI-first HTTP client for contract-driven services.

This module provides OpenAPIClient, a thin, strict HTTP client that derives all callable operations directly from an OpenAPI 3.x specification.

It is the client counterpart to OpenAPIFirstApp.

Notes

Core Principles:

- The OpenAPI specification is the single source of truth\n- Each operationId becomes a callable Python method\n- No implicit schema mutation or inference\n- No code generation step\n- Minimal abstraction over httpx\n

Responsibilities:

- Parses an OpenAPI 3.x specification\n- Dynamically creates one callable per operationId\n- Enforces presence of servers, paths, and operationId\n- Formats path parameters safely\n- Handles JSON request bodies explicitly\n- Returns raw `httpx.Response` objects\n

Constraints:

- This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.\n
"},{"location":"client/#openapi_first.client-classes","title":"Classes","text":""},{"location":"client/#openapi_first.client.OpenAPIClient","title":"OpenAPIClient","text":"
OpenAPIClient(\n    spec: dict[str, Any],\n    base_url: str | None = None,\n    client: httpx.Client | None = None,\n)\n

OpenAPI-first HTTP client (httpx-based).

Notes

Responsibilities:

- This client derives all callable methods directly from an\n  OpenAPI 3.x specification. Each `operationId` becomes a method\n  on the client instance.\n

Guarantees:

- One callable per `operationId`.\n- Explicit parameters (path, query, headers, body).\n- No implicit schema inference or mutation.\n- Returns raw `httpx.Response` objects.\n- No response validation or deserialization.\n
Example 
from openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n    spec=spec,\n    base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n    path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n

Initialize the OpenAPI client.

Parameters:

Name Type Description Default spec dict[str, Any]

Parsed OpenAPI 3.x specification.

required base_url str | None

Base URL of the target service. If omitted, the first entry in the OpenAPI servers list is used.

None client Client | None

Optional preconfigured httpx client instance.

None

Raises:

Type Description OpenAPIClientError

If no servers are defined, spec has no paths, operationIds are missing/duplicate, or required parameters are missing.

"},{"location":"client/#openapi_first.client.OpenAPIClient-functions","title":"Functions","text":""},{"location":"client/#openapi_first.client.OpenAPIClientError","title":"OpenAPIClientError","text":"

Bases: OpenAPIFirstError

Raised when an OpenAPI client operation fails.

"},{"location":"codegen/","title":"Codegen","text":""},{"location":"codegen/#openapi_first.codegen","title":"openapi_first.codegen","text":""},{"location":"codegen/#openapi_first.codegen--summary","title":"Summary","text":"

Core logic for generating Python source code from OpenAPI specifications.

This module provides reusable utilities for code generation, specifically generating Pydantic models and route handler stubs from OpenAPI 3.x schema definitions.

"},{"location":"codegen/#openapi_first.codegen-functions","title":"Functions","text":""},{"location":"codegen/#openapi_first.codegen.generate_models","title":"generate_models","text":"
generate_models(\n    spec_path: Path,\n    output_path: Path,\n    pydantic_version: int = 2,\n) -> None\n

Generate Pydantic models from an OpenAPI specification.

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI specification file (YAML or JSON).

required output_path Path

Path where the generated Python code should be written.

required pydantic_version int

The Pydantic version to target (1 or 2). Defaults to 2.

2 Notes

Reusability: This function is designed to be used by the CLI and can be exposed as an MCP tool without modification.

"},{"location":"codegen/#openapi_first.codegen.generate_routes","title":"generate_routes","text":"
generate_routes(\n    spec_path: Path,\n    output_dir: Path,\n    *,\n    use_models: bool = False,\n    models_module: str = \"models\"\n) -> list[Path]\n

Generate route handler stubs from an OpenAPI specification.

Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI specification file (YAML or JSON).

required output_dir Path

Directory where the generated route files are written. Created automatically if it does not exist.

required use_models bool

If True, import Pydantic models from models_module for request-body schemas referenced via $ref.

False models_module str

Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").

'models'

Returns:

Type Description list[Path]

list[Path]: Absolute paths of every generated route file.

Raises:

Type Description OpenAPISpecLoadError

If the spec cannot be loaded or validated.

ValueError

If any operation is missing operationId.

"},{"location":"codegen_routes/","title":"Codegen Routes","text":""},{"location":"codegen_routes/#openapi_first.codegen_routes","title":"openapi_first.codegen_routes","text":""},{"location":"codegen_routes/#openapi_first.codegen_routes--summary","title":"Summary","text":"

Route handler code generation from OpenAPI specifications.

This module generates Python route handler stubs from an OpenAPI 3.x specification. Each resource (derived from the first path segment) gets its own file under the output directory. Every OpenAPI operation must define an operationId, which becomes the handler function name.

Notes

Design constraints:

- ``operationId`` is required on every operation (matching\n  ``binder.bind_routes``).\n- Handlers are stubs raising ``NotImplementedError``.\n- Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n  parent resource (``pets``).\n- Parameter types and defaults are inferred from the spec.\n- ``response: Response`` is injected for non-200 success codes.\n
"},{"location":"codegen_routes/#openapi_first.codegen_routes-functions","title":"Functions","text":""},{"location":"codegen_routes/#openapi_first.codegen_routes.generate_routes","title":"generate_routes","text":"
generate_routes(\n    spec_path: Path,\n    output_dir: Path,\n    *,\n    use_models: bool = False,\n    models_module: str = \"models\"\n) -> list[Path]\n

Generate route handler stubs from an OpenAPI specification.

Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI specification file (YAML or JSON).

required output_dir Path

Directory where the generated route files are written. Created automatically if it does not exist.

required use_models bool

If True, import Pydantic models from models_module for request-body schemas referenced via $ref.

False models_module str

Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").

'models'

Returns:

Type Description list[Path]

list[Path]: Absolute paths of every generated route file.

Raises:

Type Description OpenAPISpecLoadError

If the spec cannot be loaded or validated.

ValueError

If any operation is missing operationId.

"},{"location":"errors/","title":"Errors","text":""},{"location":"errors/#openapi_first.errors","title":"openapi_first.errors","text":""},{"location":"errors/#openapi_first.errors--summary","title":"Summary","text":"

Exceptions for OpenAPI-first FastAPI applications.

This module defines a small hierarchy of explicit, intention-revealing exceptions used to signal contract violations between an OpenAPI specification and its Python implementation.

Notes

Design Principles:

- Errors represent programmer mistakes, not runtime conditions.\n- All errors are raised during application startup.\n- Messages are actionable and suitable for CI/CD output.\n- Exceptions are explicit rather than reused from generic built-ins.\n

These errors should normally cause immediate application failure.

"},{"location":"errors/#openapi_first.errors-classes","title":"Classes","text":""},{"location":"errors/#openapi_first.errors.MissingOperationHandler","title":"MissingOperationHandler","text":"
MissingOperationHandler(\n    *,\n    path: str,\n    method: str,\n    operation_id: str | None = None\n)\n

Bases: OpenAPIFirstError

Raised when an OpenAPI operation cannot be resolved to a handler.

Notes

Scenarios:

- An OpenAPI operation does not define an `operationId`.\n- An `operationId` is defined but no matching function exists in\n  the provided routes module.\n

Guarantees:

- This represents a violation of the OpenAPI-first contract and\n  indicates that the specification and implementation are out of\n  sync.\n

Initialize the error.

Parameters:

Name Type Description Default path str

The HTTP path declared in the OpenAPI specification.

required method str

The HTTP method (as declared in the OpenAPI spec).

required operation_id str | None

The operationId declared in the OpenAPI spec, if present.

None"},{"location":"errors/#openapi_first.errors.MissingOperationHandler-functions","title":"Functions","text":""},{"location":"errors/#openapi_first.errors.OpenAPIFirstError","title":"OpenAPIFirstError","text":"

Bases: Exception

Base exception for all OpenAPI-first enforcement errors.

Notes

Responsibilities:

- This exception exists to allow callers, test suites, and CI\n  pipelines to catch and distinguish OpenAPI contract violations\n  from unrelated runtime errors.\n- All exceptions raised by the OpenAPI-first core should inherit\n  from this type.\n
"},{"location":"loader/","title":"Loader","text":""},{"location":"loader/#openapi_first.loader","title":"openapi_first.loader","text":""},{"location":"loader/#openapi_first.loader--summary","title":"Summary","text":"

OpenAPI specification loading and validation utilities.

This module is responsible for loading an OpenAPI 3.x specification from disk and validating it before it is used by the application.

It enforces the principle that an invalid or malformed OpenAPI document must never reach the routing or runtime layers.

Notes

Design Principles:

- OpenAPI is treated as an authoritative contract.\n- Invalid specifications fail fast at application startup.\n- Supported formats are JSON and YAML.\n- Validation errors are surfaced clearly and early.\n

Constraints:

- This module intentionally does NOT:\n    - Modify the OpenAPI document.\n    - Infer missing fields.\n    - Generate models or code.\n    - Perform request/response validation at runtime.\n
"},{"location":"loader/#openapi_first.loader-classes","title":"Classes","text":""},{"location":"loader/#openapi_first.loader.OpenAPISpecLoadError","title":"OpenAPISpecLoadError","text":"

Bases: OpenAPIFirstError

Raised when an OpenAPI specification cannot be loaded or validated.

Notes

Guarantees:

- This error indicates that the OpenAPI document is unreadable,\n  malformed, or violates the OpenAPI 3.x specification.\n
"},{"location":"loader/#openapi_first.loader-functions","title":"Functions","text":""},{"location":"loader/#openapi_first.loader.load_openapi","title":"load_openapi","text":"
load_openapi(path: str | Path) -> dict[str, Any]\n

Load and validate an OpenAPI 3.x specification from disk.

Parameters:

Name Type Description Default path str | Path

Filesystem path to an OpenAPI specification file. Supported extensions: .json, .yaml, .yml.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Parsed and validated OpenAPI specification.

Raises:

Type Description OpenAPISpecLoadError

If the file does not exist, cannot be parsed, or fails OpenAPI schema validation.

Notes

Guarantees:

- The specification is parsed based on file extension and validated\n  using a strict OpenAPI schema validator.\n- Any error results in an immediate exception, preventing\n  application startup.\n
"},{"location":"security/","title":"Security","text":""},{"location":"security/#openapi_first.security","title":"openapi_first.security","text":""},{"location":"security/#openapi_first.security--summary","title":"Summary","text":"

OpenAPI security scheme parsing and auto-generated auth dependencies.

This module reads securitySchemes and per-operation security from an OpenAPI spec, resolves {ENV_VAR} placeholders in x- extension fields, and generates FastAPI dependencies for token validation (e.g., Bearer JWT introspection).

"},{"location":"security/#openapi_first.security-functions","title":"Functions","text":""},{"location":"security/#openapi_first.security.make_security_dependencies","title":"make_security_dependencies","text":"
make_security_dependencies(\n    spec: dict[str, Any],\n    security_schemes: dict[str, dict[str, Any]],\n) -> dict[str, list[Any]]\n

Build a mapping of METHOD:/path \u2192 list of Depends(...).

The effective security for each operation is resolved by:

  1. Using the operation-level security field if present.
  2. Falling back to the top-level security field.
  3. An empty list means no auth required for that operation.
"},{"location":"security/#openapi_first.security.parse_security_schemes","title":"parse_security_schemes","text":"
parse_security_schemes(\n    spec: dict[str, Any],\n) -> dict[str, dict[str, Any]]\n

Extract and resolve environment variables in security schemes.

"},{"location":"openapi_first/","title":"Openapi First","text":"
  • App
  • Binder
  • Cli
  • Client
  • Codegen
  • Codegen Routes
  • Errors
  • Loader
  • Security
  • Templates
"},{"location":"openapi_first/#openapi_first","title":"openapi_first","text":""},{"location":"openapi_first/#openapi_first--summary","title":"Summary","text":"

FastAPI OpenAPI First \u2014 strict OpenAPI-first application bootstrap for FastAPI.

FastAPI OpenAPI First is a contract-first infrastructure library that enforces OpenAPI as the single source of truth for FastAPI services.

The library removes decorator-driven routing and replaces it with deterministic, spec-driven application assembly. Every HTTP route, method, and operation is defined in OpenAPI first and bound to Python handlers explicitly via operationId.

"},{"location":"openapi_first/#openapi_first--installation","title":"Installation","text":"

Install using pip:

pip install openapi-first\n

Or with Poetry:

poetry add openapi-first\n
"},{"location":"openapi_first/#openapi_first--quick-start","title":"Quick Start","text":"

Minimal OpenAPI-first FastAPI application:

from openapi_first import app\nimport my_service.routes as routes\n\napi = app.OpenAPIFirstApp(\n    openapi_path=\"openapi.yaml\",\n    routes_module=routes,\n    title=\"My Service\",\n    version=\"1.0.0\",\n)\n

OperationId-driven HTTP client:

from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\nresponse = client.get_health()\n
"},{"location":"openapi_first/#openapi_first--architecture","title":"Architecture","text":"

The library is structured around four core responsibilities:

  • loader: Load and validate OpenAPI 3.x specifications (JSON/YAML).
  • binder: Bind OpenAPI operations to FastAPI routes via operationId.
  • app: OpenAPI-first FastAPI application bootstrap.
  • client: OpenAPI-first HTTP client driven by the same specification.
  • errors: Explicit error hierarchy for contract violations.
"},{"location":"openapi_first/#openapi_first--public-api","title":"Public API","text":"

The supported public API consists of the following top-level modules:

  • openapi_first.app
  • openapi_first.binder
  • openapi_first.loader
  • openapi_first.client
  • openapi_first.errors
"},{"location":"openapi_first/#openapi_first--design-guarantees","title":"Design Guarantees","text":"
  • OpenAPI is the single source of truth.
  • No undocumented routes can exist.
  • No OpenAPI operation can exist without a handler or client callable.
  • All contract violations fail at application startup or client creation.
  • No hidden FastAPI magic or implicit behavior.
  • Deterministic, testable application assembly.
"},{"location":"openapi_first/app/","title":"App","text":""},{"location":"openapi_first/app/#openapi_first.app","title":"openapi_first.app","text":""},{"location":"openapi_first/app/#openapi_first.app--summary","title":"Summary","text":"

OpenAPI-first application bootstrap for FastAPI.

This module provides OpenAPIFirstApp, a thin but strict abstraction that enforces OpenAPI as the single source of truth for a FastAPI service.

Notes

Core Principles:

- The OpenAPI specification (JSON or YAML) defines the entire API surface.\n- Every `operationId` in the OpenAPI spec must have a corresponding\n  Python handler function.\n- Handlers are plain Python callables (no FastAPI decorators).\n- FastAPI route registration is derived exclusively from the spec.\n- FastAPI's autogenerated OpenAPI schema is fully overridden.\n

Responsibilities:

- Loads and validates an OpenAPI 3.x specification.\n- Dynamically binds HTTP routes to handler functions using `operationId`.\n- Registers routes with FastAPI at application startup.\n- Ensures runtime behavior matches the OpenAPI contract exactly.\n

Constraints:

- This module intentionally does NOT:\n    - Generate OpenAPI specs.\n    - Generate client code.\n    - Introduce a new framework or lifecycle.\n    - Alter FastAPI dependency injection semantics.\n
"},{"location":"openapi_first/app/#openapi_first.app-classes","title":"Classes","text":""},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp","title":"OpenAPIFirstApp","text":"
OpenAPIFirstApp(\n    *,\n    openapi_path: str,\n    routes_module: Any,\n    **fastapi_kwargs: Any\n)\n

Bases: FastAPI

FastAPI application enforcing OpenAPI-first design.

Notes

Responsibilities:

- `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n  registration with OpenAPI-driven binding.\n- All routes are derived from the provided OpenAPI specification,\n  and each ``operationId`` is mapped to a Python function in the\n  supplied routes module.\n- Auth dependencies are auto-injected from the spec's\n  ``securitySchemes`` and per-operation ``security`` fields.\n

Guarantees:

- No route can exist without an OpenAPI declaration.\n- No OpenAPI operation can exist without a handler.\n- Swagger UI and ``/openapi.json`` always reflect the provided spec.\n- Handler functions remain framework-agnostic and testable.\n- Auth enforcement is driven entirely by the spec \u2014 no manual\n  middleware or decorators required.\n
Example 
from openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n    openapi_path=\"app/openapi.json\",\n    routes_module=routes,\n    title=\"Example Service\",\n)\n

Initialize the application.

Parameters:

Name Type Description Default openapi_path str

Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract.

required routes_module Any

Python module containing handler functions whose names correspond exactly to OpenAPI operationId values.

required **fastapi_kwargs Any

Additional keyword arguments passed directly to fastapi.FastAPI (e.g., title, version, middleware, lifespan handlers).

{}

Raises:

Type Description OpenAPIFirstError

If the OpenAPI specification is invalid, or if any declared operationId does not have a corresponding handler function.

"},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp-functions","title":"Functions","text":""},{"location":"openapi_first/app/#openapi_first.app-functions","title":"Functions","text":""},{"location":"openapi_first/binder/","title":"Binder","text":""},{"location":"openapi_first/binder/#openapi_first.binder","title":"openapi_first.binder","text":""},{"location":"openapi_first/binder/#openapi_first.binder--summary","title":"Summary","text":"

OpenAPI-driven route binding for FastAPI.

This module is responsible for translating an OpenAPI 3.x specification into concrete FastAPI routes. It enforces a strict one-to-one mapping between OpenAPI operations and Python handler functions using operationId.

Notes

Core Responsibility:

- Read path + method definitions from an OpenAPI specification.\n- Resolve each `operationId` to a Python callable.\n- Register routes with FastAPI using `APIRoute`.\n- Fail fast when contract violations are detected.\n

Design Constraints:

- All routes MUST be declared in the OpenAPI specification.\n- All OpenAPI operations MUST define an `operationId`.\n- Every `operationId` MUST resolve to a handler function.\n- Handlers are plain Python callables (no decorators required).\n- No implicit route creation or inference is allowed.\n

Constraints:

- This module intentionally does NOT:\n    - Perform request or response validation.\n    - Generate Pydantic models.\n    - Modify FastAPI dependency injection.\n    - Interpret OpenAPI semantics beyond routing metadata.\n
"},{"location":"openapi_first/binder/#openapi_first.binder-classes","title":"Classes","text":""},{"location":"openapi_first/binder/#openapi_first.binder-functions","title":"Functions","text":""},{"location":"openapi_first/binder/#openapi_first.binder.bind_routes","title":"bind_routes","text":"
bind_routes(\n    app: FastAPI,\n    spec: dict[str, Any],\n    routes_module: Any,\n    security_deps: dict[str, list[Any]] | None = None,\n) -> None\n

Bind OpenAPI operations to FastAPI routes.

Parameters:

Name Type Description Default app Any

The FastAPI application instance to which routes will be added.

required spec dict

Parsed OpenAPI 3.x specification dictionary.

required routes_module Any

Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.

required security_deps dict[str, list[Any]] | None

Optional mapping of METHOD:/path \u2192 list[Depends(...)] generated from the spec's securitySchemes and per-operation security fields.

None

Raises:

Type Description MissingOperationHandler

If an operationId is missing from the spec or if no corresponding handler function exists in the routes module.

Notes

Responsibilities:

- Iterates through the OpenAPI specification paths and methods.\n- Resolves each ``operationId`` to a handler function, and registers\n  a corresponding ``APIRoute`` on the FastAPI application.\n- Injects FastAPI ``Depends()`` for each security requirement found\n  on the operation or inherited from the top-level ``security`` field.\n

Guarantees:

- Route registration is deterministic and spec-driven. No route\n  decorators are required or supported. Handler resolution errors\n  surface at application startup.\n
"},{"location":"openapi_first/cli/","title":"Cli","text":""},{"location":"openapi_first/cli/#openapi_first.cli","title":"openapi_first.cli","text":""},{"location":"openapi_first/cli/#openapi_first.cli--summary","title":"Summary","text":"

Command-line interface for FastAPI OpenAPI-first scaffolding utilities.

This CLI bootstraps OpenAPI-first FastAPI applications from versioned, bundled templates packaged with the library.

"},{"location":"openapi_first/cli/#openapi_first.cli-functions","title":"Functions","text":""},{"location":"openapi_first/cli/#openapi_first.cli.available_templates","title":"available_templates","text":"
available_templates() -> list[str]\n

Return a list of available application templates.

Returns:

Type Description list[str]

list[str]: Sorted list of template names found in the internal templates directory.

"},{"location":"openapi_first/cli/#openapi_first.cli.copy_template","title":"copy_template","text":"
copy_template(template: str, target_dir: Path) -> None\n

Copy a bundled OpenAPI-first application template into a directory.

Parameters:

Name Type Description Default template str

Name of the template to copy.

required target_dir Path

Filesystem path where the template should be copied.

required

Raises:

Type Description FileNotFoundError

If the requested template does not exist.

"},{"location":"openapi_first/client/","title":"Client","text":""},{"location":"openapi_first/client/#openapi_first.client","title":"openapi_first.client","text":""},{"location":"openapi_first/client/#openapi_first.client--summary","title":"Summary","text":"

OpenAPI-first HTTP client for contract-driven services.

This module provides OpenAPIClient, a thin, strict HTTP client that derives all callable operations directly from an OpenAPI 3.x specification.

It is the client counterpart to OpenAPIFirstApp.

Notes

Core Principles:

- The OpenAPI specification is the single source of truth\n- Each operationId becomes a callable Python method\n- No implicit schema mutation or inference\n- No code generation step\n- Minimal abstraction over httpx\n

Responsibilities:

- Parses an OpenAPI 3.x specification\n- Dynamically creates one callable per operationId\n- Enforces presence of servers, paths, and operationId\n- Formats path parameters safely\n- Handles JSON request bodies explicitly\n- Returns raw `httpx.Response` objects\n

Constraints:

- This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.\n
"},{"location":"openapi_first/client/#openapi_first.client-classes","title":"Classes","text":""},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClient","title":"OpenAPIClient","text":"
OpenAPIClient(\n    spec: dict[str, Any],\n    base_url: str | None = None,\n    client: httpx.Client | None = None,\n)\n

OpenAPI-first HTTP client (httpx-based).

Notes

Responsibilities:

- This client derives all callable methods directly from an\n  OpenAPI 3.x specification. Each `operationId` becomes a method\n  on the client instance.\n

Guarantees:

- One callable per `operationId`.\n- Explicit parameters (path, query, headers, body).\n- No implicit schema inference or mutation.\n- Returns raw `httpx.Response` objects.\n- No response validation or deserialization.\n
Example 
from openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n    spec=spec,\n    base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n    path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n

Initialize the OpenAPI client.

Parameters:

Name Type Description Default spec dict[str, Any]

Parsed OpenAPI 3.x specification.

required base_url str | None

Base URL of the target service. If omitted, the first entry in the OpenAPI servers list is used.

None client Client | None

Optional preconfigured httpx client instance.

None

Raises:

Type Description OpenAPIClientError

If no servers are defined, spec has no paths, operationIds are missing/duplicate, or required parameters are missing.

"},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClient-functions","title":"Functions","text":""},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClientError","title":"OpenAPIClientError","text":"

Bases: OpenAPIFirstError

Raised when an OpenAPI client operation fails.

"},{"location":"openapi_first/codegen/","title":"Codegen","text":""},{"location":"openapi_first/codegen/#openapi_first.codegen","title":"openapi_first.codegen","text":""},{"location":"openapi_first/codegen/#openapi_first.codegen--summary","title":"Summary","text":"

Core logic for generating Python source code from OpenAPI specifications.

This module provides reusable utilities for code generation, specifically generating Pydantic models and route handler stubs from OpenAPI 3.x schema definitions.

"},{"location":"openapi_first/codegen/#openapi_first.codegen-functions","title":"Functions","text":""},{"location":"openapi_first/codegen/#openapi_first.codegen.generate_models","title":"generate_models","text":"
generate_models(\n    spec_path: Path,\n    output_path: Path,\n    pydantic_version: int = 2,\n) -> None\n

Generate Pydantic models from an OpenAPI specification.

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI specification file (YAML or JSON).

required output_path Path

Path where the generated Python code should be written.

required pydantic_version int

The Pydantic version to target (1 or 2). Defaults to 2.

2 Notes

Reusability: This function is designed to be used by the CLI and can be exposed as an MCP tool without modification.

"},{"location":"openapi_first/codegen/#openapi_first.codegen.generate_routes","title":"generate_routes","text":"
generate_routes(\n    spec_path: Path,\n    output_dir: Path,\n    *,\n    use_models: bool = False,\n    models_module: str = \"models\"\n) -> list[Path]\n

Generate route handler stubs from an OpenAPI specification.

Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI specification file (YAML or JSON).

required output_dir Path

Directory where the generated route files are written. Created automatically if it does not exist.

required use_models bool

If True, import Pydantic models from models_module for request-body schemas referenced via $ref.

False models_module str

Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").

'models'

Returns:

Type Description list[Path]

list[Path]: Absolute paths of every generated route file.

Raises:

Type Description OpenAPISpecLoadError

If the spec cannot be loaded or validated.

ValueError

If any operation is missing operationId.

"},{"location":"openapi_first/codegen_routes/","title":"Codegen Routes","text":""},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes","title":"openapi_first.codegen_routes","text":""},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes--summary","title":"Summary","text":"

Route handler code generation from OpenAPI specifications.

This module generates Python route handler stubs from an OpenAPI 3.x specification. Each resource (derived from the first path segment) gets its own file under the output directory. Every OpenAPI operation must define an operationId, which becomes the handler function name.

Notes

Design constraints:

- ``operationId`` is required on every operation (matching\n  ``binder.bind_routes``).\n- Handlers are stubs raising ``NotImplementedError``.\n- Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n  parent resource (``pets``).\n- Parameter types and defaults are inferred from the spec.\n- ``response: Response`` is injected for non-200 success codes.\n
"},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes-functions","title":"Functions","text":""},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes.generate_routes","title":"generate_routes","text":"
generate_routes(\n    spec_path: Path,\n    output_dir: Path,\n    *,\n    use_models: bool = False,\n    models_module: str = \"models\"\n) -> list[Path]\n

Generate route handler stubs from an OpenAPI specification.

Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI specification file (YAML or JSON).

required output_dir Path

Directory where the generated route files are written. Created automatically if it does not exist.

required use_models bool

If True, import Pydantic models from models_module for request-body schemas referenced via $ref.

False models_module str

Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").

'models'

Returns:

Type Description list[Path]

list[Path]: Absolute paths of every generated route file.

Raises:

Type Description OpenAPISpecLoadError

If the spec cannot be loaded or validated.

ValueError

If any operation is missing operationId.

"},{"location":"openapi_first/errors/","title":"Errors","text":""},{"location":"openapi_first/errors/#openapi_first.errors","title":"openapi_first.errors","text":""},{"location":"openapi_first/errors/#openapi_first.errors--summary","title":"Summary","text":"

Exceptions for OpenAPI-first FastAPI applications.

This module defines a small hierarchy of explicit, intention-revealing exceptions used to signal contract violations between an OpenAPI specification and its Python implementation.

Notes

Design Principles:

- Errors represent programmer mistakes, not runtime conditions.\n- All errors are raised during application startup.\n- Messages are actionable and suitable for CI/CD output.\n- Exceptions are explicit rather than reused from generic built-ins.\n

These errors should normally cause immediate application failure.

"},{"location":"openapi_first/errors/#openapi_first.errors-classes","title":"Classes","text":""},{"location":"openapi_first/errors/#openapi_first.errors.MissingOperationHandler","title":"MissingOperationHandler","text":"
MissingOperationHandler(\n    *,\n    path: str,\n    method: str,\n    operation_id: str | None = None\n)\n

Bases: OpenAPIFirstError

Raised when an OpenAPI operation cannot be resolved to a handler.

Notes

Scenarios:

- An OpenAPI operation does not define an `operationId`.\n- An `operationId` is defined but no matching function exists in\n  the provided routes module.\n

Guarantees:

- This represents a violation of the OpenAPI-first contract and\n  indicates that the specification and implementation are out of\n  sync.\n

Initialize the error.

Parameters:

Name Type Description Default path str

The HTTP path declared in the OpenAPI specification.

required method str

The HTTP method (as declared in the OpenAPI spec).

required operation_id str | None

The operationId declared in the OpenAPI spec, if present.

None"},{"location":"openapi_first/errors/#openapi_first.errors.MissingOperationHandler-functions","title":"Functions","text":""},{"location":"openapi_first/errors/#openapi_first.errors.OpenAPIFirstError","title":"OpenAPIFirstError","text":"

Bases: Exception

Base exception for all OpenAPI-first enforcement errors.

Notes

Responsibilities:

- This exception exists to allow callers, test suites, and CI\n  pipelines to catch and distinguish OpenAPI contract violations\n  from unrelated runtime errors.\n- All exceptions raised by the OpenAPI-first core should inherit\n  from this type.\n
"},{"location":"openapi_first/loader/","title":"Loader","text":""},{"location":"openapi_first/loader/#openapi_first.loader","title":"openapi_first.loader","text":""},{"location":"openapi_first/loader/#openapi_first.loader--summary","title":"Summary","text":"

OpenAPI specification loading and validation utilities.

This module is responsible for loading an OpenAPI 3.x specification from disk and validating it before it is used by the application.

It enforces the principle that an invalid or malformed OpenAPI document must never reach the routing or runtime layers.

Notes

Design Principles:

- OpenAPI is treated as an authoritative contract.\n- Invalid specifications fail fast at application startup.\n- Supported formats are JSON and YAML.\n- Validation errors are surfaced clearly and early.\n

Constraints:

- This module intentionally does NOT:\n    - Modify the OpenAPI document.\n    - Infer missing fields.\n    - Generate models or code.\n    - Perform request/response validation at runtime.\n
"},{"location":"openapi_first/loader/#openapi_first.loader-classes","title":"Classes","text":""},{"location":"openapi_first/loader/#openapi_first.loader.OpenAPISpecLoadError","title":"OpenAPISpecLoadError","text":"

Bases: OpenAPIFirstError

Raised when an OpenAPI specification cannot be loaded or validated.

Notes

Guarantees:

- This error indicates that the OpenAPI document is unreadable,\n  malformed, or violates the OpenAPI 3.x specification.\n
"},{"location":"openapi_first/loader/#openapi_first.loader-functions","title":"Functions","text":""},{"location":"openapi_first/loader/#openapi_first.loader.load_openapi","title":"load_openapi","text":"
load_openapi(path: str | Path) -> dict[str, Any]\n

Load and validate an OpenAPI 3.x specification from disk.

Parameters:

Name Type Description Default path str | Path

Filesystem path to an OpenAPI specification file. Supported extensions: .json, .yaml, .yml.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Parsed and validated OpenAPI specification.

Raises:

Type Description OpenAPISpecLoadError

If the file does not exist, cannot be parsed, or fails OpenAPI schema validation.

Notes

Guarantees:

- The specification is parsed based on file extension and validated\n  using a strict OpenAPI schema validator.\n- Any error results in an immediate exception, preventing\n  application startup.\n
"},{"location":"openapi_first/security/","title":"Security","text":""},{"location":"openapi_first/security/#openapi_first.security","title":"openapi_first.security","text":""},{"location":"openapi_first/security/#openapi_first.security--summary","title":"Summary","text":"

OpenAPI security scheme parsing and auto-generated auth dependencies.

This module reads securitySchemes and per-operation security from an OpenAPI spec, resolves {ENV_VAR} placeholders in x- extension fields, and generates FastAPI dependencies for token validation (e.g., Bearer JWT introspection).

"},{"location":"openapi_first/security/#openapi_first.security-functions","title":"Functions","text":""},{"location":"openapi_first/security/#openapi_first.security.make_security_dependencies","title":"make_security_dependencies","text":"
make_security_dependencies(\n    spec: dict[str, Any],\n    security_schemes: dict[str, dict[str, Any]],\n) -> dict[str, list[Any]]\n

Build a mapping of METHOD:/path \u2192 list of Depends(...).

The effective security for each operation is resolved by:

  1. Using the operation-level security field if present.
  2. Falling back to the top-level security field.
  3. An empty list means no auth required for that operation.
"},{"location":"openapi_first/security/#openapi_first.security.parse_security_schemes","title":"parse_security_schemes","text":"
parse_security_schemes(\n    spec: dict[str, Any],\n) -> dict[str, dict[str, Any]]\n

Extract and resolve environment variables in security schemes.

"},{"location":"openapi_first/templates/","title":"Templates","text":"
  • Crud App
  • Health App
  • Model App
  • Vet App
"},{"location":"openapi_first/templates/#openapi_first.templates","title":"openapi_first.templates","text":"

Application templates for FastAPI OpenAPI First.

This package contains example and scaffolding templates intended to be copied into user projects via the openapi-first CLI.

Templates in this package are: - Reference implementations of OpenAPI-first services - Not part of the openapi_first public or internal API - Not intended to be imported as runtime dependencies

The presence of this file exists solely to: - Mark the directory as an explicit Python package - Enable deterministic tooling behavior (documentation, packaging) - Avoid accidental traversal of non-package directories

No code in this package should be imported by library consumers.

"},{"location":"openapi_first/templates/crud_app/","title":"Crud App","text":"
  • Data
  • Main
  • Routes
  • Test Crud App
"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app","title":"openapi_first.templates.crud_app","text":"

OpenAPI-first CRUD application template.

This package contains a complete, minimal example of an OpenAPI-first CRUD service built using the openapi_first library.

The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace implementing CRUD operations (routes) - an in-memory mock data store (data)

All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification and enforced at application startup. No decorator-driven routing or implicit framework behavior is used.

This template demonstrates: - operationId-driven server-side route binding - explicit HTTP status code control in handlers - operationId-driven client usage against the same OpenAPI contract - end-to-end validation using in-memory data and tests

"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"

Create a new CRUD example service using the bundled template:

openapi-first crud_app\n

Create the service in a custom directory:

openapi-first crud_app my-crud-service\n

List all available application templates:

openapi-first --list\n

The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.

"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--client-usage-example","title":"Client Usage Example","text":"

The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.

Example client calls for CRUD operations:

from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List items\nresponse = client.list_items()\n\n# Get item by ID\nresponse = client.get_item(\n    path_params={\"item_id\": 1}\n)\n\n# Create item\nresponse = client.create_item(\n    body={\"name\": \"Orange\", \"price\": 0.8}\n)\n\n# Update item\nresponse = client.update_item(\n    path_params={\"item_id\": 1},\n    body={\"name\": \"Green Apple\", \"price\": 0.6},\n)\n\n# Delete item\nresponse = client.delete_item(\n    path_params={\"item_id\": 1}\n)\n

Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Path and request parameters must match the OpenAPI specification - Invalid or incomplete OpenAPI specs fail at client construction time

"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--non-goals","title":"Non-Goals","text":"

This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage

It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.

This package is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/crud_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data","title":"openapi_first.templates.crud_app.data","text":"

In-memory mock data store for CRUD example.

This module intentionally avoids persistence and concurrency guarantees. It is suitable for demos, tests, and scaffolding only.

It intentionally avoids - persistence - concurrency guarantees - validation - error handling

The implementation is suitable for: - demonstrations - tests - scaffolding and example services

It is explicitly NOT suitable for production use.

This module is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data-functions","title":"Functions","text":""},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item","title":"create_item","text":"
create_item(payload: dict)\n

Create a new item in the data store.

A new integer ID is assigned automatically. No validation is performed on the provided payload.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item--parameters","title":"Parameters","text":"

payload : dict Item attributes excluding the id field.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item--returns","title":"Returns","text":"

dict The newly created item, including its assigned ID.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.delete_item","title":"delete_item","text":"
delete_item(item_id: int)\n

Remove an item from the data store.

This function assumes the item exists and will raise KeyError if the ID is not present.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.delete_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to delete.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item","title":"get_item","text":"
get_item(item_id: int)\n

Retrieve a single item by ID.

This function assumes the item exists and will raise KeyError if the ID is not present in the store.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to retrieve.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item--returns","title":"Returns","text":"

dict The stored item representation.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.list_items","title":"list_items","text":"
list_items()\n

Return all items in the data store.

This function performs no filtering, pagination, or sorting. The returned collection reflects the current in-memory state.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.list_items--returns","title":"Returns","text":"

list[dict] A list of item representations.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item","title":"update_item","text":"
update_item(item_id: int, payload: dict)\n

Replace an existing item in the data store.

This function overwrites the existing item entirely and does not perform partial updates or validation. If the item does not exist, it will be created implicitly.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to update. payload : dict Item attributes excluding the id field.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item--returns","title":"Returns","text":"

dict The updated item representation.

"},{"location":"openapi_first/templates/crud_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/crud_app/main/#openapi_first.templates.crud_app.main","title":"openapi_first.templates.crud_app.main","text":"

Application entry point for an OpenAPI-first CRUD example service.

This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.

All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.

This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.

Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup

This file is intended to be used as the ASGI entry point.

Example

uvicorn main:app

"},{"location":"openapi_first/templates/crud_app/main/#openapi_first.templates.crud_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/crud_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes","title":"openapi_first.templates.crud_app.routes","text":"

CRUD route handlers bound via OpenAPI operationId.

These handlers explicitly control HTTP status codes to ensure runtime behavior matches the OpenAPI contract.

This module defines OpenAPI-bound operation handlers for a simple CRUD service. Functions in this module are bound to HTTP routes exclusively via OpenAPI operationId values.

Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Error conditions are translated into explicit HTTP responses rather than relying on implicit framework behavior.

No routing decorators or path definitions appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item","title":"create_item","text":"
create_item(payload: dict, response: Response)\n

Create a new item.

Implements the OpenAPI operation identified by operationId: create_item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item--parameters","title":"Parameters","text":"

payload : dict Item attributes excluding the id field. response : fastapi.Response Response object used to set the HTTP status code.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item--returns","title":"Returns","text":"

dict The newly created item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item","title":"delete_item","text":"
delete_item(item_id: int, response: Response)\n

Delete an existing item.

Implements the OpenAPI operation identified by operationId: delete_item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to delete. response : fastapi.Response Response object used to set the HTTP status code.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--returns","title":"Returns","text":"

None No content.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item","title":"get_item","text":"
get_item(item_id: int)\n

Retrieve a single item by ID.

Implements the OpenAPI operation identified by operationId: get_item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to retrieve.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--returns","title":"Returns","text":"

dict The requested item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.list_items","title":"list_items","text":"
list_items()\n

List all items.

Implements the OpenAPI operation identified by operationId: list_items.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.list_items--returns","title":"Returns","text":"

list[dict] A list of item representations.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item","title":"update_item","text":"
update_item(item_id: int, payload: dict)\n

Update an existing item.

Implements the OpenAPI operation identified by operationId: update_item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to update. payload : dict Item attributes excluding the id field.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--returns","title":"Returns","text":"

dict The updated item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/crud_app/test_crud_app/","title":"Test Crud App","text":""},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app","title":"openapi_first.templates.crud_app.test_crud_app","text":"

End-to-end tests for the OpenAPI-first CRUD example app.

These tests validate that all CRUD operations behave correctly against the in-memory mock data store. - OpenAPI specification loading - OperationId-driven route binding on the server - OperationId-driven client invocation - Correct HTTP status codes and response payloads

The tests exercise all CRUD operations against an in-memory mock data store and assume deterministic behavior within a single process.

The tests assume: - OpenAPI-first route binding - In-memory storage (no persistence guarantees) - Deterministic behavior in a single process - One-to-one correspondence between OpenAPI operationId values and server/client callables

"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app-classes","title":"Classes","text":""},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app-functions","title":"Functions","text":""},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_create_item","title":"test_create_item","text":"
test_create_item()\n

Creating a new item should return the created entity.

"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_delete_item","title":"test_delete_item","text":"
test_delete_item()\n

Deleting an item should remove it from the store.

"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_get_item","title":"test_get_item","text":"
test_get_item()\n

Existing item should be retrievable by ID.

"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_list_items_initial","title":"test_list_items_initial","text":"
test_list_items_initial()\n

Initial items should be present.

"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_update_item","title":"test_update_item","text":"
test_update_item()\n

Updating an item should replace its values.

"},{"location":"openapi_first/templates/health_app/","title":"Health App","text":"
  • Main
  • Routes
"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app","title":"openapi_first.templates.health_app","text":"

OpenAPI-first FastAPI application template.

This package contains a minimal, fully working example of an OpenAPI-first FastAPI service built using the openapi_first library.

The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace (routes)

No routing decorators, implicit behavior, or framework-specific convenience abstractions are used. All HTTP routes, methods, and operation bindings are defined in OpenAPI and enforced at application startup.

This package is intended to be copied as a starting point for new services via the openapi-first CLI. It is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"

Create a new OpenAPI-first health check service using the bundled template:

openapi-first health_app\n

Create the service in a custom directory:

openapi-first health_app my-health-service\n

List all available application templates:

openapi-first --list\n

The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.

"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app--client-usage-example","title":"Client Usage Example","text":"

The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.

Example client call for the get_health operation:

from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\nresponse = client.get_health()\n\nassert response.status_code == 200\nassert response.json() == {\"status\": \"ok\"}\n

Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Path and request parameters must match the OpenAPI specification - Invalid or incomplete OpenAPI specs fail at client construction time

"},{"location":"openapi_first/templates/health_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/health_app/main/#openapi_first.templates.health_app.main","title":"openapi_first.templates.health_app.main","text":"

Application entry point for an OpenAPI-first FastAPI service.

This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.

All HTTP routes, methods, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.

This module contains no routing logic, request handling, or framework configuration beyond application assembly.

Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup

This file is intended to be used as the ASGI entry point.

Example

uvicorn main:app

"},{"location":"openapi_first/templates/health_app/main/#openapi_first.templates.health_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/health_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes","title":"openapi_first.templates.health_app.routes","text":"

OpenAPI operation handlers.

This module defines pure Python callables that implement OpenAPI operations for this service. Functions in this module are bound to HTTP routes exclusively via OpenAPI operationId values.

No routing decorators, HTTP metadata, or framework-specific logic should appear here. All request/response semantics are defined in the OpenAPI specification.

This module serves solely as an operationId namespace.

"},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes.get_health","title":"get_health","text":"
get_health()\n

Health check operation handler.

This function implements the OpenAPI operation identified by operationId: get_health.

It contains no routing metadata or framework-specific logic. Request binding, HTTP method, and response semantics are defined exclusively by the OpenAPI specification.

"},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes.get_health--returns","title":"Returns","text":"

dict A minimal liveness payload indicating service health.

"},{"location":"openapi_first/templates/model_app/","title":"Model App","text":"
  • Data
  • Main
  • Models
  • Routes
  • Test Model App
"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app","title":"openapi_first.templates.model_app","text":"

OpenAPI-first model-based CRUD application template.

This package contains a complete, minimal example of an OpenAPI-first CRUD service that uses explicit Pydantic domain models for request and response schemas.

The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace implementing CRUD operations (routes) - Pydantic domain models (models) - an in-memory mock data store (data)

All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification and enforced at application startup. No decorator-driven routing or implicit framework behavior is used.

This template demonstrates: - operationId-driven server-side route binding - explicit request and response modeling with Pydantic - explicit HTTP status code control in handlers - operationId-driven client usage against the same OpenAPI contract - end-to-end validation using in-memory data and tests

"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"

Create a new model-based CRUD example service using the bundled template:

openapi-first model_app\n

Create the service in a custom directory:

openapi-first model_app my-model-service\n

List all available application templates:

openapi-first --list\n

The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.

"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--client-usage-example","title":"Client Usage Example","text":"

The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.

Example client calls for model-based CRUD operations:

from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List items\nresponse = client.list_items()\n\n# Get item by ID\nresponse = client.get_item(\n    path_params={\"item_id\": 1}\n)\n\n# Create item\nresponse = client.create_item(\n    body={\"name\": \"Orange\", \"price\": 0.8}\n)\n\n# Update item\nresponse = client.update_item(\n    path_params={\"item_id\": 1},\n    body={\"name\": \"Green Apple\", \"price\": 0.6},\n)\n\n# Delete item\nresponse = client.delete_item(\n    path_params={\"item_id\": 1}\n)\n

Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Request and response payloads conform to Pydantic models - Invalid or incomplete OpenAPI specs fail at client construction time

"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--non-goals","title":"Non-Goals","text":"

This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage

It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.

This package is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/model_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data","title":"openapi_first.templates.model_app.data","text":"

In-memory data store using Pydantic models.

This module is NOT thread-safe and is intended for demos and scaffolds only. This module provides a minimal, process-local data store for the model-based CRUD example application. It stores and returns domain objects defined using Pydantic models and is intended solely for demonstration and scaffolding purposes.

The implementation intentionally avoids: - persistence - concurrency guarantees - transactional semantics - validation beyond what Pydantic provides

It is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data-functions","title":"Functions","text":""},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item","title":"create_item","text":"
create_item(payload: ItemCreate) -> Item\n

Create a new item in the data store.

A new identifier is assigned automatically. No additional validation is performed beyond Pydantic model validation.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item--parameters","title":"Parameters","text":"

payload : ItemCreate Data required to create a new item.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item--returns","title":"Returns","text":"

Item The newly created item.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item","title":"delete_item","text":"
delete_item(item_id: int) -> None\n

Remove an item from the data store.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to delete.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item--raises","title":"Raises","text":"

KeyError If the item does not exist.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item","title":"get_item","text":"
get_item(item_id: int) -> Item\n

Retrieve a single item by ID.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to retrieve.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--returns","title":"Returns","text":"

Item The requested item.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--raises","title":"Raises","text":"

KeyError If the item does not exist.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.list_items","title":"list_items","text":"
list_items() -> list[Item]\n

Return all items in the data store.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.list_items--returns","title":"Returns","text":"

list[Item] A list of item domain objects.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item","title":"update_item","text":"
update_item(item_id: int, payload: ItemCreate) -> Item\n

Replace an existing item in the data store.

This function performs a full replacement of the stored item. Partial updates are not supported.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to update. payload : ItemCreate New item data.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--returns","title":"Returns","text":"

Item The updated item.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--raises","title":"Raises","text":"

KeyError If the item does not exist.

"},{"location":"openapi_first/templates/model_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/model_app/main/#openapi_first.templates.model_app.main","title":"openapi_first.templates.model_app.main","text":"

Application entry point for an OpenAPI-first model-based CRUD example service.

This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.

All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.

This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.

Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup

This file is intended to be used as the ASGI entry point.

Example

uvicorn main:app

"},{"location":"openapi_first/templates/model_app/main/#openapi_first.templates.model_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/model_app/models/","title":"Models","text":""},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models","title":"openapi_first.templates.model_app.models","text":"

Pydantic domain models for the CRUD example.

This module defines Pydantic models that represent the domain entities used by the service. These models are referenced by the OpenAPI specification for request and response schemas.

The models are declarative and framework-agnostic. They contain no persistence logic, validation beyond type constraints, or business behavior.

This module is not part of the openapi_first library API surface. It exists solely to support the example application template.

"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models-classes","title":"Classes","text":""},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.Item","title":"Item","text":"

Bases: ItemBase

Domain model for a persisted item.

This model represents the full item state returned in responses, including the server-assigned identifier.

"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.ItemBase","title":"ItemBase","text":"

Bases: BaseModel

Base domain model for an item.

Defines fields common to all item representations.

"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.ItemCreate","title":"ItemCreate","text":"

Bases: ItemBase

Domain model for item creation requests.

This model is used for request bodies when creating new items. It intentionally excludes the id field, which is assigned by the service.

"},{"location":"openapi_first/templates/model_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes","title":"openapi_first.templates.model_app.routes","text":"

CRUD route handlers bound via OpenAPI operationId.

This module defines OpenAPI-bound operation handlers for a model-based CRUD service. Functions in this module are bound to HTTP routes exclusively via OpenAPI operationId values.

Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Domain models defined using Pydantic are used for request and response payloads.

No routing decorators, path definitions, or implicit framework behavior appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item","title":"create_item","text":"
create_item(payload: ItemCreate, response: Response)\n

Create a new item.

Implements the OpenAPI operation identified by operationId: create_item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item--parameters","title":"Parameters","text":"

payload : ItemCreate Request body describing the item to create. response : fastapi.Response Response object used to set the HTTP status code.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item--returns","title":"Returns","text":"

Item The newly created item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item","title":"delete_item","text":"
delete_item(item_id: int, response: Response)\n

Delete an existing item.

Implements the OpenAPI operation identified by operationId: delete_item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to delete. response : fastapi.Response Response object used to set the HTTP status code.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--returns","title":"Returns","text":"

None No content.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item","title":"get_item","text":"
get_item(item_id: int)\n

Retrieve a single item by ID.

Implements the OpenAPI operation identified by operationId: get_item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to retrieve.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--returns","title":"Returns","text":"

Item The requested item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.list_items","title":"list_items","text":"
list_items()\n

List all items.

Implements the OpenAPI operation identified by operationId: list_items.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.list_items--returns","title":"Returns","text":"

list[Item] A list of item domain objects.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item","title":"update_item","text":"
update_item(item_id: int, payload: ItemCreate)\n

Update an existing item.

Implements the OpenAPI operation identified by operationId: update_item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to update. payload : ItemCreate New item data.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--returns","title":"Returns","text":"

Item The updated item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/model_app/test_model_app/","title":"Test Model App","text":""},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app","title":"openapi_first.templates.model_app.test_model_app","text":"

End-to-end tests for the OpenAPI-first model CRUD example app.

These tests validate that all CRUD operations behave correctly against the in-memory mock data store using Pydantic models. - OpenAPI specification loading - OperationId-driven route binding on the server - OperationId-driven client invocation - Pydantic model-based request and response handling

All CRUD operations are exercised against an in-memory mock data store backed by Pydantic domain models.

The tests assume: - OpenAPI-first route binding - Pydantic model validation - In-memory storage (no persistence guarantees) - Deterministic behavior in a single process

"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app-classes","title":"Classes","text":""},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app-functions","title":"Functions","text":""},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_create_item","title":"test_create_item","text":"
test_create_item()\n

Creating a new item should return the created entity.

"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_delete_item","title":"test_delete_item","text":"
test_delete_item()\n

Deleting an item should remove it from the store.

"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_get_item","title":"test_get_item","text":"
test_get_item()\n

Existing item should be retrievable by ID.

"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_list_items_initial","title":"test_list_items_initial","text":"
test_list_items_initial()\n

Initial items should be present.

"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_update_item","title":"test_update_item","text":"
test_update_item()\n

Updating an item should replace its values.

"},{"location":"openapi_first/templates/vet_app/","title":"Vet App","text":"
  • Data
  • Main
  • Models
  • Routes
  • Sse
  • Test Vet App
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app","title":"openapi_first.templates.vet_app","text":"

OpenAPI-first Veterinary Clinic application template.

This package contains a complete, runnable example of an OpenAPI-first veterinary clinic management service. It demonstrates all x- extension fields consumed by the react-openapi admin panel renderer.

The application manages five resources:

  • Parents \u2014 pet owners with contact details
  • Vets \u2014 veterinarians with specializations
  • Treatments \u2014 medical procedure catalog
  • Pets \u2014 animals with species, age, weight, and photos
  • Appointments \u2014 scheduled visits linking pets, vets, and treatments

All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification (openapi.yaml). Every operation has an explicit operationId that maps to a Python handler in routes.py.

This file is a copyable template. It is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--openapi-x-extension-fields-demonstrated","title":"OpenAPI x- extension fields demonstrated","text":"

Schema-level extensions (display metadata for resource endpoints):

x-primary-key (REQUIRED) Primary key property name x-display-format (REQUIRED) Human-readable label template x-list-columns (REQUIRED) Columns for the datatable

Property-level extensions (control UI rendering):

x-label (REQUIRED) Human-readable field label x-order (REQUIRED) Field ordering in forms/detail x-description (optional) Helper text below form fields x-hidden (optional) Visibility in form / list / detail x-filterable (optional) Allows column filtering x-sortable (optional) Allows column sorting x-fk (optional) Foreign key \u2014 renders as dropdown x-fk.resource (REQUIRED for FK) Target resource name x-fk.prefetch (optional) Preload all FK options on mount x-ui-type (optional) Custom UI type (e.g. image upload) x-upload-url (optional) Upload endpoint for binary fields

"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"

Create a new vet clinic service using the bundled template:

openapi-first vet_app\n

Create the service in a custom directory:

openapi-first vet_app my-vet-clinic\n
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--client-usage-example","title":"Client Usage Example","text":"
from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List pets with pagination\nresponse = client.list_pets(query_params={\"limit\": 10, \"offset\": 0})\n\n# Create a pet with FK references\nresponse = client.create_pet(\n    body={\"name\": \"Fido\", \"species\": \"dog\", \"parents\": [1, 2]}\n)\n\n# Upload a pet photo\nresponse = client.upload_pet_photo(\n    path_params={\"id\": 1},\n    body={\"file\": open(\"photo.jpg\", \"rb\")},\n)\n
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--non-goals","title":"Non-Goals","text":"

This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage

It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.

This package is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/vet_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/vet_app/data/#openapi_first.templates.vet_app.data","title":"openapi_first.templates.vet_app.data","text":"

In-memory data store for the Veterinary Clinic example.

This module is NOT thread-safe and is intended for demos and scaffolds only.

It provides minimal, process-local data stores for the five veterinary clinic entities. Each store exposes standard CRUD operations backed by a simple dictionary.

This module intentionally avoids: - persistence - concurrency guarantees - transactional semantics - validation beyond what Pydantic provides

This module is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/vet_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/vet_app/main/#openapi_first.templates.vet_app.main","title":"openapi_first.templates.vet_app.main","text":"

Application entry point for an OpenAPI-first Veterinary Clinic service.

This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.

All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.

This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.

Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup

This file is intended to be used as the ASGI entry point.

Example

uvicorn main:app

"},{"location":"openapi_first/templates/vet_app/main/#openapi_first.templates.vet_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/vet_app/models/","title":"Models","text":""},{"location":"openapi_first/templates/vet_app/models/#openapi_first.templates.vet_app.models","title":"openapi_first.templates.vet_app.models","text":""},{"location":"openapi_first/templates/vet_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes","title":"openapi_first.templates.vet_app.routes","text":"

Veterinary Clinic route handlers bound via OpenAPI operationId.

Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Domain models defined using Pydantic are used for request and response payloads.

No routing decorators, path definitions, or implicit framework behavior appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_appointment","title":"create_appointment","text":"
create_appointment(\n    payload: AppointmentCreate, response: Response\n)\n

Create an appointment.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_parent","title":"create_parent","text":"
create_parent(payload: ParentCreate, response: Response)\n

Create a parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_parent--parameters","title":"Parameters","text":"

payload : ParentCreate Parent data excluding the id field.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_parent--returns","title":"Returns","text":"

Parent The newly created parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_pet","title":"create_pet","text":"
create_pet(payload: PetCreate, response: Response)\n

Create a pet.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_treatment","title":"create_treatment","text":"
create_treatment(\n    payload: TreatmentCreate, response: Response\n)\n

Add a treatment (admin only).

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_vet","title":"create_vet","text":"
create_vet(payload: VetCreate, response: Response)\n

Create a vet.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_appointment","title":"delete_appointment","text":"
delete_appointment(id: int, response: Response)\n

Delete an existing appointment.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_parent","title":"delete_parent","text":"
delete_parent(id: int, response: Response)\n

Delete an existing parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_parent--parameters","title":"Parameters","text":"

id : int Identifier of the parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_parent--raises","title":"Raises","text":"

HTTPException 404 if the parent does not exist.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_pet","title":"delete_pet","text":"
delete_pet(id: int, response: Response)\n

Delete an existing pet.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_treatment","title":"delete_treatment","text":"
delete_treatment(id: int, response: Response)\n

Delete an existing treatment.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_vet","title":"delete_vet","text":"
delete_vet(id: int, response: Response)\n

Delete an existing vet.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_appointment","title":"get_appointment","text":"
get_appointment(id: int)\n

Retrieve a single appointment by ID.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent","title":"get_parent","text":"
get_parent(id: int)\n

Retrieve a single parent by ID.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent--parameters","title":"Parameters","text":"

id : int Identifier of the parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent--returns","title":"Returns","text":"

Parent The requested parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent--raises","title":"Raises","text":"

HTTPException 404 if the parent does not exist.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_pet","title":"get_pet","text":"
get_pet(id: int)\n

Retrieve a single pet by ID.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_treatment","title":"get_treatment","text":"
get_treatment(id: int)\n

Retrieve a single treatment by ID.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_vet","title":"get_vet","text":"
get_vet(id: int)\n

Retrieve a single vet by ID.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_appointments","title":"list_appointments","text":"
list_appointments(\n    limit: int = 20,\n    offset: int = 0,\n    date: str = None,\n    vet: int = None,\n    pet: int = None,\n)\n

List appointments (paginated, filterable).

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_parents","title":"list_parents","text":"
list_parents(limit: int = 20, offset: int = 0)\n

List parents (paginated).

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_parents--parameters","title":"Parameters","text":"

limit : int Maximum number of records to return. offset : int Number of records to skip.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_parents--returns","title":"Returns","text":"

dict Paginated response with total and items.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_pets","title":"list_pets","text":"
list_pets(limit: int = 20, offset: int = 0)\n

List pets (paginated).

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_treatments","title":"list_treatments","text":"
list_treatments()\n

List treatments (catalogue).

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_treatments--returns","title":"Returns","text":"

list[Treatment] A list of treatment domain objects.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_vets","title":"list_vets","text":"
list_vets(limit: int = 20, offset: int = 0)\n

List vets (paginated).

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.stream_actions","title":"stream_actions async","text":"
stream_actions(id: int)\n

Stream animal actions via SSE, scoped to a pet's species.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_appointment","title":"update_appointment","text":"
update_appointment(id: int, payload: AppointmentCreate)\n

Update an existing appointment.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent","title":"update_parent","text":"
update_parent(id: int, payload: ParentCreate)\n

Update an existing parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent--parameters","title":"Parameters","text":"

id : int Identifier of the parent. payload : ParentCreate Updated parent data.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent--returns","title":"Returns","text":"

Parent The updated parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent--raises","title":"Raises","text":"

HTTPException 404 if the parent does not exist.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_pet","title":"update_pet","text":"
update_pet(id: int, payload: PetCreate)\n

Update an existing pet.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_treatment","title":"update_treatment","text":"
update_treatment(id: int, payload: TreatmentCreate)\n

Update an existing treatment.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_vet","title":"update_vet","text":"
update_vet(id: int, payload: VetCreate)\n

Update an existing vet.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.upload_pet_photo","title":"upload_pet_photo","text":"
upload_pet_photo(id: int, file: UploadFile)\n

Upload a pet photo.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.upload_pet_photo--parameters","title":"Parameters","text":"

id : int Identifier of the pet. file : UploadFile Image file to upload.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.upload_pet_photo--returns","title":"Returns","text":"

dict A confirmation with the pet ID.

"},{"location":"openapi_first/templates/vet_app/sse/","title":"Sse","text":""},{"location":"openapi_first/templates/vet_app/sse/#openapi_first.templates.vet_app.sse","title":"openapi_first.templates.vet_app.sse","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/","title":"Test Vet App","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app","title":"openapi_first.templates.vet_app.test_vet_app","text":"

End-to-end tests for the OpenAPI-first Veterinary Clinic example app.

These tests validate that all CRUD operations behave correctly against the in-memory mock data store using Pydantic models.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app-classes","title":"Classes","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app-functions","title":"Functions","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_parent","title":"test_create_parent","text":"
test_create_parent()\n

Creating a parent returns 201 with the created entity.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_pet","title":"test_create_pet","text":"
test_create_pet()\n

Creating a pet links FK references.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_treatment","title":"test_create_treatment","text":"
test_create_treatment()\n

Creating a treatment returns 201.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_vet","title":"test_create_vet","text":"
test_create_vet()\n

Creating a vet returns 201.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_delete_parent","title":"test_delete_parent","text":"
test_delete_parent()\n

Delete parent returns 204 and removes the entity.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_full_appointment_lifecycle","title":"test_full_appointment_lifecycle","text":"
test_full_appointment_lifecycle()\n

Create a parent, vet, treatment, pet, then an appointment.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_get_parent","title":"test_get_parent","text":"
test_get_parent()\n

Get parent by ID returns the entity.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_appointments","title":"test_list_appointments","text":"
test_list_appointments()\n

List appointments returns paginated response with filter params.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_parents","title":"test_list_parents","text":"
test_list_parents()\n

List parents returns paginated response.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_treatments","title":"test_list_treatments","text":"
test_list_treatments()\n

List treatments returns an array.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_vets","title":"test_list_vets","text":"
test_list_vets()\n

List vets returns paginated response.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_update_parent","title":"test_update_parent","text":"
test_update_parent()\n

Update parent replaces its values.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_upload_pet_photo","title":"test_upload_pet_photo","text":"
test_upload_pet_photo()\n

Upload pet photo returns 200.

"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"openapi_first","text":"
  • Openapi First
"},{"location":"#openapi_first","title":"openapi_first","text":""},{"location":"#openapi_first--summary","title":"Summary","text":"

FastAPI OpenAPI First \u2014 strict OpenAPI-first application bootstrap for FastAPI.

FastAPI OpenAPI First is a contract-first infrastructure library that enforces OpenAPI as the single source of truth for FastAPI services.

The library removes decorator-driven routing and replaces it with deterministic, spec-driven application assembly. Every HTTP route, method, and operation is defined in OpenAPI first and bound to Python handlers explicitly via operationId.

"},{"location":"#openapi_first--installation","title":"Installation","text":"

Install using pip:

pip install openapi-first\n

Or with Poetry:

poetry add openapi-first\n
"},{"location":"#openapi_first--quick-start","title":"Quick Start","text":"

Minimal OpenAPI-first FastAPI application:

from openapi_first import app\nimport my_service.routes as routes\n\napi = app.OpenAPIFirstApp(\n    openapi_path=\"openapi.yaml\",\n    routes_module=routes,\n    title=\"My Service\",\n    version=\"1.0.0\",\n)\n

OperationId-driven HTTP client:

from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\nresponse = client.get_health()\n
"},{"location":"#openapi_first--architecture","title":"Architecture","text":"

The library is structured around four core responsibilities:

  • loader: Load and validate OpenAPI 3.x specifications (JSON/YAML).
  • binder: Bind OpenAPI operations to FastAPI routes via operationId.
  • app: OpenAPI-first FastAPI application bootstrap.
  • client: OpenAPI-first HTTP client driven by the same specification.
  • errors: Explicit error hierarchy for contract violations.
"},{"location":"#openapi_first--public-api","title":"Public API","text":"

The supported public API consists of the following top-level modules:

  • openapi_first.app
  • openapi_first.binder
  • openapi_first.loader
  • openapi_first.client
  • openapi_first.errors
"},{"location":"#openapi_first--design-guarantees","title":"Design Guarantees","text":"
  • OpenAPI is the single source of truth.
  • No undocumented routes can exist.
  • No OpenAPI operation can exist without a handler or client callable.
  • All contract violations fail at application startup or client creation.
  • No hidden FastAPI magic or implicit behavior.
  • Deterministic, testable application assembly.
"},{"location":"app/","title":"App","text":""},{"location":"app/#openapi_first.app","title":"openapi_first.app","text":""},{"location":"app/#openapi_first.app--summary","title":"Summary","text":"

OpenAPI-first application bootstrap for FastAPI.

This module provides OpenAPIFirstApp, a thin but strict abstraction that enforces OpenAPI as the single source of truth for a FastAPI service.

Notes

Core Principles:

- The OpenAPI specification (JSON or YAML) defines the entire API surface.\n- Every `operationId` in the OpenAPI spec must have a corresponding\n  Python handler function.\n- Handlers are plain Python callables (no FastAPI decorators).\n- FastAPI route registration is derived exclusively from the spec.\n- FastAPI's autogenerated OpenAPI schema is fully overridden.\n

Responsibilities:

- Loads and validates an OpenAPI 3.x specification.\n- Dynamically binds HTTP routes to handler functions using `operationId`.\n- Registers routes with FastAPI at application startup.\n- Ensures runtime behavior matches the OpenAPI contract exactly.\n

Constraints:

- This module intentionally does NOT:\n    - Generate OpenAPI specs.\n    - Generate client code.\n    - Introduce a new framework or lifecycle.\n    - Alter FastAPI dependency injection semantics.\n
"},{"location":"app/#openapi_first.app-classes","title":"Classes","text":""},{"location":"app/#openapi_first.app.OpenAPIFirstApp","title":"OpenAPIFirstApp","text":"
OpenAPIFirstApp(\n    *,\n    openapi_path: str,\n    routes_module: Any,\n    **fastapi_kwargs: Any\n)\n

Bases: FastAPI

FastAPI application enforcing OpenAPI-first design.

Notes

Responsibilities:

- `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n  registration with OpenAPI-driven binding.\n- All routes are derived from the provided OpenAPI specification,\n  and each ``operationId`` is mapped to a Python function in the\n  supplied routes module.\n- Auth dependencies are auto-injected from the spec's\n  ``securitySchemes`` and per-operation ``security`` fields.\n

Guarantees:

- No route can exist without an OpenAPI declaration.\n- No OpenAPI operation can exist without a handler.\n- Swagger UI and ``/openapi.json`` always reflect the provided spec.\n- Handler functions remain framework-agnostic and testable.\n- Auth enforcement is driven entirely by the spec \u2014 no manual\n  middleware or decorators required.\n
Example 
from openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n    openapi_path=\"app/openapi.json\",\n    routes_module=routes,\n    title=\"Example Service\",\n)\n

Initialize the application.

Parameters:

Name Type Description Default openapi_path str

Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract.

required routes_module ModuleType

Python module containing handler functions whose names correspond exactly to OpenAPI operationId values.

required **fastapi_kwargs Any

Additional keyword arguments passed directly to fastapi.FastAPI (e.g., title, version, middleware, lifespan handlers).

{}

Raises:

Type Description OpenAPIFirstError

If the OpenAPI specification is invalid, or if any declared operationId does not have a corresponding handler function.

"},{"location":"app/#openapi_first.app.OpenAPIFirstApp-functions","title":"Functions","text":""},{"location":"app/#openapi_first.app-functions","title":"Functions","text":""},{"location":"binder/","title":"Binder","text":""},{"location":"binder/#openapi_first.binder","title":"openapi_first.binder","text":""},{"location":"binder/#openapi_first.binder--summary","title":"Summary","text":"

OpenAPI-driven route binding for FastAPI.

This module is responsible for translating an OpenAPI 3.x specification into concrete FastAPI routes. It enforces a strict one-to-one mapping between OpenAPI operations and Python handler functions using operationId.

Notes

Core Responsibility:

- Read path + method definitions from an OpenAPI specification.\n- Resolve each `operationId` to a Python callable.\n- Register routes with FastAPI using `APIRoute`.\n- Fail fast when contract violations are detected.\n

Design Constraints:

- All routes MUST be declared in the OpenAPI specification.\n- All OpenAPI operations MUST define an `operationId`.\n- Every `operationId` MUST resolve to a handler function.\n- Handlers are plain Python callables (no decorators required).\n- No implicit route creation or inference is allowed.\n

Constraints:

- This module intentionally does NOT:\n    - Perform request or response validation.\n    - Generate Pydantic models.\n    - Modify FastAPI dependency injection.\n    - Interpret OpenAPI semantics beyond routing metadata.\n
"},{"location":"binder/#openapi_first.binder-classes","title":"Classes","text":""},{"location":"binder/#openapi_first.binder-functions","title":"Functions","text":""},{"location":"binder/#openapi_first.binder.bind_routes","title":"bind_routes","text":"
bind_routes(\n    app: FastAPI,\n    spec: dict[str, Any],\n    routes_module: ModuleType,\n    security_deps: dict[str, list[Any]] | None = None,\n) -> None\n

Bind OpenAPI operations to FastAPI routes.

Parameters:

Name Type Description Default app FastAPI

The FastAPI application instance to which routes will be added.

required spec dict[str, Any]

Parsed OpenAPI 3.x specification dictionary.

required routes_module ModuleType

Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.

required security_deps dict[str, list[Any]] | None

Optional mapping of METHOD:/path \u2192 list[Depends(...)] generated from the spec's securitySchemes and per-operation security fields.

None

Raises:

Type Description MissingOperationHandler

If an operationId is missing from the spec or if no corresponding handler function exists in the routes module.

Notes

Responsibilities:

- Iterates through the OpenAPI specification paths and methods.\n- Resolves each ``operationId`` to a handler function, and registers\n  a corresponding ``APIRoute`` on the FastAPI application.\n- Injects FastAPI ``Depends()`` for each security requirement found\n  on the operation or inherited from the top-level ``security`` field.\n

Guarantees:

- Route registration is deterministic and spec-driven. No route\n  decorators are required or supported. Handler resolution errors\n  surface at application startup.\n
"},{"location":"cli/","title":"Cli","text":""},{"location":"cli/#openapi_first.cli","title":"openapi_first.cli","text":""},{"location":"cli/#openapi_first.cli--summary","title":"Summary","text":"

Command-line interface for FastAPI OpenAPI-first scaffolding utilities.

This CLI bootstraps OpenAPI-first FastAPI applications from versioned, bundled templates packaged with the library.

"},{"location":"cli/#openapi_first.cli-functions","title":"Functions","text":""},{"location":"cli/#openapi_first.cli.available_templates","title":"available_templates","text":"
available_templates() -> list[str]\n

Return a list of available application templates.

Returns:

Type Description list[str]

list[str]: Sorted list of template names found in the internal templates directory.

"},{"location":"cli/#openapi_first.cli.copy_template","title":"copy_template","text":"
copy_template(template: str, target_dir: Path) -> None\n

Copy a bundled OpenAPI-first application template into a directory.

Parameters:

Name Type Description Default template str

Name of the template to copy.

required target_dir Path

Filesystem path where the template should be copied.

required

Raises:

Type Description FileNotFoundError

If the requested template does not exist.

"},{"location":"client/","title":"Client","text":""},{"location":"client/#openapi_first.client","title":"openapi_first.client","text":""},{"location":"client/#openapi_first.client--summary","title":"Summary","text":"

OpenAPI-first HTTP client for contract-driven services.

This module provides OpenAPIClient, a thin, strict HTTP client that derives all callable operations directly from an OpenAPI 3.x specification.

It is the client counterpart to OpenAPIFirstApp.

Notes

Core Principles:

- The OpenAPI specification is the single source of truth\n- Each operationId becomes a callable Python method\n- No implicit schema mutation or inference\n- No code generation step\n- Minimal abstraction over httpx\n

Responsibilities:

- Parses an OpenAPI 3.x specification\n- Dynamically creates one callable per operationId\n- Enforces presence of servers, paths, and operationId\n- Formats path parameters safely\n- Handles JSON request bodies explicitly\n- Returns raw `httpx.Response` objects\n

Constraints:

- This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.\n
"},{"location":"client/#openapi_first.client-classes","title":"Classes","text":""},{"location":"client/#openapi_first.client.OpenAPIClient","title":"OpenAPIClient","text":"
OpenAPIClient(\n    spec: dict[str, Any],\n    base_url: str | None = None,\n    client: httpx.Client | None = None,\n)\n

OpenAPI-first HTTP client (httpx-based).

Notes

Responsibilities:

- This client derives all callable methods directly from an\n  OpenAPI 3.x specification. Each `operationId` becomes a method\n  on the client instance.\n

Guarantees:

- One callable per `operationId`.\n- Explicit parameters (path, query, headers, body).\n- No implicit schema inference or mutation.\n- Returns raw `httpx.Response` objects.\n- No response validation or deserialization.\n
Example 
from openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n    spec=spec,\n    base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n    path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n

Initialize the OpenAPI client.

Parameters:

Name Type Description Default spec dict[str, Any]

Parsed OpenAPI 3.x specification.

required base_url str | None

Base URL of the target service. If omitted, the first entry in the OpenAPI servers list is used.

None client Client | None

Optional preconfigured httpx client instance.

None

Raises:

Type Description OpenAPIClientError

If no servers are defined, spec has no paths, operationIds are missing/duplicate, or required parameters are missing.

"},{"location":"client/#openapi_first.client.OpenAPIClient-functions","title":"Functions","text":""},{"location":"client/#openapi_first.client.OpenAPIClientError","title":"OpenAPIClientError","text":"

Bases: OpenAPIFirstError

Raised when an OpenAPI client operation fails.

"},{"location":"codegen/","title":"Codegen","text":""},{"location":"codegen/#openapi_first.codegen","title":"openapi_first.codegen","text":""},{"location":"codegen/#openapi_first.codegen--summary","title":"Summary","text":"

Core logic for generating Python source code from OpenAPI specifications.

This module provides reusable utilities for code generation, specifically generating Pydantic models and route handler stubs from OpenAPI 3.x schema definitions.

"},{"location":"codegen/#openapi_first.codegen-functions","title":"Functions","text":""},{"location":"codegen/#openapi_first.codegen.generate_models","title":"generate_models","text":"
generate_models(\n    spec_path: Path,\n    output_path: Path,\n    pydantic_version: int = 2,\n) -> None\n

Generate Pydantic models from an OpenAPI specification.

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI specification file (YAML or JSON).

required output_path Path

Path where the generated Python code should be written.

required pydantic_version int

The Pydantic version to target (1 or 2). Defaults to 2.

2 Notes

Reusability: This function is designed to be used by the CLI and can be exposed as an MCP tool without modification.

"},{"location":"codegen/#openapi_first.codegen.generate_routes","title":"generate_routes","text":"
generate_routes(\n    spec_path: Path,\n    output_dir: Path,\n    *,\n    use_models: bool = False,\n    models_module: str = \"models\"\n) -> list[Path]\n

Generate route handler stubs from an OpenAPI specification.

Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI specification file (YAML or JSON).

required output_dir Path

Directory where the generated route files are written. Created automatically if it does not exist.

required use_models bool

If True, import Pydantic models from models_module for request-body schemas referenced via $ref.

False models_module str

Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").

'models'

Returns:

Type Description list[Path]

list[Path]: Absolute paths of every generated route file.

Raises:

Type Description OpenAPISpecLoadError

If the spec cannot be loaded or validated.

ValueError

If any operation is missing operationId.

"},{"location":"codegen_routes/","title":"Codegen Routes","text":""},{"location":"codegen_routes/#openapi_first.codegen_routes","title":"openapi_first.codegen_routes","text":""},{"location":"codegen_routes/#openapi_first.codegen_routes--summary","title":"Summary","text":"

Route handler code generation from OpenAPI specifications.

This module generates Python route handler stubs from an OpenAPI 3.x specification. Each resource (derived from the first path segment) gets its own file under the output directory. Every OpenAPI operation must define an operationId, which becomes the handler function name.

Notes

Design constraints:

- ``operationId`` is required on every operation (matching\n  ``binder.bind_routes``).\n- Handlers are stubs raising ``NotImplementedError``.\n- Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n  parent resource (``pets``).\n- Parameter types and defaults are inferred from the spec.\n- ``response: Response`` is injected for non-200 success codes.\n
"},{"location":"codegen_routes/#openapi_first.codegen_routes-functions","title":"Functions","text":""},{"location":"codegen_routes/#openapi_first.codegen_routes.generate_routes","title":"generate_routes","text":"
generate_routes(\n    spec_path: Path,\n    output_dir: Path,\n    *,\n    use_models: bool = False,\n    models_module: str = \"models\"\n) -> list[Path]\n

Generate route handler stubs from an OpenAPI specification.

Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI specification file (YAML or JSON).

required output_dir Path

Directory where the generated route files are written. Created automatically if it does not exist.

required use_models bool

If True, import Pydantic models from models_module for request-body schemas referenced via $ref.

False models_module str

Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").

'models'

Returns:

Type Description list[Path]

list[Path]: Absolute paths of every generated route file.

Raises:

Type Description OpenAPISpecLoadError

If the spec cannot be loaded or validated.

ValueError

If any operation is missing operationId.

"},{"location":"errors/","title":"Errors","text":""},{"location":"errors/#openapi_first.errors","title":"openapi_first.errors","text":""},{"location":"errors/#openapi_first.errors--summary","title":"Summary","text":"

Exceptions for OpenAPI-first FastAPI applications.

This module defines a small hierarchy of explicit, intention-revealing exceptions used to signal contract violations between an OpenAPI specification and its Python implementation.

Notes

Design Principles:

- Errors represent programmer mistakes, not runtime conditions.\n- All errors are raised during application startup.\n- Messages are actionable and suitable for CI/CD output.\n- Exceptions are explicit rather than reused from generic built-ins.\n

These errors should normally cause immediate application failure.

"},{"location":"errors/#openapi_first.errors-classes","title":"Classes","text":""},{"location":"errors/#openapi_first.errors.MissingOperationHandler","title":"MissingOperationHandler","text":"
MissingOperationHandler(\n    *,\n    path: str,\n    method: str,\n    operation_id: str | None = None\n)\n

Bases: OpenAPIFirstError

Raised when an OpenAPI operation cannot be resolved to a handler.

Notes

Scenarios:

- An OpenAPI operation does not define an `operationId`.\n- An `operationId` is defined but no matching function exists in\n  the provided routes module.\n

Guarantees:

- This represents a violation of the OpenAPI-first contract and\n  indicates that the specification and implementation are out of\n  sync.\n

Initialize the error.

Parameters:

Name Type Description Default path str

The HTTP path declared in the OpenAPI specification.

required method str

The HTTP method (as declared in the OpenAPI spec).

required operation_id str | None

The operationId declared in the OpenAPI spec, if present.

None"},{"location":"errors/#openapi_first.errors.MissingOperationHandler-functions","title":"Functions","text":""},{"location":"errors/#openapi_first.errors.OpenAPIFirstError","title":"OpenAPIFirstError","text":"

Bases: Exception

Base exception for all OpenAPI-first enforcement errors.

Notes

Responsibilities:

- This exception exists to allow callers, test suites, and CI\n  pipelines to catch and distinguish OpenAPI contract violations\n  from unrelated runtime errors.\n- All exceptions raised by the OpenAPI-first core should inherit\n  from this type.\n
"},{"location":"loader/","title":"Loader","text":""},{"location":"loader/#openapi_first.loader","title":"openapi_first.loader","text":""},{"location":"loader/#openapi_first.loader--summary","title":"Summary","text":"

OpenAPI specification loading and validation utilities.

This module is responsible for loading an OpenAPI 3.x specification from disk and validating it before it is used by the application.

It enforces the principle that an invalid or malformed OpenAPI document must never reach the routing or runtime layers.

Notes

Design Principles:

- OpenAPI is treated as an authoritative contract.\n- Invalid specifications fail fast at application startup.\n- Supported formats are JSON and YAML.\n- Validation errors are surfaced clearly and early.\n

Constraints:

- This module intentionally does NOT:\n    - Modify the OpenAPI document.\n    - Infer missing fields.\n    - Generate models or code.\n    - Perform request/response validation at runtime.\n
"},{"location":"loader/#openapi_first.loader-classes","title":"Classes","text":""},{"location":"loader/#openapi_first.loader.OpenAPISpecLoadError","title":"OpenAPISpecLoadError","text":"

Bases: OpenAPIFirstError

Raised when an OpenAPI specification cannot be loaded or validated.

Notes

Guarantees:

- This error indicates that the OpenAPI document is unreadable,\n  malformed, or violates the OpenAPI 3.x specification.\n
"},{"location":"loader/#openapi_first.loader-functions","title":"Functions","text":""},{"location":"loader/#openapi_first.loader.load_openapi","title":"load_openapi","text":"
load_openapi(path: str | Path) -> dict[str, Any]\n

Load and validate an OpenAPI 3.x specification from disk.

Parameters:

Name Type Description Default path str | Path

Filesystem path to an OpenAPI specification file. Supported extensions: .json, .yaml, .yml.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Parsed and validated OpenAPI specification.

Raises:

Type Description OpenAPISpecLoadError

If the file does not exist, cannot be parsed, or fails OpenAPI schema validation.

Notes

Guarantees:

- The specification is parsed based on file extension and validated\n  using a strict OpenAPI schema validator.\n- Any error results in an immediate exception, preventing\n  application startup.\n
"},{"location":"security/","title":"Security","text":""},{"location":"security/#openapi_first.security","title":"openapi_first.security","text":""},{"location":"security/#openapi_first.security--summary","title":"Summary","text":"

OpenAPI security scheme parsing and auto-generated auth dependencies.

This module reads securitySchemes and per-operation security from an OpenAPI spec, resolves {ENV_VAR} placeholders in x- extension fields, and generates FastAPI dependencies for token validation (e.g., Bearer JWT introspection).

"},{"location":"security/#openapi_first.security-functions","title":"Functions","text":""},{"location":"security/#openapi_first.security.make_security_dependencies","title":"make_security_dependencies","text":"
make_security_dependencies(\n    spec: dict[str, Any],\n    security_schemes: dict[str, dict[str, Any]],\n) -> dict[str, list[Any]]\n

Build a mapping of METHOD:/path \u2192 list of Depends(...).

The effective security for each operation is resolved by:

  1. Using the operation-level security field if present.
  2. Falling back to the top-level security field.
  3. An empty list means no auth required for that operation.
"},{"location":"security/#openapi_first.security.parse_security_schemes","title":"parse_security_schemes","text":"
parse_security_schemes(\n    spec: dict[str, Any],\n) -> dict[str, dict[str, Any]]\n

Extract and resolve environment variables in security schemes.

"},{"location":"openapi_first/","title":"Openapi First","text":"
  • App
  • Binder
  • Cli
  • Client
  • Codegen
  • Codegen Routes
  • Errors
  • Loader
  • Security
  • Templates
"},{"location":"openapi_first/#openapi_first","title":"openapi_first","text":""},{"location":"openapi_first/#openapi_first--summary","title":"Summary","text":"

FastAPI OpenAPI First \u2014 strict OpenAPI-first application bootstrap for FastAPI.

FastAPI OpenAPI First is a contract-first infrastructure library that enforces OpenAPI as the single source of truth for FastAPI services.

The library removes decorator-driven routing and replaces it with deterministic, spec-driven application assembly. Every HTTP route, method, and operation is defined in OpenAPI first and bound to Python handlers explicitly via operationId.

"},{"location":"openapi_first/#openapi_first--installation","title":"Installation","text":"

Install using pip:

pip install openapi-first\n

Or with Poetry:

poetry add openapi-first\n
"},{"location":"openapi_first/#openapi_first--quick-start","title":"Quick Start","text":"

Minimal OpenAPI-first FastAPI application:

from openapi_first import app\nimport my_service.routes as routes\n\napi = app.OpenAPIFirstApp(\n    openapi_path=\"openapi.yaml\",\n    routes_module=routes,\n    title=\"My Service\",\n    version=\"1.0.0\",\n)\n

OperationId-driven HTTP client:

from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\nresponse = client.get_health()\n
"},{"location":"openapi_first/#openapi_first--architecture","title":"Architecture","text":"

The library is structured around four core responsibilities:

  • loader: Load and validate OpenAPI 3.x specifications (JSON/YAML).
  • binder: Bind OpenAPI operations to FastAPI routes via operationId.
  • app: OpenAPI-first FastAPI application bootstrap.
  • client: OpenAPI-first HTTP client driven by the same specification.
  • errors: Explicit error hierarchy for contract violations.
"},{"location":"openapi_first/#openapi_first--public-api","title":"Public API","text":"

The supported public API consists of the following top-level modules:

  • openapi_first.app
  • openapi_first.binder
  • openapi_first.loader
  • openapi_first.client
  • openapi_first.errors
"},{"location":"openapi_first/#openapi_first--design-guarantees","title":"Design Guarantees","text":"
  • OpenAPI is the single source of truth.
  • No undocumented routes can exist.
  • No OpenAPI operation can exist without a handler or client callable.
  • All contract violations fail at application startup or client creation.
  • No hidden FastAPI magic or implicit behavior.
  • Deterministic, testable application assembly.
"},{"location":"openapi_first/app/","title":"App","text":""},{"location":"openapi_first/app/#openapi_first.app","title":"openapi_first.app","text":""},{"location":"openapi_first/app/#openapi_first.app--summary","title":"Summary","text":"

OpenAPI-first application bootstrap for FastAPI.

This module provides OpenAPIFirstApp, a thin but strict abstraction that enforces OpenAPI as the single source of truth for a FastAPI service.

Notes

Core Principles:

- The OpenAPI specification (JSON or YAML) defines the entire API surface.\n- Every `operationId` in the OpenAPI spec must have a corresponding\n  Python handler function.\n- Handlers are plain Python callables (no FastAPI decorators).\n- FastAPI route registration is derived exclusively from the spec.\n- FastAPI's autogenerated OpenAPI schema is fully overridden.\n

Responsibilities:

- Loads and validates an OpenAPI 3.x specification.\n- Dynamically binds HTTP routes to handler functions using `operationId`.\n- Registers routes with FastAPI at application startup.\n- Ensures runtime behavior matches the OpenAPI contract exactly.\n

Constraints:

- This module intentionally does NOT:\n    - Generate OpenAPI specs.\n    - Generate client code.\n    - Introduce a new framework or lifecycle.\n    - Alter FastAPI dependency injection semantics.\n
"},{"location":"openapi_first/app/#openapi_first.app-classes","title":"Classes","text":""},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp","title":"OpenAPIFirstApp","text":"
OpenAPIFirstApp(\n    *,\n    openapi_path: str,\n    routes_module: Any,\n    **fastapi_kwargs: Any\n)\n

Bases: FastAPI

FastAPI application enforcing OpenAPI-first design.

Notes

Responsibilities:

- `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n  registration with OpenAPI-driven binding.\n- All routes are derived from the provided OpenAPI specification,\n  and each ``operationId`` is mapped to a Python function in the\n  supplied routes module.\n- Auth dependencies are auto-injected from the spec's\n  ``securitySchemes`` and per-operation ``security`` fields.\n

Guarantees:

- No route can exist without an OpenAPI declaration.\n- No OpenAPI operation can exist without a handler.\n- Swagger UI and ``/openapi.json`` always reflect the provided spec.\n- Handler functions remain framework-agnostic and testable.\n- Auth enforcement is driven entirely by the spec \u2014 no manual\n  middleware or decorators required.\n
Example 
from openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n    openapi_path=\"app/openapi.json\",\n    routes_module=routes,\n    title=\"Example Service\",\n)\n

Initialize the application.

Parameters:

Name Type Description Default openapi_path str

Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract.

required routes_module ModuleType

Python module containing handler functions whose names correspond exactly to OpenAPI operationId values.

required **fastapi_kwargs Any

Additional keyword arguments passed directly to fastapi.FastAPI (e.g., title, version, middleware, lifespan handlers).

{}

Raises:

Type Description OpenAPIFirstError

If the OpenAPI specification is invalid, or if any declared operationId does not have a corresponding handler function.

"},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp-functions","title":"Functions","text":""},{"location":"openapi_first/app/#openapi_first.app-functions","title":"Functions","text":""},{"location":"openapi_first/binder/","title":"Binder","text":""},{"location":"openapi_first/binder/#openapi_first.binder","title":"openapi_first.binder","text":""},{"location":"openapi_first/binder/#openapi_first.binder--summary","title":"Summary","text":"

OpenAPI-driven route binding for FastAPI.

This module is responsible for translating an OpenAPI 3.x specification into concrete FastAPI routes. It enforces a strict one-to-one mapping between OpenAPI operations and Python handler functions using operationId.

Notes

Core Responsibility:

- Read path + method definitions from an OpenAPI specification.\n- Resolve each `operationId` to a Python callable.\n- Register routes with FastAPI using `APIRoute`.\n- Fail fast when contract violations are detected.\n

Design Constraints:

- All routes MUST be declared in the OpenAPI specification.\n- All OpenAPI operations MUST define an `operationId`.\n- Every `operationId` MUST resolve to a handler function.\n- Handlers are plain Python callables (no decorators required).\n- No implicit route creation or inference is allowed.\n

Constraints:

- This module intentionally does NOT:\n    - Perform request or response validation.\n    - Generate Pydantic models.\n    - Modify FastAPI dependency injection.\n    - Interpret OpenAPI semantics beyond routing metadata.\n
"},{"location":"openapi_first/binder/#openapi_first.binder-classes","title":"Classes","text":""},{"location":"openapi_first/binder/#openapi_first.binder-functions","title":"Functions","text":""},{"location":"openapi_first/binder/#openapi_first.binder.bind_routes","title":"bind_routes","text":"
bind_routes(\n    app: FastAPI,\n    spec: dict[str, Any],\n    routes_module: ModuleType,\n    security_deps: dict[str, list[Any]] | None = None,\n) -> None\n

Bind OpenAPI operations to FastAPI routes.

Parameters:

Name Type Description Default app FastAPI

The FastAPI application instance to which routes will be added.

required spec dict[str, Any]

Parsed OpenAPI 3.x specification dictionary.

required routes_module ModuleType

Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.

required security_deps dict[str, list[Any]] | None

Optional mapping of METHOD:/path \u2192 list[Depends(...)] generated from the spec's securitySchemes and per-operation security fields.

None

Raises:

Type Description MissingOperationHandler

If an operationId is missing from the spec or if no corresponding handler function exists in the routes module.

Notes

Responsibilities:

- Iterates through the OpenAPI specification paths and methods.\n- Resolves each ``operationId`` to a handler function, and registers\n  a corresponding ``APIRoute`` on the FastAPI application.\n- Injects FastAPI ``Depends()`` for each security requirement found\n  on the operation or inherited from the top-level ``security`` field.\n

Guarantees:

- Route registration is deterministic and spec-driven. No route\n  decorators are required or supported. Handler resolution errors\n  surface at application startup.\n
"},{"location":"openapi_first/cli/","title":"Cli","text":""},{"location":"openapi_first/cli/#openapi_first.cli","title":"openapi_first.cli","text":""},{"location":"openapi_first/cli/#openapi_first.cli--summary","title":"Summary","text":"

Command-line interface for FastAPI OpenAPI-first scaffolding utilities.

This CLI bootstraps OpenAPI-first FastAPI applications from versioned, bundled templates packaged with the library.

"},{"location":"openapi_first/cli/#openapi_first.cli-functions","title":"Functions","text":""},{"location":"openapi_first/cli/#openapi_first.cli.available_templates","title":"available_templates","text":"
available_templates() -> list[str]\n

Return a list of available application templates.

Returns:

Type Description list[str]

list[str]: Sorted list of template names found in the internal templates directory.

"},{"location":"openapi_first/cli/#openapi_first.cli.copy_template","title":"copy_template","text":"
copy_template(template: str, target_dir: Path) -> None\n

Copy a bundled OpenAPI-first application template into a directory.

Parameters:

Name Type Description Default template str

Name of the template to copy.

required target_dir Path

Filesystem path where the template should be copied.

required

Raises:

Type Description FileNotFoundError

If the requested template does not exist.

"},{"location":"openapi_first/client/","title":"Client","text":""},{"location":"openapi_first/client/#openapi_first.client","title":"openapi_first.client","text":""},{"location":"openapi_first/client/#openapi_first.client--summary","title":"Summary","text":"

OpenAPI-first HTTP client for contract-driven services.

This module provides OpenAPIClient, a thin, strict HTTP client that derives all callable operations directly from an OpenAPI 3.x specification.

It is the client counterpart to OpenAPIFirstApp.

Notes

Core Principles:

- The OpenAPI specification is the single source of truth\n- Each operationId becomes a callable Python method\n- No implicit schema mutation or inference\n- No code generation step\n- Minimal abstraction over httpx\n

Responsibilities:

- Parses an OpenAPI 3.x specification\n- Dynamically creates one callable per operationId\n- Enforces presence of servers, paths, and operationId\n- Formats path parameters safely\n- Handles JSON request bodies explicitly\n- Returns raw `httpx.Response` objects\n

Constraints:

- This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.\n
"},{"location":"openapi_first/client/#openapi_first.client-classes","title":"Classes","text":""},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClient","title":"OpenAPIClient","text":"
OpenAPIClient(\n    spec: dict[str, Any],\n    base_url: str | None = None,\n    client: httpx.Client | None = None,\n)\n

OpenAPI-first HTTP client (httpx-based).

Notes

Responsibilities:

- This client derives all callable methods directly from an\n  OpenAPI 3.x specification. Each `operationId` becomes a method\n  on the client instance.\n

Guarantees:

- One callable per `operationId`.\n- Explicit parameters (path, query, headers, body).\n- No implicit schema inference or mutation.\n- Returns raw `httpx.Response` objects.\n- No response validation or deserialization.\n
Example 
from openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n    spec=spec,\n    base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n    path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n

Initialize the OpenAPI client.

Parameters:

Name Type Description Default spec dict[str, Any]

Parsed OpenAPI 3.x specification.

required base_url str | None

Base URL of the target service. If omitted, the first entry in the OpenAPI servers list is used.

None client Client | None

Optional preconfigured httpx client instance.

None

Raises:

Type Description OpenAPIClientError

If no servers are defined, spec has no paths, operationIds are missing/duplicate, or required parameters are missing.

"},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClient-functions","title":"Functions","text":""},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClientError","title":"OpenAPIClientError","text":"

Bases: OpenAPIFirstError

Raised when an OpenAPI client operation fails.

"},{"location":"openapi_first/codegen/","title":"Codegen","text":""},{"location":"openapi_first/codegen/#openapi_first.codegen","title":"openapi_first.codegen","text":""},{"location":"openapi_first/codegen/#openapi_first.codegen--summary","title":"Summary","text":"

Core logic for generating Python source code from OpenAPI specifications.

This module provides reusable utilities for code generation, specifically generating Pydantic models and route handler stubs from OpenAPI 3.x schema definitions.

"},{"location":"openapi_first/codegen/#openapi_first.codegen-functions","title":"Functions","text":""},{"location":"openapi_first/codegen/#openapi_first.codegen.generate_models","title":"generate_models","text":"
generate_models(\n    spec_path: Path,\n    output_path: Path,\n    pydantic_version: int = 2,\n) -> None\n

Generate Pydantic models from an OpenAPI specification.

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI specification file (YAML or JSON).

required output_path Path

Path where the generated Python code should be written.

required pydantic_version int

The Pydantic version to target (1 or 2). Defaults to 2.

2 Notes

Reusability: This function is designed to be used by the CLI and can be exposed as an MCP tool without modification.

"},{"location":"openapi_first/codegen/#openapi_first.codegen.generate_routes","title":"generate_routes","text":"
generate_routes(\n    spec_path: Path,\n    output_dir: Path,\n    *,\n    use_models: bool = False,\n    models_module: str = \"models\"\n) -> list[Path]\n

Generate route handler stubs from an OpenAPI specification.

Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI specification file (YAML or JSON).

required output_dir Path

Directory where the generated route files are written. Created automatically if it does not exist.

required use_models bool

If True, import Pydantic models from models_module for request-body schemas referenced via $ref.

False models_module str

Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").

'models'

Returns:

Type Description list[Path]

list[Path]: Absolute paths of every generated route file.

Raises:

Type Description OpenAPISpecLoadError

If the spec cannot be loaded or validated.

ValueError

If any operation is missing operationId.

"},{"location":"openapi_first/codegen_routes/","title":"Codegen Routes","text":""},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes","title":"openapi_first.codegen_routes","text":""},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes--summary","title":"Summary","text":"

Route handler code generation from OpenAPI specifications.

This module generates Python route handler stubs from an OpenAPI 3.x specification. Each resource (derived from the first path segment) gets its own file under the output directory. Every OpenAPI operation must define an operationId, which becomes the handler function name.

Notes

Design constraints:

- ``operationId`` is required on every operation (matching\n  ``binder.bind_routes``).\n- Handlers are stubs raising ``NotImplementedError``.\n- Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n  parent resource (``pets``).\n- Parameter types and defaults are inferred from the spec.\n- ``response: Response`` is injected for non-200 success codes.\n
"},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes-functions","title":"Functions","text":""},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes.generate_routes","title":"generate_routes","text":"
generate_routes(\n    spec_path: Path,\n    output_dir: Path,\n    *,\n    use_models: bool = False,\n    models_module: str = \"models\"\n) -> list[Path]\n

Generate route handler stubs from an OpenAPI specification.

Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).

Parameters:

Name Type Description Default spec_path Path

Path to the OpenAPI specification file (YAML or JSON).

required output_dir Path

Directory where the generated route files are written. Created automatically if it does not exist.

required use_models bool

If True, import Pydantic models from models_module for request-body schemas referenced via $ref.

False models_module str

Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").

'models'

Returns:

Type Description list[Path]

list[Path]: Absolute paths of every generated route file.

Raises:

Type Description OpenAPISpecLoadError

If the spec cannot be loaded or validated.

ValueError

If any operation is missing operationId.

"},{"location":"openapi_first/errors/","title":"Errors","text":""},{"location":"openapi_first/errors/#openapi_first.errors","title":"openapi_first.errors","text":""},{"location":"openapi_first/errors/#openapi_first.errors--summary","title":"Summary","text":"

Exceptions for OpenAPI-first FastAPI applications.

This module defines a small hierarchy of explicit, intention-revealing exceptions used to signal contract violations between an OpenAPI specification and its Python implementation.

Notes

Design Principles:

- Errors represent programmer mistakes, not runtime conditions.\n- All errors are raised during application startup.\n- Messages are actionable and suitable for CI/CD output.\n- Exceptions are explicit rather than reused from generic built-ins.\n

These errors should normally cause immediate application failure.

"},{"location":"openapi_first/errors/#openapi_first.errors-classes","title":"Classes","text":""},{"location":"openapi_first/errors/#openapi_first.errors.MissingOperationHandler","title":"MissingOperationHandler","text":"
MissingOperationHandler(\n    *,\n    path: str,\n    method: str,\n    operation_id: str | None = None\n)\n

Bases: OpenAPIFirstError

Raised when an OpenAPI operation cannot be resolved to a handler.

Notes

Scenarios:

- An OpenAPI operation does not define an `operationId`.\n- An `operationId` is defined but no matching function exists in\n  the provided routes module.\n

Guarantees:

- This represents a violation of the OpenAPI-first contract and\n  indicates that the specification and implementation are out of\n  sync.\n

Initialize the error.

Parameters:

Name Type Description Default path str

The HTTP path declared in the OpenAPI specification.

required method str

The HTTP method (as declared in the OpenAPI spec).

required operation_id str | None

The operationId declared in the OpenAPI spec, if present.

None"},{"location":"openapi_first/errors/#openapi_first.errors.MissingOperationHandler-functions","title":"Functions","text":""},{"location":"openapi_first/errors/#openapi_first.errors.OpenAPIFirstError","title":"OpenAPIFirstError","text":"

Bases: Exception

Base exception for all OpenAPI-first enforcement errors.

Notes

Responsibilities:

- This exception exists to allow callers, test suites, and CI\n  pipelines to catch and distinguish OpenAPI contract violations\n  from unrelated runtime errors.\n- All exceptions raised by the OpenAPI-first core should inherit\n  from this type.\n
"},{"location":"openapi_first/loader/","title":"Loader","text":""},{"location":"openapi_first/loader/#openapi_first.loader","title":"openapi_first.loader","text":""},{"location":"openapi_first/loader/#openapi_first.loader--summary","title":"Summary","text":"

OpenAPI specification loading and validation utilities.

This module is responsible for loading an OpenAPI 3.x specification from disk and validating it before it is used by the application.

It enforces the principle that an invalid or malformed OpenAPI document must never reach the routing or runtime layers.

Notes

Design Principles:

- OpenAPI is treated as an authoritative contract.\n- Invalid specifications fail fast at application startup.\n- Supported formats are JSON and YAML.\n- Validation errors are surfaced clearly and early.\n

Constraints:

- This module intentionally does NOT:\n    - Modify the OpenAPI document.\n    - Infer missing fields.\n    - Generate models or code.\n    - Perform request/response validation at runtime.\n
"},{"location":"openapi_first/loader/#openapi_first.loader-classes","title":"Classes","text":""},{"location":"openapi_first/loader/#openapi_first.loader.OpenAPISpecLoadError","title":"OpenAPISpecLoadError","text":"

Bases: OpenAPIFirstError

Raised when an OpenAPI specification cannot be loaded or validated.

Notes

Guarantees:

- This error indicates that the OpenAPI document is unreadable,\n  malformed, or violates the OpenAPI 3.x specification.\n
"},{"location":"openapi_first/loader/#openapi_first.loader-functions","title":"Functions","text":""},{"location":"openapi_first/loader/#openapi_first.loader.load_openapi","title":"load_openapi","text":"
load_openapi(path: str | Path) -> dict[str, Any]\n

Load and validate an OpenAPI 3.x specification from disk.

Parameters:

Name Type Description Default path str | Path

Filesystem path to an OpenAPI specification file. Supported extensions: .json, .yaml, .yml.

required

Returns:

Type Description dict[str, Any]

dict[str, Any]: Parsed and validated OpenAPI specification.

Raises:

Type Description OpenAPISpecLoadError

If the file does not exist, cannot be parsed, or fails OpenAPI schema validation.

Notes

Guarantees:

- The specification is parsed based on file extension and validated\n  using a strict OpenAPI schema validator.\n- Any error results in an immediate exception, preventing\n  application startup.\n
"},{"location":"openapi_first/security/","title":"Security","text":""},{"location":"openapi_first/security/#openapi_first.security","title":"openapi_first.security","text":""},{"location":"openapi_first/security/#openapi_first.security--summary","title":"Summary","text":"

OpenAPI security scheme parsing and auto-generated auth dependencies.

This module reads securitySchemes and per-operation security from an OpenAPI spec, resolves {ENV_VAR} placeholders in x- extension fields, and generates FastAPI dependencies for token validation (e.g., Bearer JWT introspection).

"},{"location":"openapi_first/security/#openapi_first.security-functions","title":"Functions","text":""},{"location":"openapi_first/security/#openapi_first.security.make_security_dependencies","title":"make_security_dependencies","text":"
make_security_dependencies(\n    spec: dict[str, Any],\n    security_schemes: dict[str, dict[str, Any]],\n) -> dict[str, list[Any]]\n

Build a mapping of METHOD:/path \u2192 list of Depends(...).

The effective security for each operation is resolved by:

  1. Using the operation-level security field if present.
  2. Falling back to the top-level security field.
  3. An empty list means no auth required for that operation.
"},{"location":"openapi_first/security/#openapi_first.security.parse_security_schemes","title":"parse_security_schemes","text":"
parse_security_schemes(\n    spec: dict[str, Any],\n) -> dict[str, dict[str, Any]]\n

Extract and resolve environment variables in security schemes.

"},{"location":"openapi_first/templates/","title":"Templates","text":"
  • Crud App
  • Health App
  • Model App
  • Vet App
"},{"location":"openapi_first/templates/#openapi_first.templates","title":"openapi_first.templates","text":"

Application templates for FastAPI OpenAPI First.

This package contains example and scaffolding templates intended to be copied into user projects via the openapi-first CLI.

Templates in this package are: - Reference implementations of OpenAPI-first services - Not part of the openapi_first public or internal API - Not intended to be imported as runtime dependencies

The presence of this file exists solely to: - Mark the directory as an explicit Python package - Enable deterministic tooling behavior (documentation, packaging) - Avoid accidental traversal of non-package directories

No code in this package should be imported by library consumers.

"},{"location":"openapi_first/templates/crud_app/","title":"Crud App","text":"
  • Data
  • Main
  • Routes
  • Test Crud App
"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app","title":"openapi_first.templates.crud_app","text":"

OpenAPI-first CRUD application template.

This package contains a complete, minimal example of an OpenAPI-first CRUD service built using the openapi_first library.

The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace implementing CRUD operations (routes) - an in-memory mock data store (data)

All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification and enforced at application startup. No decorator-driven routing or implicit framework behavior is used.

This template demonstrates: - operationId-driven server-side route binding - explicit HTTP status code control in handlers - operationId-driven client usage against the same OpenAPI contract - end-to-end validation using in-memory data and tests

"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"

Create a new CRUD example service using the bundled template:

openapi-first crud_app\n

Create the service in a custom directory:

openapi-first crud_app my-crud-service\n

List all available application templates:

openapi-first --list\n

The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.

"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--client-usage-example","title":"Client Usage Example","text":"

The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.

Example client calls for CRUD operations:

from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List items\nresponse = client.list_items()\n\n# Get item by ID\nresponse = client.get_item(\n    path_params={\"item_id\": 1}\n)\n\n# Create item\nresponse = client.create_item(\n    body={\"name\": \"Orange\", \"price\": 0.8}\n)\n\n# Update item\nresponse = client.update_item(\n    path_params={\"item_id\": 1},\n    body={\"name\": \"Green Apple\", \"price\": 0.6},\n)\n\n# Delete item\nresponse = client.delete_item(\n    path_params={\"item_id\": 1}\n)\n

Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Path and request parameters must match the OpenAPI specification - Invalid or incomplete OpenAPI specs fail at client construction time

"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--non-goals","title":"Non-Goals","text":"

This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage

It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.

This package is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/crud_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data","title":"openapi_first.templates.crud_app.data","text":"

In-memory mock data store for CRUD example.

This module intentionally avoids persistence and concurrency guarantees. It is suitable for demos, tests, and scaffolding only.

It intentionally avoids - persistence - concurrency guarantees - validation - error handling

The implementation is suitable for: - demonstrations - tests - scaffolding and example services

It is explicitly NOT suitable for production use.

This module is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data-functions","title":"Functions","text":""},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item","title":"create_item","text":"
create_item(payload: dict)\n

Create a new item in the data store.

A new integer ID is assigned automatically. No validation is performed on the provided payload.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item--parameters","title":"Parameters","text":"

payload : dict Item attributes excluding the id field.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item--returns","title":"Returns","text":"

dict The newly created item, including its assigned ID.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.delete_item","title":"delete_item","text":"
delete_item(item_id: int)\n

Remove an item from the data store.

This function assumes the item exists and will raise KeyError if the ID is not present.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.delete_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to delete.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item","title":"get_item","text":"
get_item(item_id: int)\n

Retrieve a single item by ID.

This function assumes the item exists and will raise KeyError if the ID is not present in the store.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to retrieve.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item--returns","title":"Returns","text":"

dict The stored item representation.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.list_items","title":"list_items","text":"
list_items()\n

Return all items in the data store.

This function performs no filtering, pagination, or sorting. The returned collection reflects the current in-memory state.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.list_items--returns","title":"Returns","text":"

list[dict] A list of item representations.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item","title":"update_item","text":"
update_item(item_id: int, payload: dict)\n

Replace an existing item in the data store.

This function overwrites the existing item entirely and does not perform partial updates or validation. If the item does not exist, it will be created implicitly.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to update. payload : dict Item attributes excluding the id field.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item--returns","title":"Returns","text":"

dict The updated item representation.

"},{"location":"openapi_first/templates/crud_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/crud_app/main/#openapi_first.templates.crud_app.main","title":"openapi_first.templates.crud_app.main","text":"

Application entry point for an OpenAPI-first CRUD example service.

This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.

All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.

This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.

Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup

This file is intended to be used as the ASGI entry point.

Example

uvicorn main:app

"},{"location":"openapi_first/templates/crud_app/main/#openapi_first.templates.crud_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/crud_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes","title":"openapi_first.templates.crud_app.routes","text":"

CRUD route handlers bound via OpenAPI operationId.

These handlers explicitly control HTTP status codes to ensure runtime behavior matches the OpenAPI contract.

This module defines OpenAPI-bound operation handlers for a simple CRUD service. Functions in this module are bound to HTTP routes exclusively via OpenAPI operationId values.

Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Error conditions are translated into explicit HTTP responses rather than relying on implicit framework behavior.

No routing decorators or path definitions appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item","title":"create_item","text":"
create_item(payload: dict, response: Response)\n

Create a new item.

Implements the OpenAPI operation identified by operationId: create_item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item--parameters","title":"Parameters","text":"

payload : dict Item attributes excluding the id field. response : fastapi.Response Response object used to set the HTTP status code.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item--returns","title":"Returns","text":"

dict The newly created item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item","title":"delete_item","text":"
delete_item(item_id: int, response: Response)\n

Delete an existing item.

Implements the OpenAPI operation identified by operationId: delete_item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to delete. response : fastapi.Response Response object used to set the HTTP status code.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--returns","title":"Returns","text":"

None No content.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item","title":"get_item","text":"
get_item(item_id: int)\n

Retrieve a single item by ID.

Implements the OpenAPI operation identified by operationId: get_item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to retrieve.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--returns","title":"Returns","text":"

dict The requested item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.list_items","title":"list_items","text":"
list_items()\n

List all items.

Implements the OpenAPI operation identified by operationId: list_items.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.list_items--returns","title":"Returns","text":"

list[dict] A list of item representations.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item","title":"update_item","text":"
update_item(item_id: int, payload: dict)\n

Update an existing item.

Implements the OpenAPI operation identified by operationId: update_item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to update. payload : dict Item attributes excluding the id field.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--returns","title":"Returns","text":"

dict The updated item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/crud_app/test_crud_app/","title":"Test Crud App","text":""},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app","title":"openapi_first.templates.crud_app.test_crud_app","text":"

End-to-end tests for the OpenAPI-first CRUD example app.

These tests validate that all CRUD operations behave correctly against the in-memory mock data store. - OpenAPI specification loading - OperationId-driven route binding on the server - OperationId-driven client invocation - Correct HTTP status codes and response payloads

The tests exercise all CRUD operations against an in-memory mock data store and assume deterministic behavior within a single process.

The tests assume: - OpenAPI-first route binding - In-memory storage (no persistence guarantees) - Deterministic behavior in a single process - One-to-one correspondence between OpenAPI operationId values and server/client callables

"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app-classes","title":"Classes","text":""},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app-functions","title":"Functions","text":""},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_create_item","title":"test_create_item","text":"
test_create_item()\n

Creating a new item should return the created entity.

"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_delete_item","title":"test_delete_item","text":"
test_delete_item()\n

Deleting an item should remove it from the store.

"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_get_item","title":"test_get_item","text":"
test_get_item()\n

Existing item should be retrievable by ID.

"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_list_items_initial","title":"test_list_items_initial","text":"
test_list_items_initial()\n

Initial items should be present.

"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_update_item","title":"test_update_item","text":"
test_update_item()\n

Updating an item should replace its values.

"},{"location":"openapi_first/templates/health_app/","title":"Health App","text":"
  • Main
  • Routes
"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app","title":"openapi_first.templates.health_app","text":"

OpenAPI-first FastAPI application template.

This package contains a minimal, fully working example of an OpenAPI-first FastAPI service built using the openapi_first library.

The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace (routes)

No routing decorators, implicit behavior, or framework-specific convenience abstractions are used. All HTTP routes, methods, and operation bindings are defined in OpenAPI and enforced at application startup.

This package is intended to be copied as a starting point for new services via the openapi-first CLI. It is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"

Create a new OpenAPI-first health check service using the bundled template:

openapi-first health_app\n

Create the service in a custom directory:

openapi-first health_app my-health-service\n

List all available application templates:

openapi-first --list\n

The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.

"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app--client-usage-example","title":"Client Usage Example","text":"

The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.

Example client call for the get_health operation:

from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\nresponse = client.get_health()\n\nassert response.status_code == 200\nassert response.json() == {\"status\": \"ok\"}\n

Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Path and request parameters must match the OpenAPI specification - Invalid or incomplete OpenAPI specs fail at client construction time

"},{"location":"openapi_first/templates/health_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/health_app/main/#openapi_first.templates.health_app.main","title":"openapi_first.templates.health_app.main","text":"

Application entry point for an OpenAPI-first FastAPI service.

This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.

All HTTP routes, methods, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.

This module contains no routing logic, request handling, or framework configuration beyond application assembly.

Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup

This file is intended to be used as the ASGI entry point.

Example

uvicorn main:app

"},{"location":"openapi_first/templates/health_app/main/#openapi_first.templates.health_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/health_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes","title":"openapi_first.templates.health_app.routes","text":"

OpenAPI operation handlers.

This module defines pure Python callables that implement OpenAPI operations for this service. Functions in this module are bound to HTTP routes exclusively via OpenAPI operationId values.

No routing decorators, HTTP metadata, or framework-specific logic should appear here. All request/response semantics are defined in the OpenAPI specification.

This module serves solely as an operationId namespace.

"},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes.get_health","title":"get_health","text":"
get_health()\n

Health check operation handler.

This function implements the OpenAPI operation identified by operationId: get_health.

It contains no routing metadata or framework-specific logic. Request binding, HTTP method, and response semantics are defined exclusively by the OpenAPI specification.

"},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes.get_health--returns","title":"Returns","text":"

dict A minimal liveness payload indicating service health.

"},{"location":"openapi_first/templates/model_app/","title":"Model App","text":"
  • Data
  • Main
  • Models
  • Routes
  • Test Model App
"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app","title":"openapi_first.templates.model_app","text":"

OpenAPI-first model-based CRUD application template.

This package contains a complete, minimal example of an OpenAPI-first CRUD service that uses explicit Pydantic domain models for request and response schemas.

The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace implementing CRUD operations (routes) - Pydantic domain models (models) - an in-memory mock data store (data)

All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification and enforced at application startup. No decorator-driven routing or implicit framework behavior is used.

This template demonstrates: - operationId-driven server-side route binding - explicit request and response modeling with Pydantic - explicit HTTP status code control in handlers - operationId-driven client usage against the same OpenAPI contract - end-to-end validation using in-memory data and tests

"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"

Create a new model-based CRUD example service using the bundled template:

openapi-first model_app\n

Create the service in a custom directory:

openapi-first model_app my-model-service\n

List all available application templates:

openapi-first --list\n

The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.

"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--client-usage-example","title":"Client Usage Example","text":"

The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.

Example client calls for model-based CRUD operations:

from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List items\nresponse = client.list_items()\n\n# Get item by ID\nresponse = client.get_item(\n    path_params={\"item_id\": 1}\n)\n\n# Create item\nresponse = client.create_item(\n    body={\"name\": \"Orange\", \"price\": 0.8}\n)\n\n# Update item\nresponse = client.update_item(\n    path_params={\"item_id\": 1},\n    body={\"name\": \"Green Apple\", \"price\": 0.6},\n)\n\n# Delete item\nresponse = client.delete_item(\n    path_params={\"item_id\": 1}\n)\n

Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Request and response payloads conform to Pydantic models - Invalid or incomplete OpenAPI specs fail at client construction time

"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--non-goals","title":"Non-Goals","text":"

This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage

It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.

This package is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/model_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data","title":"openapi_first.templates.model_app.data","text":"

In-memory data store using Pydantic models.

This module is NOT thread-safe and is intended for demos and scaffolds only. This module provides a minimal, process-local data store for the model-based CRUD example application. It stores and returns domain objects defined using Pydantic models and is intended solely for demonstration and scaffolding purposes.

The implementation intentionally avoids: - persistence - concurrency guarantees - transactional semantics - validation beyond what Pydantic provides

It is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data-functions","title":"Functions","text":""},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item","title":"create_item","text":"
create_item(payload: ItemCreate) -> Item\n

Create a new item in the data store.

A new identifier is assigned automatically. No additional validation is performed beyond Pydantic model validation.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item--parameters","title":"Parameters","text":"

payload : ItemCreate Data required to create a new item.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item--returns","title":"Returns","text":"

Item The newly created item.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item","title":"delete_item","text":"
delete_item(item_id: int) -> None\n

Remove an item from the data store.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to delete.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item--raises","title":"Raises","text":"

KeyError If the item does not exist.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item","title":"get_item","text":"
get_item(item_id: int) -> Item\n

Retrieve a single item by ID.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to retrieve.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--returns","title":"Returns","text":"

Item The requested item.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--raises","title":"Raises","text":"

KeyError If the item does not exist.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.list_items","title":"list_items","text":"
list_items() -> list[Item]\n

Return all items in the data store.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.list_items--returns","title":"Returns","text":"

list[Item] A list of item domain objects.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item","title":"update_item","text":"
update_item(item_id: int, payload: ItemCreate) -> Item\n

Replace an existing item in the data store.

This function performs a full replacement of the stored item. Partial updates are not supported.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to update. payload : ItemCreate New item data.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--returns","title":"Returns","text":"

Item The updated item.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--raises","title":"Raises","text":"

KeyError If the item does not exist.

"},{"location":"openapi_first/templates/model_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/model_app/main/#openapi_first.templates.model_app.main","title":"openapi_first.templates.model_app.main","text":"

Application entry point for an OpenAPI-first model-based CRUD example service.

This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.

All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.

This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.

Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup

This file is intended to be used as the ASGI entry point.

Example

uvicorn main:app

"},{"location":"openapi_first/templates/model_app/main/#openapi_first.templates.model_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/model_app/models/","title":"Models","text":""},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models","title":"openapi_first.templates.model_app.models","text":"

Pydantic domain models for the CRUD example.

This module defines Pydantic models that represent the domain entities used by the service. These models are referenced by the OpenAPI specification for request and response schemas.

The models are declarative and framework-agnostic. They contain no persistence logic, validation beyond type constraints, or business behavior.

This module is not part of the openapi_first library API surface. It exists solely to support the example application template.

"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models-classes","title":"Classes","text":""},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.Item","title":"Item","text":"

Bases: ItemBase

Domain model for a persisted item.

This model represents the full item state returned in responses, including the server-assigned identifier.

"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.ItemBase","title":"ItemBase","text":"

Bases: BaseModel

Base domain model for an item.

Defines fields common to all item representations.

"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.ItemCreate","title":"ItemCreate","text":"

Bases: ItemBase

Domain model for item creation requests.

This model is used for request bodies when creating new items. It intentionally excludes the id field, which is assigned by the service.

"},{"location":"openapi_first/templates/model_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes","title":"openapi_first.templates.model_app.routes","text":"

CRUD route handlers bound via OpenAPI operationId.

This module defines OpenAPI-bound operation handlers for a model-based CRUD service. Functions in this module are bound to HTTP routes exclusively via OpenAPI operationId values.

Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Domain models defined using Pydantic are used for request and response payloads.

No routing decorators, path definitions, or implicit framework behavior appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item","title":"create_item","text":"
create_item(payload: ItemCreate, response: Response)\n

Create a new item.

Implements the OpenAPI operation identified by operationId: create_item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item--parameters","title":"Parameters","text":"

payload : ItemCreate Request body describing the item to create. response : fastapi.Response Response object used to set the HTTP status code.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item--returns","title":"Returns","text":"

Item The newly created item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item","title":"delete_item","text":"
delete_item(item_id: int, response: Response)\n

Delete an existing item.

Implements the OpenAPI operation identified by operationId: delete_item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to delete. response : fastapi.Response Response object used to set the HTTP status code.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--returns","title":"Returns","text":"

None No content.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item","title":"get_item","text":"
get_item(item_id: int)\n

Retrieve a single item by ID.

Implements the OpenAPI operation identified by operationId: get_item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to retrieve.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--returns","title":"Returns","text":"

Item The requested item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.list_items","title":"list_items","text":"
list_items()\n

List all items.

Implements the OpenAPI operation identified by operationId: list_items.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.list_items--returns","title":"Returns","text":"

list[Item] A list of item domain objects.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item","title":"update_item","text":"
update_item(item_id: int, payload: ItemCreate)\n

Update an existing item.

Implements the OpenAPI operation identified by operationId: update_item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to update. payload : ItemCreate New item data.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--returns","title":"Returns","text":"

Item The updated item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/model_app/test_model_app/","title":"Test Model App","text":""},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app","title":"openapi_first.templates.model_app.test_model_app","text":"

End-to-end tests for the OpenAPI-first model CRUD example app.

These tests validate that all CRUD operations behave correctly against the in-memory mock data store using Pydantic models. - OpenAPI specification loading - OperationId-driven route binding on the server - OperationId-driven client invocation - Pydantic model-based request and response handling

All CRUD operations are exercised against an in-memory mock data store backed by Pydantic domain models.

The tests assume: - OpenAPI-first route binding - Pydantic model validation - In-memory storage (no persistence guarantees) - Deterministic behavior in a single process

"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app-classes","title":"Classes","text":""},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app-functions","title":"Functions","text":""},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_create_item","title":"test_create_item","text":"
test_create_item()\n

Creating a new item should return the created entity.

"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_delete_item","title":"test_delete_item","text":"
test_delete_item()\n

Deleting an item should remove it from the store.

"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_get_item","title":"test_get_item","text":"
test_get_item()\n

Existing item should be retrievable by ID.

"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_list_items_initial","title":"test_list_items_initial","text":"
test_list_items_initial()\n

Initial items should be present.

"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_update_item","title":"test_update_item","text":"
test_update_item()\n

Updating an item should replace its values.

"},{"location":"openapi_first/templates/vet_app/","title":"Vet App","text":"
  • Data
  • Main
  • Models
  • Routes
  • Sse
  • Test Vet App
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app","title":"openapi_first.templates.vet_app","text":"

OpenAPI-first Veterinary Clinic application template.

This package contains a complete, runnable example of an OpenAPI-first veterinary clinic management service. It demonstrates all x- extension fields consumed by the react-openapi admin panel renderer.

The application manages five resources:

  • Parents \u2014 pet owners with contact details
  • Vets \u2014 veterinarians with specializations
  • Treatments \u2014 medical procedure catalog
  • Pets \u2014 animals with species, age, weight, and photos
  • Appointments \u2014 scheduled visits linking pets, vets, and treatments

All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification (openapi.yaml). Every operation has an explicit operationId that maps to a Python handler in routes.py.

This file is a copyable template. It is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--openapi-x-extension-fields-demonstrated","title":"OpenAPI x- extension fields demonstrated","text":"

Schema-level extensions (display metadata for resource endpoints):

x-primary-key (REQUIRED) Primary key property name x-display-format (REQUIRED) Human-readable label template x-list-columns (REQUIRED) Columns for the datatable

Property-level extensions (control UI rendering):

x-label (REQUIRED) Human-readable field label x-order (REQUIRED) Field ordering in forms/detail x-description (optional) Helper text below form fields x-hidden (optional) Visibility in form / list / detail x-filterable (optional) Allows column filtering x-sortable (optional) Allows column sorting x-fk (optional) Foreign key \u2014 renders as dropdown x-fk.resource (REQUIRED for FK) Target resource name x-fk.prefetch (optional) Preload all FK options on mount x-ui-type (optional) Custom UI type (e.g. image upload) x-upload-url (optional) Upload endpoint for binary fields

"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"

Create a new vet clinic service using the bundled template:

openapi-first vet_app\n

Create the service in a custom directory:

openapi-first vet_app my-vet-clinic\n
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--client-usage-example","title":"Client Usage Example","text":"
from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List pets with pagination\nresponse = client.list_pets(query_params={\"limit\": 10, \"offset\": 0})\n\n# Create a pet with FK references\nresponse = client.create_pet(\n    body={\"name\": \"Fido\", \"species\": \"dog\", \"parents\": [1, 2]}\n)\n\n# Upload a pet photo\nresponse = client.upload_pet_photo(\n    path_params={\"id\": 1},\n    body={\"file\": open(\"photo.jpg\", \"rb\")},\n)\n
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--non-goals","title":"Non-Goals","text":"

This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage

It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.

This package is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/vet_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/vet_app/data/#openapi_first.templates.vet_app.data","title":"openapi_first.templates.vet_app.data","text":"

In-memory data store for the Veterinary Clinic example.

This module is NOT thread-safe and is intended for demos and scaffolds only.

It provides minimal, process-local data stores for the five veterinary clinic entities. Each store exposes standard CRUD operations backed by a simple dictionary.

This module intentionally avoids: - persistence - concurrency guarantees - transactional semantics - validation beyond what Pydantic provides

This module is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/vet_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/vet_app/main/#openapi_first.templates.vet_app.main","title":"openapi_first.templates.vet_app.main","text":"

Application entry point for an OpenAPI-first Veterinary Clinic service.

This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.

All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.

This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.

Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup

This file is intended to be used as the ASGI entry point.

Example

uvicorn main:app

"},{"location":"openapi_first/templates/vet_app/main/#openapi_first.templates.vet_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/vet_app/models/","title":"Models","text":""},{"location":"openapi_first/templates/vet_app/models/#openapi_first.templates.vet_app.models","title":"openapi_first.templates.vet_app.models","text":""},{"location":"openapi_first/templates/vet_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes","title":"openapi_first.templates.vet_app.routes","text":"

Veterinary Clinic route handlers bound via OpenAPI operationId.

Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Domain models defined using Pydantic are used for request and response payloads.

No routing decorators, path definitions, or implicit framework behavior appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_appointment","title":"create_appointment","text":"
create_appointment(\n    payload: AppointmentCreate, response: Response\n)\n

Create an appointment.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_parent","title":"create_parent","text":"
create_parent(payload: ParentCreate, response: Response)\n

Create a parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_parent--parameters","title":"Parameters","text":"

payload : ParentCreate Parent data excluding the id field.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_parent--returns","title":"Returns","text":"

Parent The newly created parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_pet","title":"create_pet","text":"
create_pet(payload: PetCreate, response: Response)\n

Create a pet.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_treatment","title":"create_treatment","text":"
create_treatment(\n    payload: TreatmentCreate, response: Response\n)\n

Add a treatment (admin only).

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_vet","title":"create_vet","text":"
create_vet(payload: VetCreate, response: Response)\n

Create a vet.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_appointment","title":"delete_appointment","text":"
delete_appointment(id: int, response: Response)\n

Delete an existing appointment.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_parent","title":"delete_parent","text":"
delete_parent(id: int, response: Response)\n

Delete an existing parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_parent--parameters","title":"Parameters","text":"

id : int Identifier of the parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_parent--raises","title":"Raises","text":"

HTTPException 404 if the parent does not exist.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_pet","title":"delete_pet","text":"
delete_pet(id: int, response: Response)\n

Delete an existing pet.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_treatment","title":"delete_treatment","text":"
delete_treatment(id: int, response: Response)\n

Delete an existing treatment.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_vet","title":"delete_vet","text":"
delete_vet(id: int, response: Response)\n

Delete an existing vet.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_appointment","title":"get_appointment","text":"
get_appointment(id: int)\n

Retrieve a single appointment by ID.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent","title":"get_parent","text":"
get_parent(id: int)\n

Retrieve a single parent by ID.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent--parameters","title":"Parameters","text":"

id : int Identifier of the parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent--returns","title":"Returns","text":"

Parent The requested parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent--raises","title":"Raises","text":"

HTTPException 404 if the parent does not exist.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_pet","title":"get_pet","text":"
get_pet(id: int)\n

Retrieve a single pet by ID.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_treatment","title":"get_treatment","text":"
get_treatment(id: int)\n

Retrieve a single treatment by ID.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_vet","title":"get_vet","text":"
get_vet(id: int)\n

Retrieve a single vet by ID.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_appointments","title":"list_appointments","text":"
list_appointments(\n    limit: int = 20,\n    offset: int = 0,\n    date: str = None,\n    vet: int = None,\n    pet: int = None,\n)\n

List appointments (paginated, filterable).

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_parents","title":"list_parents","text":"
list_parents(limit: int = 20, offset: int = 0)\n

List parents (paginated).

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_parents--parameters","title":"Parameters","text":"

limit : int Maximum number of records to return. offset : int Number of records to skip.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_parents--returns","title":"Returns","text":"

dict Paginated response with total and items.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_pets","title":"list_pets","text":"
list_pets(limit: int = 20, offset: int = 0)\n

List pets (paginated).

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_treatments","title":"list_treatments","text":"
list_treatments()\n

List treatments (catalogue).

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_treatments--returns","title":"Returns","text":"

list[Treatment] A list of treatment domain objects.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_vets","title":"list_vets","text":"
list_vets(limit: int = 20, offset: int = 0)\n

List vets (paginated).

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.stream_actions","title":"stream_actions async","text":"
stream_actions(id: int)\n

Stream animal actions via SSE, scoped to a pet's species.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_appointment","title":"update_appointment","text":"
update_appointment(id: int, payload: AppointmentCreate)\n

Update an existing appointment.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent","title":"update_parent","text":"
update_parent(id: int, payload: ParentCreate)\n

Update an existing parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent--parameters","title":"Parameters","text":"

id : int Identifier of the parent. payload : ParentCreate Updated parent data.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent--returns","title":"Returns","text":"

Parent The updated parent.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent--raises","title":"Raises","text":"

HTTPException 404 if the parent does not exist.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_pet","title":"update_pet","text":"
update_pet(id: int, payload: PetCreate)\n

Update an existing pet.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_treatment","title":"update_treatment","text":"
update_treatment(id: int, payload: TreatmentCreate)\n

Update an existing treatment.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_vet","title":"update_vet","text":"
update_vet(id: int, payload: VetCreate)\n

Update an existing vet.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.upload_pet_photo","title":"upload_pet_photo","text":"
upload_pet_photo(id: int, file: UploadFile)\n

Upload a pet photo.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.upload_pet_photo--parameters","title":"Parameters","text":"

id : int Identifier of the pet. file : UploadFile Image file to upload.

"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.upload_pet_photo--returns","title":"Returns","text":"

dict A confirmation with the pet ID.

"},{"location":"openapi_first/templates/vet_app/sse/","title":"Sse","text":""},{"location":"openapi_first/templates/vet_app/sse/#openapi_first.templates.vet_app.sse","title":"openapi_first.templates.vet_app.sse","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/","title":"Test Vet App","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app","title":"openapi_first.templates.vet_app.test_vet_app","text":"

End-to-end tests for the OpenAPI-first Veterinary Clinic example app.

These tests validate that all CRUD operations behave correctly against the in-memory mock data store using Pydantic models.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app-classes","title":"Classes","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app-functions","title":"Functions","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_parent","title":"test_create_parent","text":"
test_create_parent()\n

Creating a parent returns 201 with the created entity.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_pet","title":"test_create_pet","text":"
test_create_pet()\n

Creating a pet links FK references.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_treatment","title":"test_create_treatment","text":"
test_create_treatment()\n

Creating a treatment returns 201.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_vet","title":"test_create_vet","text":"
test_create_vet()\n

Creating a vet returns 201.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_delete_parent","title":"test_delete_parent","text":"
test_delete_parent()\n

Delete parent returns 204 and removes the entity.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_full_appointment_lifecycle","title":"test_full_appointment_lifecycle","text":"
test_full_appointment_lifecycle()\n

Create a parent, vet, treatment, pet, then an appointment.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_get_parent","title":"test_get_parent","text":"
test_get_parent()\n

Get parent by ID returns the entity.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_appointments","title":"test_list_appointments","text":"
test_list_appointments()\n

List appointments returns paginated response with filter params.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_parents","title":"test_list_parents","text":"
test_list_parents()\n

List parents returns paginated response.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_treatments","title":"test_list_treatments","text":"
test_list_treatments()\n

List treatments returns an array.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_vets","title":"test_list_vets","text":"
test_list_vets()\n

List vets returns paginated response.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_update_parent","title":"test_update_parent","text":"
test_update_parent()\n

Update parent replaces its values.

"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_upload_pet_photo","title":"test_upload_pet_photo","text":"
test_upload_pet_photo()\n

Upload pet photo returns 200.

"}]} \ No newline at end of file