flowra 0.0.1.dev1__py3-none-any.whl

flowra/__init__.py

@@ -0,0 +1,3 @@
+from . import agent, lib, llm, runtime, tools
+
+__all__ = ["agent", "lib", "llm", "runtime", "tools"]

flowra/agent/__init__.py

@@ -0,0 +1,70 @@
+from .agent import Agent
+from .agent_def import (
+    NEW_SCOPE,
+    AbstractAgent,
+    AgentDefinition,
+    AgentDefinitionRef,
+    AgentInstance,
+    AgentRef,
+    AgentResult,
+    Call,
+    CallStepHandler,
+    CreateInstance,
+    Goto,
+    SlotContainer,
+    SlotDef,
+    SlotKind,
+    Spawn,
+    StepAction,
+    StepMeta,
+    StepMethod,
+    StepRef,
+    StepResult,
+    StepSpec,
+    resolve_step_owner,
+    resolve_step_ref,
+)
+from .agent_registry import AgentRegistry, ResolvedAgent
+from .agent_store import AgentStore
+from .compile import compile_agent
+from .interrupt_token import InterruptToken
+from .service_locator import ServiceLocator
+from .step_decorator import step
+from .stored_values import AppendOnlyList, Scalar, slot
+
+__all__ = [
+    "NEW_SCOPE",
+    "AbstractAgent",
+    "Agent",
+    "AgentDefinition",
+    "AgentDefinitionRef",
+    "AgentInstance",
+    "AgentRef",
+    "AgentRegistry",
+    "AgentResult",
+    "AgentStore",
+    "AppendOnlyList",
+    "Call",
+    "CallStepHandler",
+    "CreateInstance",
+    "Goto",
+    "InterruptToken",
+    "ResolvedAgent",
+    "Scalar",
+    "ServiceLocator",
+    "SlotContainer",
+    "SlotDef",
+    "SlotKind",
+    "Spawn",
+    "StepAction",
+    "StepMeta",
+    "StepMethod",
+    "StepRef",
+    "StepResult",
+    "StepSpec",
+    "compile_agent",
+    "resolve_step_owner",
+    "resolve_step_ref",
+    "slot",
+    "step",
+]

flowra/agent/agent.py

@@ -0,0 +1,21 @@
+from typing import Any, ClassVar
+
+from .agent_def import AbstractAgent, AgentDefinitionRef, get_step_tag, set_agent_class
+from .compile import compile_agent
+
+__all__ = ["Agent"]
+
+
+class Agent(AbstractAgent):
+    __slots__ = ("__slot_store__",)
+    __subagents__: ClassVar[dict[str, AgentDefinitionRef]] = {}
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        for attr_name in vars(cls):
+            val = getattr(cls, attr_name, None)
+            if callable(val) and get_step_tag(val) is not None:
+                set_agent_class(val, cls)
+
+        subagents = getattr(cls, "__subagents__", None)
+        cls.__agent_definition__ = compile_agent(cls, subagents)

flowra/agent/agent_def.py

@@ -0,0 +1,213 @@
+import dataclasses
+import enum
+from collections.abc import Awaitable, Callable
+from typing import Any, ClassVar
+
+from .service_locator import ServiceLocator
+from .stored_values import AppendOnlyList, Scalar
+
+__all__ = [
+    "NEW_SCOPE",
+    "AbstractAgent",
+    "AgentDefinition",
+    "AgentDefinitionRef",
+    "AgentInstance",
+    "AgentRef",
+    "AgentResult",
+    "Call",
+    "CallStepHandler",
+    "CreateInstance",
+    "Goto",
+    "SlotContainer",
+    "SlotDef",
+    "SlotKind",
+    "Spawn",
+    "StepAction",
+    "StepMeta",
+    "StepMethod",
+    "StepRef",
+    "StepResult",
+    "StepSpec",
+    "get_step_tag",
+    "resolve_step_owner",
+    "resolve_step_ref",
+    "set_agent_class",
+    "set_step_tag",
+]
+
+_STEP_TAG_ATTR = "__step_tag__"
+_AGENT_CLASS_ATTR = "__agent_class__"
+
+
+def get_step_tag(fn: Callable[..., Any]) -> str | None:
+    return getattr(fn, _STEP_TAG_ATTR, None)
+
+
+def set_step_tag(fn: Callable[..., Any], tag: str) -> None:
+    setattr(fn, _STEP_TAG_ATTR, tag)
+
+
+def set_agent_class(fn: Callable[..., Any], cls: type) -> None:
+    setattr(fn, _AGENT_CLASS_ATTR, cls)
+
+
+def resolve_step_ref(ref: "StepRef") -> str:
+    if isinstance(ref, str):
+        return ref
+    func = getattr(ref, "__func__", ref)
+    tag = getattr(func, _STEP_TAG_ATTR, None)
+    if tag is None:
+        raise TypeError(f"{ref!r} is not a @step-decorated method")
+    return tag
+
+
+def resolve_step_owner(ref: "StepRef") -> type | None:
+    if isinstance(ref, str):
+        return None
+    bound_self = getattr(ref, "__self__", None)
+    if bound_self is not None:
+        return type(bound_self)
+    func = getattr(ref, "__func__", ref)
+    return getattr(func, _AGENT_CLASS_ATTR, None)
+
+
+def _resolve_step_with_agent(step: "StepRef", agent: "AgentRef | None") -> str:
+    if not isinstance(step, str):
+        bound_self = getattr(step, "__self__", None)
+        if bound_self is None and agent is None:
+            msg = (
+                f"Unbound method {step!r} requires explicit agent parameter. "
+                f"Use agent=AgentClass or agent='agent_name', or use bound method self.{step.__name__}"
+            )
+            raise TypeError(msg)
+        step = resolve_step_ref(step)
+    return step
+
+
+class AbstractAgent:
+    __slots__ = ()
+    __agent_definition__: ClassVar["AgentDefinition"]
+
+
+type AgentRef = str | type[AbstractAgent]
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class StepSpec:
+    pass
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class AgentResult:
+    pass
+
+
+class _NewScope(enum.Enum):
+    NEW_SCOPE = "NEW_SCOPE"
+
+
+NEW_SCOPE = _NewScope.NEW_SCOPE
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True, init=False)
+class Goto:
+    agent: AgentRef | None
+    step: str
+    spec: StepSpec | None
+    storage_key: str | _NewScope | None
+
+    def __init__(
+        self,
+        *,
+        step: "StepRef",
+        agent: AgentRef | None = None,
+        spec: StepSpec | None = None,
+        storage_key: str | _NewScope | None = None,
+    ) -> None:
+        object.__setattr__(self, "agent", agent)
+        object.__setattr__(self, "step", _resolve_step_with_agent(step, agent))
+        object.__setattr__(self, "spec", spec)
+        object.__setattr__(self, "storage_key", storage_key)
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True, init=False)
+class Call:
+    agent: AgentRef | None
+    step: str
+    spec: StepSpec | None
+    storage_key: str | _NewScope | None
+
+    def __init__(
+        self,
+        *,
+        step: "StepRef",
+        agent: AgentRef | None = None,
+        spec: StepSpec | None = None,
+        storage_key: str | _NewScope | None = None,
+    ) -> None:
+        object.__setattr__(self, "agent", agent)
+        object.__setattr__(self, "step", _resolve_step_with_agent(step, agent))
+        object.__setattr__(self, "spec", spec)
+        object.__setattr__(self, "storage_key", storage_key)
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True, init=False)
+class Spawn:
+    children: list[Call]
+    then: str
+
+    def __init__(
+        self,
+        *,
+        children: list[Call],
+        then: "StepRef",
+    ) -> None:
+        object.__setattr__(self, "children", children)
+        object.__setattr__(self, "then", resolve_step_ref(then))
+
+
+type StepAction = Goto | Spawn
+type StepResult = StepAction | AgentResult | None
+type StepMethod = Callable[..., StepResult | Awaitable[StepResult]]
+type StepRef = str | StepMethod
+
+type CallStepHandler = Callable[[str, StepSpec | None, list[AgentResult] | None], Awaitable[StepResult]]
+
+type SlotContainer = Scalar | AppendOnlyList
+
+type CreateInstance = Callable[[ServiceLocator, dict[str, SlotContainer]], AgentInstance]
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class AgentInstance:
+    call_step: CallStepHandler
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class StepMeta:
+    step_spec: type[StepSpec] | None = None
+    result_types: frozenset[type[AgentResult]] = frozenset()
+
+
+class SlotKind(enum.StrEnum):
+    SCALAR = "scalar"
+    APPEND_ONLY = "append_only"
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class SlotDef:
+    key: str
+    kind: SlotKind
+    value_type: type
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class AgentDefinition:
+    steps: dict[str, StepMeta]
+    slots: dict[str, SlotDef]
+    type_registry: dict[str, type]
+    create_instance: CreateInstance
+    subagents: "dict[str, AgentDefinitionRef]" = dataclasses.field(default_factory=dict)
+
+
+type AgentDefinitionRef = AgentDefinition | type[AbstractAgent]

flowra/agent/agent_registry.py

@@ -0,0 +1,139 @@
+import dataclasses
+import re
+
+from .agent_def import AbstractAgent, AgentDefinition, AgentDefinitionRef, AgentRef
+
+__all__ = ["AgentRegistry", "ResolvedAgent"]
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class ResolvedAgent:
+    name: str
+    definition: AgentDefinition
+
+
+class AgentRegistry:
+    __VALID_NAME = re.compile(r"^[a-zA-Z0-9_-]+$")
+
+    __slots__ = ("__definitions", "__type_maps")
+
+    def __init__(self, agents: dict[str, AgentDefinitionRef]) -> None:
+        self.__definitions: dict[str, AgentDefinition] = {}
+        self.__type_maps: dict[str, dict[type[AbstractAgent], str]] = {}
+        for name, ref in agents.items():
+            self.__register("", name, ref)
+
+    def resolve(
+        self,
+        ref: AgentRef,
+        *,
+        context: str | None = None,
+    ) -> ResolvedAgent:
+        if isinstance(ref, str):
+            name = self.__resolve_name(ref, context=context)
+            defn = self.__definitions.get(name)
+            if defn is None:
+                raise KeyError(f"Unknown agent: {name!r}")
+            return ResolvedAgent(name=name, definition=defn)
+
+        return self.__resolve_type(ref, context or "")
+
+    def get(self, name: str) -> AgentDefinition:
+        defn = self.__definitions.get(name)
+        if defn is None:
+            raise KeyError(f"Unknown agent: {name!r}")
+        return defn
+
+    def all_definitions(self) -> list[AgentDefinition]:
+        return list(self.__definitions.values())
+
+    def all_named_definitions(self) -> list[tuple[str, AgentDefinition]]:
+        return list(self.__definitions.items())
+
+    def name_for_type(
+        self,
+        agent_type: type[AbstractAgent],
+        *,
+        context: str = "",
+    ) -> str:
+        return self.__resolve_type(agent_type, context).name
+
+    def __register(
+        self,
+        context: str,
+        local_name: str,
+        ref: AgentDefinitionRef,
+    ) -> None:
+        self.__validate_name(local_name)
+        full_name = f"{context}/{local_name}" if context else local_name
+
+        if isinstance(ref, type):
+            agent_def = ref.__agent_definition__
+            type_map = self.__type_maps.setdefault(context, {})
+            if ref in type_map:
+                msg = f"Duplicate agent class {ref.__name__!r} at level {context!r}"
+                raise ValueError(msg)
+            type_map[ref] = local_name
+        else:
+            agent_def = ref
+
+        self.__definitions[full_name] = agent_def
+
+        for subname, subref in agent_def.subagents.items():
+            self.__register(full_name, subname, subref)
+
+    def __resolve_type(
+        self,
+        agent_type: type[AbstractAgent],
+        context: str,
+    ) -> ResolvedAgent:
+        current = context
+        while True:
+            type_map = self.__type_maps.get(current, {})
+            local_name = type_map.get(agent_type)
+            if local_name is not None:
+                full_name = f"{current}/{local_name}" if current else local_name
+                return ResolvedAgent(name=full_name, definition=self.__definitions[full_name])
+            if not current:
+                break
+            slash = current.rfind("/")
+            current = current[:slash] if slash >= 0 else ""
+        msg = f"Unregistered agent class: {agent_type.__name__}"
+        raise KeyError(msg)
+
+    @staticmethod
+    def __resolve_name(ref: str, *, context: str | None) -> str:
+        if not ref.startswith("."):
+            return ref
+
+        if context is None:
+            msg = f"Relative agent reference {ref!r} requires a context"
+            raise ValueError(msg)
+
+        if ref.startswith("./"):
+            suffix = ref[2:]
+            return f"{context}/{suffix}"
+
+        if ref.startswith("../"):
+            parts = context.split("/")
+            remaining = ref
+            while remaining.startswith("../"):
+                remaining = remaining[3:]
+                if not parts or (len(parts) == 1 and parts[0] == ""):
+                    msg = f"Relative reference {ref!r} goes above root from context {context!r}"
+                    raise ValueError(msg)
+                parts.pop()
+            if not remaining:
+                msg = f"Relative reference {ref!r} resolves to a context, not an agent name"
+                raise ValueError(msg)
+            parent = "/".join(parts)
+            return f"{parent}/{remaining}" if parent else remaining
+
+        msg = f"Invalid relative reference {ref!r}: use './' or '../' prefix"
+        raise ValueError(msg)
+
+    @classmethod
+    def __validate_name(cls, name: str) -> None:
+        if not cls.__VALID_NAME.match(name):
+            msg = f"Invalid agent name {name!r}: must contain only alphanumeric characters, underscores, and hyphens"
+            raise ValueError(msg)

flowra/agent/agent_store.py

@@ -0,0 +1,10 @@
+import abc
+
+__all__ = ["AgentStore"]
+
+
+class AgentStore(abc.ABC):
+    __slots__ = ()
+
+    @abc.abstractmethod
+    async def flush(self) -> None: ...