aigenos-flow 0.3.0__py3-none-any.whl

aigenos_flow/__init__.py

@@ -0,0 +1,140 @@
+"""aigenos-flow — deterministic conversational flows + a drop-in widget layer.
+
+One package. The deterministic flow engine lives right here at the package
+root; the FastAPI widget server (``aigenos_flow.main`` / ``aigenos_flow.agui``
+/ ``aigenos_flow.integrations``) ships under the ``[server]`` extra.
+
+Quickstart:
+
+    from aigenos_flow import FlowAgent, flow, action
+
+    # skills/file_expense/SKILL.md + handlers.py defines the flow
+    agent = FlowAgent.from_dir("skills/", host=my_host)
+    graph = agent.as_langgraph()
+
+Public API (stable for v0.x):
+
+    FlowAgent                  — load skills, compile to LangGraph
+    @flow                      — decorator: marks the entrypoint of a Skill's flow
+    @action                    — decorator: marks a memoized side-effectful step
+    Context                    — the ``ctx`` passed to flow functions (ask/run/say)
+    FieldSpec                  — typed field declaration (also valid in YAML)
+    Reply, SetField, Correct,  — what the interpreter LLM emits per turn
+        Cancel, StartFlow,
+        OutOfScope, Chitchat
+    FlowState                  — the TypedDict that threads through every node
+    Host                       — Protocol every framework adapter implements
+
+Host adapters live at ``aigenos_flow.hosts`` (``LangGraphHost``, ``TestHost``).
+"""
+from .agent import FlowAgent
+from .context import Context, FlowDone, FlowLink, NeedField
+from .declarative import ActionSpec, AuditSink, ToolRegistry, build_declarative_flow
+from .context import Context, FlowDone, FlowLink, NeedField, NeedFields
+from .decorators import action, flow
+from .fields import FieldSpec, FieldValidationError
+from .host import Host
+from .integration import build_react_with_skills, message_text
+from .interpret import (
+    Cancel,
+    Chitchat,
+    Correct,
+    OutOfScope,
+    Reply,
+    SetField,
+    StartFlow,
+    Turn,
+    TurnInterpretation,
+)
+from .runtime import (
+    FlowStackFrame,
+    FlowState,
+    Message,
+    initial_state,
+)
+from .skills import Skill, SkillFrontmatter, SkillRegistry
+from ._slack_helper import post_to_slack
+from .connectors import (
+    ConnectorAdapter,
+    ConnectorManager,
+    ConnectorResult,
+    ConnectorStore,
+    InvocationContext,
+    ManagedOperation,
+    ParameterSpec,
+    SecretResolver,
+    ToolDescriptor,
+)
+
+# Back-compat aliases — old code that imports SlotSpec / SetSlot / NeedSlot /
+# CommandList still works. Marked DEPRECATED in docs; will be removed in 0.3.
+SlotSpec = FieldSpec
+SlotValidationError = FieldValidationError
+SetSlot = SetField
+NeedSlot = NeedField
+CommandList = TurnInterpretation
+Command = Turn
+
+__all__ = [
+    # high level
+    "FlowAgent",
+    "flow",
+    "action",
+    "build_react_with_skills",
+    "message_text",
+    # core types
+    "Context",
+    "Skill",
+    "SkillFrontmatter",
+    "SkillRegistry",
+    "FieldSpec",
+    "FieldValidationError",
+    # declarative skills
+    "ActionSpec",
+    "ToolRegistry",
+    "AuditSink",
+    "build_declarative_flow",
+    # managed connectors
+    "ConnectorAdapter",
+    "ConnectorManager",
+    "ConnectorResult",
+    "ConnectorStore",
+    "InvocationContext",
+    "ManagedOperation",
+    "ParameterSpec",
+    "SecretResolver",
+    "ToolDescriptor",
+    # interpretation vocabulary
+    "Turn",
+    "TurnInterpretation",
+    "SetField",
+    "Correct",
+    "StartFlow",
+    "Cancel",
+    "OutOfScope",
+    "Chitchat",
+    "Reply",
+    # state
+    "FlowState",
+    "FlowStackFrame",
+    "Message",
+    "initial_state",
+    # exception sentinels
+    "FlowDone",
+    "FlowLink",
+    "NeedField",
+    "NeedFields",
+    # host protocol
+    "Host",
+    # integrations
+    "post_to_slack",
+    # back-compat
+    "SlotSpec",
+    "SlotValidationError",
+    "SetSlot",
+    "NeedSlot",
+    "CommandList",
+    "Command",
+]
+
+__version__ = "0.3.0"

aigenos_flow/_slack_helper.py

@@ -0,0 +1,96 @@
+"""Tiny Slack incoming-webhook helper used by generated skill actions.
+
+Why this lives in the engine: the skill_generator emits handlers.py files
+whose `@action` stubs call ``post_to_slack(...)`` when ``SLACK_WEBHOOK_URL``
+is set in the environment. Generated actions degrade gracefully — without
+the env var they just return their fake_result, so demos still work offline.
+
+Usage in a generated action::
+
+    @action
+    def submit_refund(state):
+        info = post_to_slack(
+            "Refund request",
+            fields={"order_id": state["fields"]["order_id"], "amount": state["fields"]["amount"]},
+        )
+        # info["posted"] is True if a webhook was hit, False otherwise.
+        return {"refund_id": "RFD-4242", "status": "pending", "slack": info}
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+from urllib import error, request
+
+log = logging.getLogger("aigenos_flow.slack")
+
+
+def post_to_slack(
+    title: str,
+    *,
+    fields: dict[str, Any] | None = None,
+    webhook_url: str | None = None,
+    timeout: float = 5.0,
+) -> dict[str, Any]:
+    """Post a formatted message to a Slack incoming webhook.
+
+    Args:
+        title: Bolded header line (e.g. "New refund request").
+        fields: Optional key/value pairs rendered as a bulleted block under the title.
+        webhook_url: Override the SLACK_WEBHOOK_URL env var.
+        timeout: HTTP timeout in seconds.
+
+    Returns:
+        ``{"posted": bool, "status": int | None, "error": str | None}``.
+        Never raises — silent skip when the webhook isn't configured so the
+        demo continues working without any setup.
+    """
+    url = webhook_url or os.getenv("SLACK_WEBHOOK_URL")
+    if not url:
+        log.info("[slack] SLACK_WEBHOOK_URL not set — skipping post")
+        return {"posted": False, "status": None, "error": "SLACK_WEBHOOK_URL not set"}
+
+    # Slack Block Kit payload — renders nicely in the channel.
+    blocks: list[dict[str, Any]] = [
+        {
+            "type": "header",
+            "text": {"type": "plain_text", "text": title, "emoji": True},
+        }
+    ]
+    if fields:
+        field_lines = "\n".join(f"• *{k}:* {v}" for k, v in fields.items())
+        blocks.append(
+            {
+                "type": "section",
+                "text": {"type": "mrkdwn", "text": field_lines},
+            }
+        )
+    blocks.append(
+        {
+            "type": "context",
+            "elements": [
+                {"type": "mrkdwn", "text": "_Posted by an aigenos-flows skill_"},
+            ],
+        }
+    )
+
+    payload = json.dumps({"text": title, "blocks": blocks}).encode("utf-8")
+    req = request.Request(
+        url, data=payload, headers={"content-type": "application/json"}
+    )
+    try:
+        with request.urlopen(req, timeout=timeout) as resp:
+            status = resp.getcode()
+            log.info("[slack] posted %r → status=%s", title, status)
+            return {"posted": True, "status": status, "error": None}
+    except error.HTTPError as exc:
+        log.warning("[slack] post failed: HTTP %s", exc.code)
+        return {"posted": False, "status": exc.code, "error": f"HTTP {exc.code}"}
+    except error.URLError as exc:
+        log.warning("[slack] post failed: %s", exc.reason)
+        return {"posted": False, "status": None, "error": str(exc.reason)}
+    except Exception as exc:  # noqa: BLE001 — never raise to skill code
+        log.exception("[slack] unexpected error")
+        return {"posted": False, "status": None, "error": str(exc)}

aigenos_flow/agent.py

@@ -0,0 +1,177 @@
+"""FlowAgent: loads a skills directory and compiles it to either a
+self-contained LangGraph (via ``as_langgraph()``) or a single node you
+can plug into an existing graph (``turn()``).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .declarative import AuditSink, ToolRegistry
+from .host import Host
+from .runtime import (  # noqa: F401 — FlowState re-exported for type hints
+    FlowState,
+    resume_state_updates,
+    run_turn,
+)
+from .skills import SkillRegistry, load_skills_dir
+
+
+class FlowAgent:
+    """A loaded set of skills plus a host. Knows how to compile itself into
+    different framework targets.
+
+    Two response modes:
+
+    - ``"flex"`` (default): the LLM is asked to always include a natural
+      conversational Reply alongside any structured items. The agent feels
+      like an LLM chatbot whose field-filling flow runs on top.
+    - ``"strict"``: the LLM is asked only to interpret items; Reply is
+      optional. The agent reads more like a form. Use this when latency,
+      cost, or determinism of the assistant's literal words matters.
+    """
+
+    def __init__(
+        self,
+        registry: SkillRegistry,
+        host: Host,
+        *,
+        mode: str = "flex",
+    ):
+        if mode not in {"flex", "strict"}:
+            raise ValueError(f"mode must be 'flex' or 'strict', got {mode!r}")
+        self.registry = registry
+        self.host = host
+        self.mode = mode
+
+    @classmethod
+    def from_dir(
+        cls,
+        skills_dir: Path | str,
+        host: Host,
+        *,
+        mode: str = "flex",
+        tools: Any = None,
+        audit: AuditSink | None = None,
+    ) -> "FlowAgent":
+        """Load a skills directory.
+
+        ``tools`` grants the host tools that declarative ``actions:`` may
+        reference — a list of callables / LangChain tools, a name->fn dict, or a
+        ToolRegistry. Imperative skills (and pure-compute declarative skills)
+        need no tools. ``audit`` overrides the default in-process audit sink.
+        """
+        registry = load_skills_dir(
+            skills_dir, tool_registry=ToolRegistry.from_tools(tools), audit=audit
+        )
+        if len(registry) == 0:
+            raise ValueError(f"no skills found in {skills_dir!r}")
+        return cls(registry=registry, host=host, mode=mode)
+
+    def list_skills(self) -> list[str]:
+        return [s.name for s in self.registry.all()]
+
+    # ----------------------------------------------------------------- LangGraph
+    def as_langgraph(self) -> Any:
+        """Compile to a LangGraph CompiledStateGraph.
+
+        Topology: START -> turn -> (done -> END) or (awaiting_user -> wait -> turn).
+
+        The turn/wait split is required so messages emitted before
+        interrupt() are checkpointed (interrupt raises before the node
+        returns, so a single node would lose them).
+        """
+        try:
+            from langgraph.graph import END, START, StateGraph
+            from langgraph.types import interrupt
+        except ImportError as e:  # pragma: no cover
+            raise ImportError(
+                "as_langgraph() requires `langgraph` to be installed. "
+                "pip install langgraph"
+            ) from e
+
+        registry = self.registry
+        host = self.host
+        mode = self.mode
+
+        def turn_node(state: FlowState) -> dict[str, Any]:
+            state = run_turn(state, registry, host, mode=mode)
+            pending = host.drain_pending_messages()
+            updates: dict[str, Any] = {
+                "flow_id": state.get("flow_id"),
+                "fields": state.get("fields", {}),
+                "results": state.get("results", {}),
+                "say_cursor": state.get("say_cursor", 0),
+                "field_history": state.get("field_history", {}),
+                "history": state.get("history", []),
+                "pending_user_message": None,
+                # Always clear the widget-bypass key: run_turn consumes it and
+                # sets it to None on the state object, but the node's return
+                # dict is what LangGraph checkpoints — omitting it would leave a
+                # stale submission to re-fire next turn (the old confirm-loop).
+                "pending_field_updates": None,
+                "pending_assistant_messages": pending,
+                "pending_widget": state.get("pending_widget"),
+                "awaiting_user": bool(state.get("awaiting_user")),
+                "awaiting_field": state.get("awaiting_field"),
+                "flow_stack": state.get("flow_stack", []),
+                "done": bool(state.get("done")),
+                # Chat-leaf + effect-dedup state must survive checkpointing:
+                # chat routing reads chat_config on the NEXT turn, and the
+                # no-double-spend guard is keyed on flow_run_id in effects_log.
+                "chat_config": state.get("chat_config"),
+                "flow_run_id": state.get("flow_run_id"),
+                "effects_log": state.get("effects_log", {}),
+            }
+            if pending:
+                updates["history"] = list(updates["history"]) + [
+                    {"role": "assistant", "content": p} for p in pending
+                ]
+            return updates
+
+        def wait_node(state: FlowState) -> dict[str, Any]:
+            pending = state.get("pending_assistant_messages") or []
+            prompt = (
+                pending[-1]
+                if pending
+                else f"Please provide {state.get('awaiting_field', 'input')}."
+            )
+            user_input = interrupt(
+                {
+                    "prompt": prompt,
+                    "messages": list(pending),
+                    "field": state.get("awaiting_field"),
+                    "flow_id": state.get("flow_id"),
+                }
+            )
+            # Shared routing: dict → structured widget submission (LLM bypass),
+            # str → free-form message. See runtime.resume_state_updates.
+            return {**resume_state_updates(user_input), "pending_assistant_messages": []}
+
+        def route(state: FlowState) -> str:
+            if state.get("done"):
+                return "end"
+            if state.get("awaiting_user"):
+                return "wait"
+            return "end"
+
+        graph = StateGraph(FlowState)
+        graph.add_node("turn", turn_node)
+        graph.add_node("wait", wait_node)
+        graph.add_edge(START, "turn")
+        graph.add_conditional_edges("turn", route, {"wait": "wait", "end": END})
+        graph.add_edge("wait", "turn")
+
+        return graph.compile(
+            checkpointer=getattr(host, "checkpointer", None),
+        )
+
+    # ----------------------------------------------------------------- bare runtime
+    def turn(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Single-shot interface that doesn't require LangGraph at all.
+
+        Useful for tests and for embedding into any framework that doesn't
+        provide a checkpointed graph runtime. The caller is responsible for
+        persisting ``state`` between turns.
+        """
+        return run_turn(state, self.registry, self.host, mode=self.mode)  # type: ignore[arg-type]

aigenos_flow/agui/events.py

@@ -0,0 +1,135 @@
+"""AG-UI protocol event types.
+
+Subset of the AG-UI spec sufficient for text streaming + generative-UI tool
+calls. Frontend renders widgets by treating TOOL_CALL_* events whose tool name
+is `render_widget` as widget render requests.
+"""
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+def _ts() -> int:
+    return int(time.time() * 1000)
+
+
+def _id() -> str:
+    return uuid.uuid4().hex
+
+
+class BaseEvent(BaseModel):
+    type: str
+    timestamp: int = Field(default_factory=_ts)
+    raw_event: dict[str, Any] | None = None
+
+
+class RunStarted(BaseEvent):
+    type: Literal["RUN_STARTED"] = "RUN_STARTED"
+    thread_id: str
+    run_id: str
+
+
+class RunFinished(BaseEvent):
+    type: Literal["RUN_FINISHED"] = "RUN_FINISHED"
+    thread_id: str
+    run_id: str
+
+
+class RunError(BaseEvent):
+    type: Literal["RUN_ERROR"] = "RUN_ERROR"
+    message: str
+    code: str | None = None
+
+
+class StepStarted(BaseEvent):
+    type: Literal["STEP_STARTED"] = "STEP_STARTED"
+    step_name: str
+
+
+class StepFinished(BaseEvent):
+    type: Literal["STEP_FINISHED"] = "STEP_FINISHED"
+    step_name: str
+
+
+class TextMessageStart(BaseEvent):
+    type: Literal["TEXT_MESSAGE_START"] = "TEXT_MESSAGE_START"
+    message_id: str
+    role: Literal["assistant"] = "assistant"
+
+
+class TextMessageContent(BaseEvent):
+    type: Literal["TEXT_MESSAGE_CONTENT"] = "TEXT_MESSAGE_CONTENT"
+    message_id: str
+    delta: str
+
+
+class TextMessageEnd(BaseEvent):
+    type: Literal["TEXT_MESSAGE_END"] = "TEXT_MESSAGE_END"
+    message_id: str
+
+
+class ToolCallStart(BaseEvent):
+    type: Literal["TOOL_CALL_START"] = "TOOL_CALL_START"
+    tool_call_id: str
+    tool_call_name: str
+    parent_message_id: str | None = None
+
+
+class ToolCallArgs(BaseEvent):
+    type: Literal["TOOL_CALL_ARGS"] = "TOOL_CALL_ARGS"
+    tool_call_id: str
+    delta: str
+
+
+class ToolCallEnd(BaseEvent):
+    type: Literal["TOOL_CALL_END"] = "TOOL_CALL_END"
+    tool_call_id: str
+
+
+class ToolCallResult(BaseEvent):
+    type: Literal["TOOL_CALL_RESULT"] = "TOOL_CALL_RESULT"
+    tool_call_id: str
+    message_id: str
+    content: str
+    role: Literal["tool"] = "tool"
+
+
+class StateSnapshot(BaseEvent):
+    type: Literal["STATE_SNAPSHOT"] = "STATE_SNAPSHOT"
+    snapshot: dict[str, Any]
+
+
+class StateDelta(BaseEvent):
+    type: Literal["STATE_DELTA"] = "STATE_DELTA"
+    delta: list[dict[str, Any]]
+
+
+class CustomEvent(BaseEvent):
+    type: Literal["CUSTOM"] = "CUSTOM"
+    name: str
+    value: dict[str, Any]
+
+
+AnyEvent = (
+    RunStarted | RunFinished | RunError
+    | StepStarted | StepFinished
+    | TextMessageStart | TextMessageContent | TextMessageEnd
+    | ToolCallStart | ToolCallArgs | ToolCallEnd | ToolCallResult
+    | StateSnapshot | StateDelta | CustomEvent
+)
+
+
+def new_run_id() -> str:
+    return _id()
+
+
+def new_message_id() -> str:
+    return _id()
+
+
+def new_tool_call_id() -> str:
+    return _id()

aigenos_flow/agui/protocols/__init__.py

@@ -0,0 +1,30 @@
+"""Protocol adapters.
+
+Backend speaks AG-UI internally; adapters translate AG-UI events into other
+emerging UI protocols (A2UI, MCP-UI). They produce SSE payloads in the target
+protocol's shape.
+"""
+from __future__ import annotations
+
+from typing import AsyncIterator
+
+from ..events import AnyEvent
+from ..stream import event_to_sse
+from .a2ui import to_a2ui_sse
+from .mcp_ui import to_mcp_ui_sse
+
+
+SUPPORTED = ("ag-ui", "a2ui", "mcp-ui")
+
+
+async def emit(protocol: str, events: AsyncIterator[AnyEvent]) -> AsyncIterator[dict[str, str]]:
+    proto = (protocol or "ag-ui").lower()
+    if proto == "a2ui":
+        async for sse in to_a2ui_sse(events):
+            yield sse
+    elif proto == "mcp-ui":
+        async for sse in to_mcp_ui_sse(events):
+            yield sse
+    else:
+        async for ev in events:
+            yield event_to_sse(ev)

aigenos_flow/agui/protocols/a2ui.py

@@ -0,0 +1,89 @@
+"""A2UI protocol adapter.
+
+A2UI groups events into thinner semantic categories than AG-UI: messages,
+ui_resources (widgets), state. We translate AG-UI tool calls named
+`render_widget` into A2UI `ui_resource` events and stream text deltas as
+`message_delta`. The wire spec is still evolving; this is a best-effort,
+forward-compatible mapping that downstream A2UI clients can consume.
+"""
+from __future__ import annotations
+
+import json
+from typing import AsyncIterator
+
+from ..events import AnyEvent
+
+
+async def to_a2ui_sse(events: AsyncIterator[AnyEvent]) -> AsyncIterator[dict[str, str]]:
+    pending_args: dict[str, str] = {}
+    pending_names: dict[str, str] = {}
+
+    async for ev in events:
+        t = ev.type
+
+        if t == "RUN_STARTED":
+            yield _sse("a2ui.run.start", {"thread_id": ev.thread_id, "run_id": ev.run_id})
+
+        elif t == "RUN_FINISHED":
+            yield _sse("a2ui.run.end", {"thread_id": ev.thread_id, "run_id": ev.run_id})
+
+        elif t == "RUN_ERROR":
+            yield _sse("a2ui.error", {"message": ev.message, "code": ev.code})
+
+        elif t == "TEXT_MESSAGE_START":
+            yield _sse("a2ui.message.start", {"id": ev.message_id, "role": ev.role})
+
+        elif t == "TEXT_MESSAGE_CONTENT":
+            yield _sse("a2ui.message.delta", {"id": ev.message_id, "delta": ev.delta})
+
+        elif t == "TEXT_MESSAGE_END":
+            yield _sse("a2ui.message.end", {"id": ev.message_id})
+
+        elif t == "TOOL_CALL_START":
+            pending_names[ev.tool_call_id] = ev.tool_call_name
+            pending_args[ev.tool_call_id] = ""
+
+        elif t == "TOOL_CALL_ARGS":
+            pending_args[ev.tool_call_id] = pending_args.get(ev.tool_call_id, "") + ev.delta
+
+        elif t == "TOOL_CALL_END":
+            args = pending_args.pop(ev.tool_call_id, "")
+            name = pending_names.pop(ev.tool_call_id, "")
+            try:
+                parsed = json.loads(args) if args else {}
+            except json.JSONDecodeError:
+                parsed = {"_raw": args}
+            if name == "render_widget":
+                yield _sse("a2ui.ui_resource", {
+                    "id": ev.tool_call_id,
+                    "kind": "widget",
+                    "widget_id": parsed.get("widget_id"),
+                    "version": parsed.get("version"),
+                    "spec": parsed.get("spec"),
+                    "submit_schema": parsed.get("submit_schema"),
+                })
+            else:
+                yield _sse("a2ui.tool_call", {"id": ev.tool_call_id, "name": name, "args": parsed})
+
+        elif t == "TOOL_CALL_RESULT":
+            try:
+                content = json.loads(ev.content)
+            except json.JSONDecodeError:
+                content = ev.content
+            yield _sse("a2ui.ui_resource_result", {"id": ev.tool_call_id, "result": content})
+
+        elif t == "STATE_SNAPSHOT":
+            yield _sse("a2ui.state", {"snapshot": ev.snapshot})
+
+        elif t == "STATE_DELTA":
+            yield _sse("a2ui.state.delta", {"delta": ev.delta})
+
+        elif t == "STEP_STARTED":
+            yield _sse("a2ui.step.start", {"name": ev.step_name})
+
+        elif t == "STEP_FINISHED":
+            yield _sse("a2ui.step.end", {"name": ev.step_name})
+
+
+def _sse(event_name: str, data: dict) -> dict[str, str]:
+    return {"event": event_name, "data": json.dumps(data)}