A developer using ReasonChip plays the role of a workflow architect and chip engineer. They design pipelines by composing modular tasks (Chips) to automate reasoning or decision-making processes. Developers create Chips as asynchronous Python functions with well-defined inputs and outputs, register them for use, and structure them into pipelines using YAML. They focus on clarity, reusability, and reliability, enabling complex workflows to be broken down into simple, testable units. With ReasonChip, developers can build distributed systems that coordinate logic, handle branching, and scale across infrastructure - without writing orchestration logic from scratch.

• Is a self-contained function that does one job well.
• Accepts a Pydantic-validated input model.
• Returns a Pydantic-validated output model.
• Can be executed standalone or as part of a larger pipeline.
• Is registered with the ReasonChip Registry so it can be discovered and invoked dynamically.

Chips are the modular units of execution in pipelines. Each chip is a Python function, typically asynchronous, that performs a discrete task (e.g., send a message, call an API, run a transformation). Chips are dynamically registered and executed by the ReasonChip engine.

This guide walks through the structure, requirements, and best practices for writing your own chip.

Creating a new chip is straightforward. Here’s the anatomy:

from reasonchip import Registry
from pydantic import BaseModel, Field

class MyChipRequest(BaseModel):
    """
    Request structure documentation.
    """
    field1: str = Field(description="Description of field1.")


class MyChipResponse(BaseModel):
    """
    Response structure documentation.
    """
    status: typing.Literal["OK", "ERROR"] = Field(description="Status of the request.")
    result: typing.Optional[typing.Any] = Field(
        default=None,
        description="The result of the operation (if successful).",
    )
    error_message: typing.Optional[str] = Field(
        default=None,
        description="Error message if the operation failed.",
    )


@Registry.register
async def my_chip(request: MyChipRequest) -> MyChipResponse:
    try:
        # Perform logic here
        return MyChipResponse(status='OK', result=5)

    except Exception as e:
        return MyChipResponse(status='ERROR', error_message=str(e))

Ensure that your chip is loaded within your pipeline context. Then all you do is reference the chip directly by its full module name and provide the parameters required.

- name: 'Calling my custom chip'
  chip: full.module.name.my_chip
  params:
    field1: "Howdy"
  store_result_as: rc
		

1. Input and Output Must Be Pydantic Models

Use Pydantic’s BaseModel to define inputs and outputs. This ensures validation, auto-documentation, and structured communication between chips.

2. Use the @Registry.register Decorator

This exposes the chip to ReasonChip’s pipeline engine and registry. Without this, your chip won’t be discoverable or executable in pipelines.

3. Use async def for Your Chip

Chips must be asynchronous to support concurrent pipeline execution. Always define chips with async def.

Structure

• Keep logic simple, focused, and testable.
• Offload shared logic to utility functions or libraries.

Error Handling

• Catch and categorize known exceptions.
• Return informative error messages in your output model.
• Avoid crashing the pipeline with unhandled exceptions.

Documentation

• Include clear docstrings.
• Use Pydantic Field descriptions for auto-generated docs.

Idempotence

• Ensure chips don’t produce unexpected side effects if retried.

• All chips can be invoked by ReasonChip pipelines, CLI tools, or remote orchestrators.
• Chips should never block or sleep synchronously.
• Output should always include a status field or success indicator.