Skip to content

chatomon.connectors.base

The connector extension point: how an atom becomes a native agent.

Classes:

Name Description
Connector

Builds an atom into a native agent of one framework.

Functions:

Name Description
render_guidance

Render guidance as the section connectors add to one model call.

Attributes:

Name Type Description
AgentT

Type of the native agent a connector builds.
ModelT

Type of a structured model answer.

AgentT module-attribute 

AgentT = TypeVar('AgentT')

Type of the native agent a connector builds.

ModelT module-attribute 

ModelT = TypeVar('ModelT', bound=BaseModel)

Type of a structured model answer.

Connector

Bases: ABC, Generic[AgentT]

Builds an atom into a native agent of one framework.

A connector installs chatomon's hooks as the outermost layer of the native agent and translates the engine's decisions into the framework's mechanisms. To support a new framework, subclass it in a new module and make it pass the shared contract suite.

Examples:

A toy connector whose "native agent" is a dictionary:

from typing import Any

from chatomon import Atom
from chatomon.connectors import Connector


class DictConnector(Connector[dict[str, Any]]):
    def build(self, atom, engine):
        return {"system_prompt": atom.system_prompt, "engine": engine}

    async def generate_structured(self, model, *, system, prompt, schema):
        raise NotImplementedError


agent = Atom(name="demo", instructions="Be brief.", connector=DictConnector()).build()
assert agent["system_prompt"] == "Be brief."

Methods:

Name Description
build

Return the native agent with chatomon's hooks installed.
generate_structured

Make one model call whose answer must match schema.

build abstractmethod 

build(atom: Atom[AgentT], engine: Engine) -> AgentT

Return the native agent with chatomon's hooks installed.

Parameters:

Name Type Description Default
atom Atom[AgentT]

The validated atom.

 required
engine Engine

The engine that runs the atom's orbitals.

 required

Returns:

Type Description
AgentT

The framework's agent object.
Source code in src/chatomon/connectors/base.py 
55
56
57
58
59
60
61
62
63
64
65
@abstractmethod
def build(self, atom: Atom[AgentT], engine: Engine) -> AgentT:
    """Return the native agent with chatomon's hooks installed.

    Args:
        atom: The validated atom.
        engine: The engine that runs the atom's orbitals.

    Returns:
        The framework's agent object.
    """

generate_structured abstractmethod async 

generate_structured(
    model: str,
    *,
    system: str,
    prompt: str,
    schema: type[ModelT]
) -> ModelT

Make one model call whose answer must match schema.

Used by orbitals that call a model, such as the judge.

Parameters:

Name Type Description Default
model str

Model identifier in the framework's format.

 required
system str

System prompt.

 required
prompt str

User prompt.

 required
schema type[ModelT]

Pydantic model the answer must validate against.

 required

Returns:

Type Description
ModelT

The validated answer.
Source code in src/chatomon/connectors/base.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
@abstractmethod
async def generate_structured(
    self, model: str, *, system: str, prompt: str, schema: type[ModelT]
) -> ModelT:
    """Make one model call whose answer must match `schema`.

    Used by orbitals that call a model, such as the judge.

    Args:
        model: Model identifier in the framework's format.
        system: System prompt.
        prompt: User prompt.
        schema: Pydantic model the answer must validate against.

    Returns:
        The validated answer.
    """

render_guidance 

render_guidance(guidance: Sequence[str]) -> str

Render guidance as the section connectors add to one model call.

Parameters:

Name Type Description Default
guidance Sequence[str]

Guidance items, in order.

 required

Returns:

Type Description
str

A <guidance> block with one bullet per item.

Examples:

from chatomon.connectors import render_guidance

assert render_guidance(["Be brief."]) == "<guidance>\n- Be brief.\n</guidance>"
Source code in src/chatomon/connectors/base.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def render_guidance(guidance: Sequence[str]) -> str:
    r"""Render guidance as the section connectors add to one model call.

    Args:
        guidance: Guidance items, in order.

    Returns:
        A `<guidance>` block with one bullet per item.

    Examples:
        ```python
        from chatomon.connectors import render_guidance

        assert render_guidance(["Be brief."]) == "<guidance>\n- Be brief.\n</guidance>"
        ```
    """
    items = "\n".join(f"- {item}" for item in guidance)
    return f"<guidance>\n{items}\n</guidance>"