concordat 0.0.1__py3-none-any.whl

concordat/__init__.py

@@ -0,0 +1,24 @@
+"""Typed sessions for AI agents."""
+
+from importlib.metadata import version as _version
+
+from .agent import Action, Agent, Approver, cli_approver, human, tool
+from .budget import Budget, BudgetExceeded
+from .protocol import Protocol, ProtocolError
+from .session import ProtocolViolation, Session
+
+__all__ = [
+    "Action",
+    "Agent",
+    "Approver",
+    "Budget",
+    "BudgetExceeded",
+    "Protocol",
+    "ProtocolError",
+    "ProtocolViolation",
+    "Session",
+    "cli_approver",
+    "human",
+    "tool",
+]
+__version__ = _version("concordat")  # set in pyproject.toml

concordat/_runner.py

@@ -0,0 +1,105 @@
+"""Provider-neutral parts of the model runners. Needs pydantic, which every provider SDK ships."""
+
+from __future__ import annotations
+
+import inspect
+import typing
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import pydantic
+import pydantic_core
+
+from .agent import Action, Agent
+from .budget import Budget
+
+STEPWISE_NOTE = (
+    "This conversation follows a fixed process. Each turn you are offered only the "
+    "actions allowed at the current step, so tools you used earlier may no longer be "
+    "listed and new ones may appear. That is expected: earlier results remain valid."
+)
+
+Status = Literal["done", "waiting", "refused", "max_tokens", "out_of_budget", "max_turns"]
+
+
+@dataclass
+class RunResult:
+    """How a run ended.
+
+    ``done``: the protocol reached a final state. ``waiting``: the model ended its turn
+    before that, usually to ask the user something; append a user message to
+    ``messages`` and call ``run`` again to continue.
+    """
+
+    status: Status
+    text: str
+    messages: list[Any]
+
+
+def system_prompt(agent: Agent) -> str:
+    return f"{agent.instructions}\n\n{STEPWISE_NOTE}" if agent.instructions else STEPWISE_NOTE
+
+
+def with_next_step(agent: Agent, content: str) -> str:
+    """Append what the model may do next, so a changing tool list is never a surprise."""
+    if agent.done:
+        return f"{content}\n\n[The process is complete.]"
+    allowed = ", ".join(agent.allowed_tools())
+    return f"{content}\n\n[Now allowed: {allowed}.]"
+
+
+def exhausted(budget: Budget) -> bool:
+    return (budget.tokens is not None and budget.tokens <= 0) or (
+        budget.tool_calls is not None and budget.tool_calls <= 0
+    )
+
+
+def cap(budget: Budget, max_tokens: int) -> int:
+    """The output limit for the next response: never more than the tokens left."""
+    return max_tokens if budget.tokens is None else min(max_tokens, budget.tokens)
+
+
+def charge(budget: Budget, used: int) -> bool:
+    """Charge the tokens a request processed; on overspend, empty the budget instead."""
+    if budget.tokens is not None and used > budget.tokens:
+        budget.tokens = 0
+        return False
+    budget.spend(tokens=used)
+    return True
+
+
+def arguments(action: Action) -> type[pydantic.BaseModel]:
+    """A model of the action's parameters, from its signature and type hints."""
+    hints = typing.get_type_hints(action.call)
+    fields: dict[str, Any] = {
+        name: (hints.get(name, Any), ... if p.default is p.empty else p.default)
+        for name, p in inspect.signature(action.call).parameters.items()
+    }
+    return pydantic.create_model(f"{action.name}_arguments", **fields)
+
+
+def description(action: Action) -> str:
+    if action.human:
+        return (
+            "Ask a human to decide; returns 'approved' or 'rejected'. " + action.description
+        ).strip()
+    return action.description
+
+
+def invoke(actions: dict[str, Action], name: str, raw: Any) -> tuple[str, bool]:
+    """Validate and run one call. Returns the result text and whether it is an error.
+
+    ``raw`` is the call's arguments as a dict, or as a JSON string.
+    """
+    action = actions.get(name)
+    if action is None:
+        return f"{name!r} is not allowed in the current state.", True
+    try:
+        model = arguments(action)
+        args = model.model_validate_json(raw) if isinstance(raw, str) else model.model_validate(raw)
+        result = action.call(**{f: getattr(args, f) for f in type(args).model_fields})
+    except Exception as e:  # the model sees the error and can correct itself
+        return f"{type(e).__name__}: {e}", True
+    if action.human:
+        return ("approved" if result else "rejected"), False
+    return (result if isinstance(result, str) else pydantic_core.to_json(result).decode()), False

concordat/agent.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable, Collection, Iterable, Mapping
+from dataclasses import dataclass, replace
+from typing import Any, ClassVar, Concatenate, Generic, ParamSpec, TypeVar, overload
+
+from .budget import Budget
+from .protocol import Protocol, ProtocolError
+from .session import ProtocolViolation, Session
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+Approver = Callable[[str, Any], bool]
+"""Decides a human step: gets the step name and the method's return value, returns approval."""
+
+
+def cli_approver(step: str, request: Any) -> bool:
+    answer = input(f"[{step}] {request}\nApprove? [y/N] ")
+    return answer.strip().lower() in {"y", "yes"}
+
+
+@dataclass(frozen=True)
+class Action:
+    """Something the model may do in the current state: call a tool, or ask a human."""
+
+    name: str
+    description: str
+    call: Callable[..., Any]
+    human: bool
+
+
+class _Step(Generic[P, R]):
+    """An agent method that is also a protocol action, legal only in state ``when``."""
+
+    def __init__(self, fn: Callable[Concatenate[Any, P], Any], when: str, targets: Iterable[str]):
+        self.fn = fn
+        self.when = when
+        self.targets = frozenset(targets)
+        self.name = fn.__name__
+        signature = inspect.signature(fn)
+        self.signature = signature.replace(parameters=list(signature.parameters.values())[1:])
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self.name = name
+
+    @overload
+    def __get__(self, agent: None, owner: type | None = None) -> _Step[P, R]: ...
+    @overload
+    def __get__(self, agent: Agent, owner: type | None = None) -> Callable[P, R]: ...
+    def __get__(
+        self, agent: Agent | None, owner: type | None = None
+    ) -> _Step[P, R] | Callable[P, R]:
+        if agent is None:
+            return self
+
+        @functools.wraps(self.fn)
+        def bound(*args: P.args, **kwargs: P.kwargs) -> R:
+            agent.session.check(self.name)  # before any side effect
+            return self._run(agent, *args, **kwargs)
+
+        bound.__signature__ = self.signature  # type: ignore[attr-defined]  # without self
+        return bound
+
+    def _run(self, agent: Agent, *args: P.args, **kwargs: P.kwargs) -> R:
+        raise NotImplementedError
+
+
+class _Tool(_Step[P, R]):
+    def __init__(
+        self, fn: Callable[Concatenate[Any, P], R], when: str, then: str | Mapping[Any, str]
+    ):
+        super().__init__(fn, when, {then} if isinstance(then, str) else then.values())
+        self.then = then
+
+    def _run(self, agent: Agent, *args: P.args, **kwargs: P.kwargs) -> R:
+        agent.budget.spend(tool_calls=1)
+        result: R = self.fn(agent, *args, **kwargs)
+        agent.session.step(self.name, self._target(result))
+        return result
+
+    def _target(self, result: object) -> str:
+        if isinstance(self.then, str):
+            return self.then
+        try:
+            return self.then[result]
+        except (KeyError, TypeError):
+            raise ProtocolViolation(
+                f"{self.name!r} returned {result!r}, which leads to no state; "
+                f"expected one of {list(self.then)}"
+            ) from None
+
+
+class _Human(_Step[P, bool]):
+    def __init__(
+        self, fn: Callable[Concatenate[Any, P], Any], when: str, approve: str, reject: str
+    ):
+        super().__init__(fn, when, {approve, reject})
+        self.approve = approve
+        self.reject = reject
+
+    def _run(self, agent: Agent, *args: P.args, **kwargs: P.kwargs) -> bool:
+        request = self.fn(agent, *args, **kwargs)
+        approved = agent.approver(self.name, request)
+        agent.session.step(self.name, self.approve if approved else self.reject)
+        return approved
+
+
+def tool(
+    when: str, then: str | Mapping[Any, str]
+) -> Callable[[Callable[Concatenate[Any, P], R]], _Tool[P, R]]:
+    """A tool the model may call in state ``when``.
+
+    ``then`` is the next state, or a mapping from the method's return value to it.
+    """
+
+    def decorate(fn: Callable[Concatenate[Any, P], R]) -> _Tool[P, R]:
+        return _Tool(fn, when, then)
+
+    return decorate
+
+
+def human(
+    when: str, approve: str, reject: str
+) -> Callable[[Callable[Concatenate[Any, P], Any]], _Human[P]]:
+    """A decision a human makes in state ``when``.
+
+    The model may request it, but only the approver decides: the method's return value
+    is shown to the approver, and calling the method returns the decision.
+    """
+
+    def decorate(fn: Callable[Concatenate[Any, P], Any]) -> _Human[P]:
+        return _Human(fn, when, approve, reject)
+
+    return decorate
+
+
+class Agent:
+    """Base class whose ``@tool`` and ``@human`` methods define its protocol.
+
+    Declaring ``final`` makes a class concrete: its protocol is built and checked when
+    the class is defined. Classes without ``final`` are abstract bases to inherit from.
+    """
+
+    instructions: ClassVar[str] = ""  # the system prompt for model-driven runs
+    initial: ClassVar[str] = "start"
+    final: ClassVar[Collection[str]] = ()
+    budget: Budget = Budget()  # a template: each instance gets its own copy
+    protocol: ClassVar[Protocol]
+    _steps: ClassVar[dict[str, _Step[Any, Any]]] = {}
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        steps: dict[str, _Step[Any, Any]] = {}
+        for klass in reversed(cls.__mro__):
+            for name, attr in vars(klass).items():
+                if isinstance(attr, _Step):
+                    steps[name] = attr
+                else:
+                    steps.pop(name, None)  # overridden by a plain method
+        cls._steps = steps
+        if not cls.final:
+            return
+        transitions: dict[str, dict[str, frozenset[str]]] = {}
+        for name, step in steps.items():
+            transitions.setdefault(step.when, {})[name] = step.targets
+        try:
+            cls.protocol = Protocol(cls.initial, transitions, cls.final)
+        except ProtocolError as e:
+            raise ProtocolError(f"{cls.__name__}: {e}") from None
+
+    def __init__(self, approver: Approver = cli_approver) -> None:
+        if not self.final:
+            raise TypeError(f"{type(self).__name__} is abstract: declare its final states")
+        self.approver = approver
+        self.budget = replace(type(self).budget)
+        self.session = Session(self.protocol, self.budget)
+
+    @property
+    def state(self) -> str:
+        return self.session.state
+
+    @property
+    def done(self) -> bool:
+        return self.session.done
+
+    def allowed_tools(self) -> dict[str, Action]:
+        """What the model may do right now; everything else is withheld from it."""
+        actions = {}
+        for name in sorted(self.session.allowed_actions()):
+            step = self._steps[name]
+            description = inspect.getdoc(step.fn) or ""
+            human = isinstance(step, _Human)
+            actions[name] = Action(name, description, getattr(self, name), human)
+        return actions

concordat/anthropic.py

@@ -0,0 +1,126 @@
+"""Run an agent against Claude through the Anthropic SDK (``pip install concordat[anthropic]``)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import anthropic
+
+from ._runner import (
+    RunResult,
+    Status,
+    arguments,
+    cap,
+    charge,
+    description,
+    exhausted,
+    invoke,
+    system_prompt,
+    with_next_step,
+)
+from .agent import Action, Agent
+
+__all__ = ["DEFAULT_MODEL", "FALLBACK_BETA", "RunResult", "run"]
+
+DEFAULT_MODEL = "claude-opus-5-5"
+FALLBACK_BETA = "server-side-fallback-2026-07-01"
+
+
+def run(
+    agent: Agent,
+    client: anthropic.Anthropic,
+    prompt: str | list[Any],
+    *,
+    model: str = DEFAULT_MODEL,
+    max_tokens: int = 16000,
+    max_turns: int = 20,
+    fallbacks: bool = True,
+    **request: Any,
+) -> RunResult:
+    """Drive ``agent`` with Claude until its protocol finishes or a limit is hit.
+
+    Each turn, Claude is offered only the actions legal in the agent's current state,
+    and every response's tokens are charged to ``agent.budget``. ``fallbacks`` re-runs
+    refused requests on Anthropic's recommended fallback model (a beta feature; turn it
+    off on platforms without server-side fallbacks). Extra keyword arguments are passed
+    to ``messages.create``.
+    """
+    messages = [{"role": "user", "content": prompt}] if isinstance(prompt, str) else list(prompt)
+    text = ""
+    for _ in range(max_turns):
+        if agent.done:
+            return RunResult("done", text, messages)
+        budget = agent.budget
+        if exhausted(budget):
+            return RunResult("out_of_budget", text, messages)
+
+        actions = agent.allowed_tools()
+        params: dict[str, Any] = {
+            "model": model,
+            "max_tokens": cap(budget, max_tokens),
+            "messages": messages,
+            "system": system_prompt(agent),
+            **request,
+        }
+        if actions:
+            params["tools"] = [_tool_param(action) for action in actions.values()]
+            # One call per response, so each call sees the state the previous one left.
+            params["tool_choice"] = {"type": "auto", "disable_parallel_tool_use": True}
+        if fallbacks:
+            response: Any = client.beta.messages.create(
+                betas=[FALLBACK_BETA], fallbacks="default", **params
+            )
+        else:
+            response = client.messages.create(**params)
+
+        if response.stop_reason == "refusal":
+            return RunResult("refused", text, messages)
+        messages.append({"role": "assistant", "content": response.content})
+        text = "".join(b.text for b in response.content if b.type == "text") or text
+        calls = [b for b in response.content if b.type == "tool_use"]
+
+        stop: Status | None = None
+        if not charge(budget, _tokens(response.usage)):
+            stop = "out_of_budget"
+        elif response.stop_reason == "max_tokens":
+            stop = "max_tokens"
+        if stop is not None:
+            if calls:  # every tool_use needs a result, or the conversation can't continue
+                results = [_result(c.id, f"Not run: {stop}.", error=True) for c in calls]
+                messages.append({"role": "user", "content": results})
+            return RunResult(stop, text, messages)
+        if not calls:
+            return RunResult("done" if agent.done else "waiting", text, messages)
+
+        results = []
+        for c in calls:
+            content, error = invoke(actions, c.name, c.input)
+            results.append(_result(c.id, with_next_step(agent, content), error))
+        messages.append({"role": "user", "content": results})
+    return RunResult("done" if agent.done else "max_turns", text, messages)
+
+
+def _tokens(usage: Any) -> int:
+    return int(
+        usage.input_tokens
+        + usage.output_tokens
+        + (usage.cache_creation_input_tokens or 0)
+        + (usage.cache_read_input_tokens or 0)
+    )
+
+
+def _tool_param(action: Action) -> dict[str, Any]:
+    return {
+        "name": action.name,
+        "description": description(action),
+        "input_schema": arguments(action).model_json_schema(),
+    }
+
+
+def _result(tool_use_id: str, content: str, error: bool = False) -> dict[str, Any]:
+    return {
+        "type": "tool_result",
+        "tool_use_id": tool_use_id,
+        "content": content,
+        "is_error": error,
+    }

concordat/budget.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_KINDS = ("tokens", "tool_calls", "usd")
+
+
+class BudgetExceeded(RuntimeError):
+    """A spend or split would exceed what is left."""
+
+
+@dataclass
+class Budget:
+    """What a session may still spend. ``None`` means unlimited."""
+
+    tokens: int | None = None
+    tool_calls: int | None = None
+    usd: float | None = None
+
+    def spend(self, *, tokens: int = 0, tool_calls: int = 0, usd: float = 0.0) -> None:
+        """Deduct the amounts, or raise without deducting anything."""
+        amounts = {"tokens": tokens, "tool_calls": tool_calls, "usd": usd}
+        for kind, amount in amounts.items():
+            left = getattr(self, kind)
+            if left is not None and amount > left:
+                raise BudgetExceeded(f"{kind}: need {amount}, {left} left")
+        for kind, amount in amounts.items():
+            left = getattr(self, kind)
+            if left is not None:
+                setattr(self, kind, left - amount)
+
+    def split(
+        self, *, tokens: int | None = None, tool_calls: int | None = None, usd: float | None = None
+    ) -> Budget:
+        """Carve out a child budget, e.g. for a handoff. The parent loses what the child gets."""
+        child = Budget(tokens=tokens, tool_calls=tool_calls, usd=usd)
+        for kind in _KINDS:
+            if getattr(self, kind) is not None and getattr(child, kind) is None:
+                raise BudgetExceeded(f"{kind}: child can't be unlimited when the parent is limited")
+        self.spend(tokens=tokens or 0, tool_calls=tool_calls or 0, usd=usd or 0.0)
+        return child

concordat/openai.py

@@ -0,0 +1,125 @@
+"""Run an agent through the OpenAI Responses API (``pip install concordat[openai]``)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import openai
+
+from ._runner import (
+    RunResult,
+    Status,
+    arguments,
+    cap,
+    charge,
+    description,
+    exhausted,
+    invoke,
+    system_prompt,
+    with_next_step,
+)
+from .agent import Action, Agent
+
+__all__ = ["RunResult", "run"]
+
+
+def run(
+    agent: Agent,
+    client: openai.OpenAI,
+    prompt: str | list[Any],
+    *,
+    model: str,
+    max_output_tokens: int = 16000,
+    max_turns: int = 20,
+    **request: Any,
+) -> RunResult:
+    """Drive ``agent`` with an OpenAI model until its protocol finishes or a limit is hit.
+
+    Each turn, the model is offered only the actions legal in the agent's current state,
+    and every response's tokens are charged to ``agent.budget``. ``messages`` in the
+    result are Responses API input items. Extra keyword arguments are passed to
+    ``responses.create``.
+    """
+    items = [{"role": "user", "content": prompt}] if isinstance(prompt, str) else list(prompt)
+    text = ""
+    for _ in range(max_turns):
+        if agent.done:
+            return RunResult("done", text, items)
+        budget = agent.budget
+        if exhausted(budget):
+            return RunResult("out_of_budget", text, items)
+
+        actions = agent.allowed_tools()
+        params: dict[str, Any] = {
+            "model": model,
+            "input": items,
+            "max_output_tokens": cap(budget, max_output_tokens),
+            "instructions": system_prompt(agent),
+            **request,
+        }
+        if actions:
+            params["tools"] = [_tool_param(action) for action in actions.values()]
+            # One call per response, so each call sees the state the previous one left.
+            params["tool_choice"] = "auto"
+            params["parallel_tool_calls"] = False
+        response: Any = client.responses.create(**params)
+
+        if _refused(response):
+            return RunResult("refused", text, items)
+        items.extend(response.output)
+        text = response.output_text or text
+        calls = [item for item in response.output if item.type == "function_call"]
+
+        stop: Status | None = None
+        if not charge(budget, response.usage.total_tokens if response.usage else 0):
+            stop = "out_of_budget"
+        elif _incomplete(response) == "max_output_tokens":
+            stop = "max_tokens"
+        if stop is not None:
+            # every function call needs an output, or the conversation can't continue
+            items.extend(_output(c.call_id, f"Not run: {stop}.", error=True) for c in calls)
+            return RunResult(stop, text, items)
+        if not calls:
+            return RunResult("done" if agent.done else "waiting", text, items)
+
+        for c in calls:
+            content, error = invoke(actions, c.name, c.arguments)
+            items.append(_output(c.call_id, with_next_step(agent, content), error))
+    return RunResult("done" if agent.done else "max_turns", text, items)
+
+
+def _tool_param(action: Action) -> dict[str, Any]:
+    return {
+        "type": "function",
+        "name": action.name,
+        "description": description(action),
+        "parameters": arguments(action).model_json_schema(),
+        "strict": False,  # strict mode requires every parameter; arguments are validated here
+    }
+
+
+def _incomplete(response: Any) -> str | None:
+    if response.status != "incomplete" or response.incomplete_details is None:
+        return None
+    reason: str | None = response.incomplete_details.reason
+    return reason
+
+
+def _refused(response: Any) -> bool:
+    if _incomplete(response) == "content_filter":
+        return True
+    return any(
+        part.type == "refusal"
+        for item in response.output
+        if item.type == "message"
+        for part in item.content
+    )
+
+
+def _output(call_id: str, content: str, error: bool = False) -> dict[str, Any]:
+    # Function outputs have no error flag, so errors are marked in the text.
+    return {
+        "type": "function_call_output",
+        "call_id": call_id,
+        "output": f"Error: {content}" if error else content,
+    }

concordat/protocol.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+
+class ProtocolError(ValueError):
+    """The protocol definition is inconsistent."""
+
+
+class Protocol:
+    """States, the actions legal in each state, and where each action may lead.
+
+    Checked when constructed: every state must be reachable from ``initial`` and
+    must still be able to reach a final state, so a session can never get stuck.
+    """
+
+    def __init__(
+        self,
+        initial: str,
+        transitions: Mapping[str, Mapping[str, Iterable[str]]],
+        final: Iterable[str],
+    ) -> None:
+        self.initial = initial
+        self.final = frozenset(final)
+        self.transitions: dict[str, dict[str, frozenset[str]]] = {
+            state: {action: frozenset(targets) for action, targets in actions.items()}
+            for state, actions in transitions.items()
+        }
+        self._check()
+
+    @property
+    def states(self) -> frozenset[str]:
+        targets = (
+            t for actions in self.transitions.values() for ts in actions.values() for t in ts
+        )
+        return frozenset({self.initial, *self.final, *self.transitions, *targets})
+
+    def actions(self, state: str) -> frozenset[str]:
+        return frozenset(self.transitions.get(state, {}))
+
+    def targets(self, state: str, action: str) -> frozenset[str]:
+        return self.transitions.get(state, {}).get(action, frozenset())
+
+    def _check(self) -> None:
+        problems = []
+        if not self.final:
+            problems.append("no final states")
+        for state in sorted(self.final):
+            if self.transitions.get(state):
+                problems.append(f"final state {state!r} has actions")
+        for state, actions in self.transitions.items():
+            for action, targets in actions.items():
+                if not targets:
+                    problems.append(f"action {action!r} in {state!r} leads nowhere")
+
+        reachable = {self.initial}
+        frontier = [self.initial]
+        while frontier:
+            for targets in self.transitions.get(frontier.pop(), {}).values():
+                for target in targets - reachable:
+                    reachable.add(target)
+                    frontier.append(target)
+        if unreachable := self.states - reachable:
+            problems.append(f"unreachable states: {sorted(unreachable)}")
+
+        can_finish = set(self.final)
+        changed = True
+        while changed:
+            changed = False
+            for state, actions in self.transitions.items():
+                if state not in can_finish and any(ts & can_finish for ts in actions.values()):
+                    can_finish.add(state)
+                    changed = True
+        if stuck := self.states - can_finish:
+            problems.append(f"states that can never finish: {sorted(stuck)}")
+
+        if problems:
+            raise ProtocolError("; ".join(problems))

concordat/session.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from .budget import Budget
+from .protocol import Protocol
+
+
+class ProtocolViolation(RuntimeError):
+    """An action that the protocol does not allow in the current state."""
+
+
+class Session:
+    """A live run of a protocol: tracks the state and rejects illegal actions."""
+
+    def __init__(self, protocol: Protocol, budget: Budget | None = None) -> None:
+        self.protocol = protocol
+        self.budget = budget if budget is not None else Budget()
+        self.state = protocol.initial
+        self.history: list[tuple[str, str, str]] = []
+
+    @property
+    def done(self) -> bool:
+        return self.state in self.protocol.final
+
+    def allowed_actions(self) -> frozenset[str]:
+        return self.protocol.actions(self.state)
+
+    def check(self, action: str) -> None:
+        """Raise ``ProtocolViolation`` unless ``action`` is allowed in the current state."""
+        if action not in self.allowed_actions():
+            raise ProtocolViolation(
+                f"{action!r} is not allowed in state {self.state!r}; "
+                f"allowed: {sorted(self.allowed_actions())}"
+            )
+
+    def step(self, action: str, to: str | None = None) -> None:
+        """Take ``action`` and move to ``to`` (optional when the action has one target)."""
+        self.check(action)
+        targets = self.protocol.targets(self.state, action)
+        if to is None and len(targets) == 1:
+            (to,) = targets
+        if to is None or to not in targets:
+            raise ProtocolViolation(
+                f"{action!r} in {self.state!r} can lead to {sorted(targets)}, not {to!r}"
+            )
+        self.history.append((self.state, action, to))
+        self.state = to

concordat-0.0.1.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: concordat
+Version: 0.0.1
+Summary: Typed sessions for AI agents: protocols the runtime enforces on the model.
+Project-URL: Homepage, https://github.com/miladsikaroudi/concordat
+Project-URL: Repository, https://github.com/miladsikaroudi/concordat
+Project-URL: Issues, https://github.com/miladsikaroudi/concordat/issues
+Project-URL: Documentation, https://github.com/miladsikaroudi/concordat/blob/main/docs/design.md
+Author: miladsikaroudi
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,claude,llm,openai,protocols,session types,typestate
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: anthropic
+Requires-Dist: anthropic<2,>=1.12; extra == 'anthropic'
+Provides-Extra: openai
+Requires-Dist: openai<4,>=3.26; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# concordat
+
+**Typed sessions for AI agents.** Agents are objects whose interfaces are protocols,
+and the runtime enforces those protocols on the model.
+
+> Status: pre-alpha. Agent classes, the protocol/session/budget kernel, and runners for
+> Claude (Anthropic) and OpenAI work. See [docs/design.md](https://github.com/miladsikaroudi/concordat/blob/main/docs/design.md).
+
+## Why
+
+"Never refund before verifying identity" usually lives in a prompt and is hoped for.
+Concordat makes it a checked protocol:
+
+- **Protocol fidelity:** the session follows the declared order of turns.
+- **Least privilege per step:** the model only gets the tools legal in the current state.
+- **Bounded spend:** tokens, tool calls and dollars stay within budget, even across handoffs.
+
+## Example
+
+```python
+from concordat import Agent, Budget, human, tool
+
+class RefundAgent(Agent):
+    final = {"refunded", "denied"}
+    budget = Budget(tool_calls=10)
+
+    @tool(when="start", then={True: "verified", False: "denied"})
+    def verify_identity(self, user_id: str) -> bool:
+        return lookup(user_id).verified
+
+    @tool(when="verified", then="awaiting_approval")
+    def propose_refund(self, amount: float) -> float:
+        return amount
+
+    @human(when="awaiting_approval", approve="refunded", reject="denied")
+    def approve_refund(self, amount: float) -> str:
+        return f"Refund ${amount}?"         # shown to the human approver
+
+agent = RefundAgent()          # protocol already checked when the class was defined
+agent.allowed_tools()          # {'verify_identity': ...}: all the model gets to see
+agent.propose_refund(5000)     # ProtocolViolation, raised before the body runs
+```
+
+### Running it with Claude
+
+```bash
+pip install "concordat[anthropic]"
+```
+
+```python
+import anthropic
+from concordat.anthropic import run
+
+result = run(RefundAgent(), anthropic.Anthropic(), "Please refund order A-100.")
+result.status   # "done", or "waiting" if Claude asked the user something
+```
+
+Each turn Claude is offered only the actions legal in the current state (a human
+step appears as a request that only the approver can decide), one call per
+response. Every response's tokens are charged to the agent's budget, and the next
+response is capped to what is left. Illegal or invalid calls go back to Claude as
+errors so it can correct itself. See [examples/refund.py](https://github.com/miladsikaroudi/concordat/blob/main/examples/refund.py).
+
+### Running it with OpenAI
+
+The same loop over the Responses API (`pip install "concordat[openai]"`):
+
+```python
+import openai
+from concordat.openai import run
+
+result = run(RefundAgent(), openai.OpenAI(), "Please refund order A-100.", model="...")
+```
+
+### Without classes
+
+The same protocol, using the kernel directly:
+
+```python
+from concordat import Budget, Protocol, Session
+
+refund = Protocol(
+    "start",
+    {
+        "start": {"verify_identity": {"verified", "denied"}},
+        "verified": {"propose_refund": {"awaiting_approval"}},
+        "awaiting_approval": {"human.approve": {"refunded"}, "human.reject": {"denied"}},
+    },
+    final={"refunded", "denied"},
+)  # checked here: no dead ends, no unreachable states
+
+session = Session(refund, Budget(tokens=50_000, tool_calls=10))
+session.allowed_actions()           # {'verify_identity'}: only these tools go to the model
+session.step("propose_refund")      # ProtocolViolation: not allowed in state 'start'
+```
+
+Handing work to another agent splits the budget, and the parent can't spend it twice:
+
+```python
+child_budget = session.budget.split(tokens=10_000, tool_calls=3)
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run mypy src
+uv run ruff check
+```
+
+## License
+
+Apache-2.0

concordat-0.0.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+concordat/__init__.py,sha256=Wz5UNqaMGKxqfCpKiEXNbGpuch_9ahrAHyVXDJT0kcE,573
+concordat/_runner.py,sha256=vbCrqPGDZcipeuz9lOt9TJb860keS2to4JxUxWgF1ow,3766
+concordat/agent.py,sha256=JxBw19MLARSI3kBSK7r6P_Wzlr9guy71-5Ofyn7n020,7019
+concordat/anthropic.py,sha256=1alIS-YbW8BRBcCOIzf59CVb5__mZuhiqvBH6wgKaiA,4320
+concordat/budget.py,sha256=w8RVwu1OQWumh_cg7cdG3eoNyH3IhxLgMHLwU1Fl4dc,1622
+concordat/openai.py,sha256=M0w9woHeKX5F-8dp8TRTMibiSrGPj0x45GRRqKIuP7s,4168
+concordat/protocol.py,sha256=Ql_SG-cbGr1GT1s8bMaXImh7H1s4CtNwvILCZIVS0Dw,2908
+concordat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+concordat/session.py,sha256=8SBJVycXPAK6RNNlSPgSNYX7lLGBECKzdfRtR3u2NXA,1721
+concordat-0.0.1.dist-info/METADATA,sha256=mK3iQwRZsAg5sY5An3_3Z79fD_3x9ckj2b92obAaz-8,4984
+concordat-0.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+concordat-0.0.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+concordat-0.0.1.dist-info/RECORD,,

concordat-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

concordat-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.