Core Types¶

The G6 type system is defined in mvp.core and provides the foundational data structures used across all components. These are the core types you build against when writing extensions with the g6ext.* SDK — see Extending G6. G6 is proprietary software; the Architecture overview covers licensing and distribution.

Result[T]¶

A monadic result type that encapsulates success or failure without exceptions. Defined in mvp.core.result.

from mvp.core import Result, Status

Status enum¶

Status.OK: Indicates a successful result.
Status.FAIL: Indicates a failed result with an error message.

Factory methods¶

Result.ok(value: T) -> Result[T]: Create a success result wrapping the given value.
Result.fail(error: str) -> Result[T]: Create a failure result with an error message.

Instance predicates and accessors¶

Note

is_ok() and is_fail() are methods — call them. value and error are properties. Omitting the parentheses yields a bound method object, which is always truthy, so the check silently passes and an assertion on it can never fail.

.is_ok() -> bool: True if the result is successful.
.is_fail() -> bool: True if the result is a failure.
.value -> T: Access the success value. Raises if the result is a failure.
.error -> str: Access the error message. Raises if the result is successful.

Combinators¶

.map(fn: Callable[[T], U]) -> Result[U]: Transform the success value. If the result is a failure, returns the failure unchanged.
.flat_map(fn: Callable[[T], Result[U]]) -> Result[U]: Chain operations that return Results. Enables railway-oriented programming.
.or_else(fn: Callable[[str], Result[T]]) -> Result[T]: Handle failure by providing an alternative. If the result is successful, returns it unchanged.

Example¶

result = Result.ok(42)
doubled = result.map(lambda x: x * 2)       # Result.ok(84)
chained = result.flat_map(lambda x: Result.ok(x + 1))  # Result.ok(43)

AIBlock[Input, Output, State]¶

The universal computation unit. Every G6 component extends AIBlock. Defined in mvp.core.ai_block.

from mvp.core import AIBlock

name: str: Human-readable name for the block.
state: State: Mutable state carried across invocations. Defaults to None.
process(input: Input) -> Result[Output]: The core computation method. Subclasses override this.
infer(input: Input) -> Result[Output]: Public entry point that calls process() with resource enforcement.

Type parameters¶

Input -- the input dataclass or Pydantic model
Output -- the output dataclass or Pydantic model
State -- mutable state type (often dict or None)

PipelineBlock¶

Chainable pipeline stages using the >> operator. Defined in mvp.core.ai_block.

from mvp.core import PipelineBlock

pipeline = block_a >> block_b >> block_c
result = pipeline.process(input_data)

Inheritance note

PipelineBlock uses a regular __init__, not a dataclass __init__, due to inheritance and default value constraints.

Protocols¶

Six structural protocols define the capabilities a component can declare. Defined in mvp.core.protocols.

from mvp.core import Ingestible, Emittable, Storable, Inferrable, Learnable, InductiveBias

Ingestible: Can accept external data. Defines ingest(data) -> Result.
Emittable: Can produce output. Defines emit() -> Result.
Storable: Can persist and restore state. Defines save(path) and load(path).
Inferrable: Can perform inference. Defines infer(input) -> Result.
Learnable: Can learn from data. Defines learn(data) -> Result.
InductiveBias: Declares inductive biases. Defines biases() -> list[str].

ResourceBounds¶

Frozen dataclass controlling token and time budgets. Defined in mvp.core.resource_bounds.

from mvp.core import ResourceBounds

max_tokens: int: Maximum tokens allowed per operation.
max_time_seconds: float: Maximum wall-clock time per operation.
max_retries: int: Maximum retry attempts on failure.

ResourceUsage¶

Mutable companion tracking actual consumption.

tokens_used: int: Tokens consumed so far.
time_elapsed: float: Wall-clock seconds elapsed.

ResourceGuardrail¶

A Guardrail subclass that enforces ResourceBounds. Uses >= comparison (a limit of 0 blocks all usage). Error messages include the [RESOURCE_LIMIT] tag.

Token windows are tracked via sliding window: _MINUTE, _HOUR, _DAY, _WEEK, _MONTH constants with _token_log list.

SearchTree¶

Goal decomposition tree structure. Defined in mvp.core.search_tree.

from mvp.core import SearchTree, TreeNode

TreeNode

A node in the search tree. Contains:

data -- the node payload (e.g., goal text)
children: list[TreeNode] -- child nodes
diagnostic: NodeDiagnostic | None -- optional diagnostic info

SearchTree

The root container. Provides:

iter_nodes() -- iterate all nodes depth-first
__len__() -- total node count

Supporting types¶

FailureMode: Categorization of how a node can fail.
Guardrail: A condition that must hold during execution.
Checkpoint: A named metric threshold to verify.
Breakpoint: A named pause point for human-in-the-loop review.
NodeDiagnostic: Diagnostic metadata attached to a tree node.

CSF types¶

Computational Safety Framework primitives. Defined in mvp.core.csf_primitives.

from mvp.core import TransitionOutcome, BoundedAgent, SafetyMonitor

TransitionOutcome: Frozen dataclass representing the result of a state transition.
TransitionKernel: Type alias for transition probability functions.
ResourceTriple: Frozen dataclass with three non-negative resource values. Validates >= 0.
BoundedAgent: Frozen dataclass representing an agent with resource bounds and transition functions.
SafetyMonitor: Abstract base class for safety monitoring. Subclasses implement check().
StepRationale: Mutable dataclass capturing the reasoning behind a step.
SafetyDecisionReport: Mutable dataclass aggregating safety check results.

Goal Engine types¶

Defined in mvp.goal_engine.schema.

from mvp.goal_engine import GoalInput, ResourceBoundsSchema

ResourceBoundsSchema

Pydantic model (frozen) for serializable resource bounds.

GoalInput

Pydantic model (frozen) for goal decomposition input. Supports nested subtasks.

goal: str -- the goal text
max_depth: int -- maximum decomposition depth
subtasks: list[GoalInput] -- optional nested sub-goals