flowent 0.0.0 → 0.0.4

package/backend/src/flowent/models/llm.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ModelCapabilities:
+    input_image: bool = False
+    output_image: bool = False
+
+
+@dataclass
+class ModelInfo:
+    id: str
+    capabilities: ModelCapabilities = field(default_factory=ModelCapabilities)
+    context_window_tokens: int | None = None
+
+
+@dataclass
+class LLMUsage:
+    total_tokens: int
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    cached_input_tokens: int | None = None
+    cache_read_tokens: int | None = None
+    cache_write_tokens: int | None = None
+    details: dict[str, int] = field(default_factory=dict)
+
+
+@dataclass
+class ToolCallResult:
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass
+class LLMOutputTextPart:
+    text: str
+
+
+@dataclass
+class LLMOutputImagePart:
+    data: bytes
+    mime_type: str
+    width: int | None = None
+    height: int | None = None
+
+
+LLMOutputPart = LLMOutputTextPart | LLMOutputImagePart
+
+
+@dataclass
+class LLMResponse:
+    content: str | None = None
+    parts: list[LLMOutputPart] | None = None
+    tool_calls: list[ToolCallResult] | None = None
+    thinking: str | None = None
+    usage: LLMUsage | None = None
+    raw_usage: dict[str, Any] | None = None

package/backend/src/flowent/models/message.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+from flowent.models.content import (
+    ContentPart,
+    content_parts_to_text,
+    deserialize_content_parts,
+)
+
+
+@dataclass
+class Message:
+    from_id: str
+    to_id: str
+    parts: list[ContentPart] = field(default_factory=list)
+    content: str = ""
+    message_id: str | None = None
+    history_recorded: bool = False
+    timestamp: float = field(default_factory=time.time)
+
+    def __post_init__(self) -> None:
+        if self.parts and not self.content:
+            self.content = content_parts_to_text(self.parts)
+        elif self.content and not self.parts:
+            self.parts = deserialize_content_parts(None, fallback_text=self.content)

package/backend/src/flowent/models/tab.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+from flowent.models.graph import WorkflowDefinition
+
+
+@dataclass
+class Tab:
+    id: str
+    title: str
+    leader_id: str | None = None
+    definition: WorkflowDefinition = field(default_factory=WorkflowDefinition)
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+
+    def serialize(self) -> dict[str, object]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "leader_id": self.leader_id,
+            "definition": self.definition.serialize(),
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+        }
+
+    @classmethod
+    def from_mapping(cls, data: dict[str, object]) -> Tab:
+        created_at = data.get("created_at")
+        updated_at = data.get("updated_at")
+        raw_definition = data.get("definition")
+        return cls(
+            id=str(data.get("id", "")),
+            title=str(data.get("title", "")),
+            leader_id=str(data["leader_id"])
+            if isinstance(data.get("leader_id"), str)
+            else None,
+            definition=WorkflowDefinition.from_mapping(
+                raw_definition if isinstance(raw_definition, dict) else None
+            ),
+            created_at=created_at
+            if isinstance(created_at, (int, float))
+            else time.time(),
+            updated_at=updated_at
+            if isinstance(updated_at, (int, float))
+            else time.time(),
+        )

package/backend/src/flowent/models/todo.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from flowent.models.base import Serializable
+
+
+@dataclass
+class TodoItem(Serializable):
+    text: str

package/backend/src/flowent/network.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any, Literal
+
+from curl_cffi.requests import AsyncSession, Session
+from curl_cffi.requests.exceptions import RequestException
+
+DEFAULT_BROWSER_IMPERSONATE: Literal["chrome"] = "chrome"
+
+
+def create_http_session(
+    *,
+    timeout: float,
+    impersonate_browser: bool = False,
+) -> Session:
+    kwargs: dict[str, Any] = {"timeout": timeout}
+    if impersonate_browser:
+        kwargs["impersonate"] = DEFAULT_BROWSER_IMPERSONATE
+    return Session(**kwargs)
+
+
+def create_async_http_session(
+    *,
+    timeout: float,
+    impersonate_browser: bool = False,
+) -> AsyncSession:
+    kwargs: dict[str, Any] = {"timeout": timeout}
+    if impersonate_browser:
+        kwargs["impersonate"] = DEFAULT_BROWSER_IMPERSONATE
+    return AsyncSession(**kwargs)
+
+
+def is_success_status(status_code: int) -> bool:
+    return 200 <= status_code < 300
+
+
+def iter_response_lines(response: Any) -> Iterator[str]:
+    for line in response.iter_lines():
+        normalized = _decode_to_text(line)
+        if normalized:
+            yield normalized
+
+
+def iter_response_text(response: Any) -> Iterator[str]:
+    iter_text = getattr(response, "iter_text", None)
+    if callable(iter_text):
+        for chunk in iter_text():
+            normalized = _decode_to_text(chunk)
+            if normalized:
+                yield normalized
+        return
+
+    for chunk in response.iter_content():
+        normalized = _decode_to_text(chunk)
+        if normalized:
+            yield normalized
+
+
+def read_response_text(response: Any) -> str:
+    text = getattr(response, "text", None)
+    if isinstance(text, str) and text:
+        return text
+
+    content = getattr(response, "content", None)
+    if isinstance(content, str) and content:
+        return content
+    if isinstance(content, (bytes, bytearray)) and content:
+        return bytes(content).decode("utf-8", errors="replace")
+
+    iter_text = getattr(response, "iter_text", None)
+    if callable(iter_text):
+        chunks = [_decode_to_text(chunk) for chunk in iter_text()]
+        if chunks:
+            return "".join(chunks)
+
+    iter_content = getattr(response, "iter_content", None)
+    if callable(iter_content):
+        chunks = [_decode_to_text(chunk) for chunk in iter_content()]
+        if chunks:
+            return "".join(chunks)
+
+    read = getattr(response, "read", None)
+    if callable(read):
+        payload = read()
+        if isinstance(payload, str):
+            return payload
+        if isinstance(payload, (bytes, bytearray)):
+            return bytes(payload).decode("utf-8", errors="replace")
+
+    return ""
+
+
+def get_response_header(response: Any, header_name: str) -> str | None:
+    headers = getattr(response, "headers", None)
+    if headers is None:
+        return None
+    getter = getattr(headers, "get", None)
+    if callable(getter):
+        value = getter(header_name)
+        if isinstance(value, str):
+            return value
+    if isinstance(headers, dict):
+        value = headers.get(header_name) or headers.get(header_name.lower())
+        if isinstance(value, str):
+            return value
+    return None
+
+
+def response_looks_like_html(response: Any) -> bool:
+    content_type = get_response_header(response, "content-type")
+    if not isinstance(content_type, str):
+        return False
+    normalized = content_type.lower()
+    return "text/html" in normalized or "application/xhtml+xml" in normalized
+
+
+def truncate_text(text: str, limit: int = 500) -> str:
+    if len(text) <= limit:
+        return text
+    return text[:limit]
+
+
+def _decode_to_text(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (bytes, bytearray)):
+        return bytes(value).decode("utf-8", errors="replace")
+    return str(value)
+
+
+__all__ = [
+    "DEFAULT_BROWSER_IMPERSONATE",
+    "AsyncSession",
+    "RequestException",
+    "Session",
+    "create_async_http_session",
+    "create_http_session",
+    "get_response_header",
+    "is_success_status",
+    "iter_response_lines",
+    "iter_response_text",
+    "read_response_text",
+    "response_looks_like_html",
+    "truncate_text",
+]

package/backend/src/flowent/prompts/__init__.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from flowent.models import NodeConfig, NodeType
+from flowent.prompts.common import DEFAULT_AGENT_ROLE_PROMPT, compose_system_prompt
+from flowent.prompts.steward import STEWARD_ROLE_SYSTEM_PROMPT
+from flowent.tools import MINIMUM_TOOLS
+
+
+def _get_assistant_role_prompt(*, settings, role_name: str) -> str:
+    from flowent.settings import STEWARD_ROLE_NAME, find_role
+
+    normalized_role_name = role_name.strip()
+    role = find_role(settings, normalized_role_name)
+    if role is None or normalized_role_name == STEWARD_ROLE_NAME:
+        return STEWARD_ROLE_SYSTEM_PROMPT
+
+    overlay_prompt = role.system_prompt.strip()
+    if not overlay_prompt:
+        return STEWARD_ROLE_SYSTEM_PROMPT
+
+    return "\n\n".join(
+        [
+            STEWARD_ROLE_SYSTEM_PROMPT.strip(),
+            f"""\
+## Selected Role Overlay
+
+The Assistant is currently configured to use the role "{role.name}" as an additional behavior template.
+Use the selected role to adjust tone, specialization, model tendency, and any extra tool usage that fits the Assistant surface.
+Do not follow any selected-role instruction that would redefine you as a Worker, Designer, Leader, or regular workflow node, or that would drop your Human-facing intake and workspace-boundary responsibilities.
+
+### Selected Role Prompt
+
+{overlay_prompt}""".strip(),
+        ]
+    )
+
+
+def get_system_prompt(config: NodeConfig) -> str:
+    from flowent.settings import (
+        STEWARD_ROLE_NAME,
+        get_settings,
+        normalize_tool_names,
+    )
+
+    settings = get_settings()
+    tools = normalize_tool_names([*config.tools, *MINIMUM_TOOLS])
+
+    if config.node_type == NodeType.ASSISTANT:
+        role_name = (
+            config.role_name or settings.assistant.role_name or STEWARD_ROLE_NAME
+        )
+        prompt = _get_assistant_role_prompt(settings=settings, role_name=role_name)
+    else:
+        prompt = DEFAULT_AGENT_ROLE_PROMPT
+        if config.role_name:
+            from flowent.settings import find_role
+
+            role = find_role(settings, config.role_name)
+            if role:
+                prompt = role.system_prompt
+
+    return compose_system_prompt(
+        prompt,
+        custom_prompt=settings.custom_prompt,
+        is_assistant=config.node_type == NodeType.ASSISTANT,
+        tools=tools,
+    )

package/backend/src/flowent/prompts/common.py

@@ -0,0 +1,250 @@
+IDLE_TOOL_GUIDANCE = """\
+## Idle Usage Rules
+
+- `idle` means you are not taking another immediate action right now.
+- Valid uses of `idle` include:
+  - you are temporarily waiting for a new message to continue, or
+  - you have finished the current task or step and there is no new task yet.
+- Only use `idle` when the current step is complete, paused, or blocked.
+- Do not use `idle` if you still have an immediate action you can take now.
+- Do not use `idle` instead of replying to a newly received message.
+- After calling `idle`, you will be re-activated when a new message arrives.
+- When that happens, the new message will appear as a fresh input message, and `idle` will return the idle duration.
+"""
+
+SLEEP_TOOL_GUIDANCE = """\
+## Sleep Usage Rules
+
+- Use `sleep(seconds)` only for deliberate fixed-duration waiting.
+- The `seconds` argument is measured in seconds and may be fractional.
+- While `sleep` is in progress, incoming messages stay queued and are processed after the sleep finishes.
+- Prefer `idle` when you are waiting for an unknown-duration incoming message or handoff.
+- `sleep` returns the actual waited duration when it finishes.
+- Do not use `sleep` instead of replying to a newly received message.
+"""
+
+TODO_TOOL_GUIDANCE = """\
+## Todo Tool Rules
+
+- Use `todo` to manage your task checklist and track the current plan or remaining work.
+"""
+
+CREATE_WORKFLOW_TOOL_GUIDANCE = """\
+## Create Workflow Tool Rules
+
+- Use `create_workflow` to open a persistent workflow before building a Workflow Graph for that task.
+- A workflow is the user-visible home for one task. Keep the title concrete and easy to recognize later.
+"""
+
+DELETE_WORKFLOW_TOOL_GUIDANCE = """\
+## Delete Workflow Tool Rules
+
+- Use `delete_workflow` only when the Human explicitly asks to remove a workflow or when you are intentionally cleaning up a task workspace that should no longer exist.
+- Deleting a workflow permanently removes the workflow and its persisted Workflow Graph after active nodes are terminated.
+"""
+
+SET_PERMISSIONS_TOOL_GUIDANCE = """\
+## Set Permissions Tool Rules
+
+- Use `set_permissions` to patch a workflow's permission boundary after the workflow already exists.
+- `set_permissions` updates the target workflow by writing directly to its bound Leader's `allow_network` and `write_dirs`.
+- Treat `allow_network` and `write_dirs` as patch fields: omitted fields stay unchanged.
+- When the Human asks to change a workflow's network or writable directory boundary, prefer `set_permissions` instead of delegating that change to the workflow's Leader.
+"""
+
+CREATE_AGENT_TOOL_GUIDANCE = """\
+## Create Agent Tool Rules
+
+- Use `create_agent` to add a new agent node to the current workflow.
+- Prefer creating the right set of agents up front. If you also have `connect`, wire workflow edges as needed.
+- `create_agent` always creates the new peer in your current workflow. It does not take `workflow_id` or any other cross-workflow target parameter.
+- Ordinary task nodes may use `create_agent` only when that tool was explicitly granted to them.
+- `create_agent` can place the new node as a standalone node, after another node, or between two nodes in the current Workflow Graph.
+- Creating an agent does not start work by itself; explicitly dispatch its first task with `send`.
+- After creating multiple agents, dispatch tasks to all of them before calling `idle`.
+- Do not insert unrelated tool calls or Human-facing text while some planned nodes are still waiting for their first task.
+- When naming an agent via `create_agent`, use title case with spaces (e.g. "Web Researcher", "Code Reviewer", "Data Analyst"). Avoid snake_case, camelCase, or all-lowercase names.
+"""
+
+DELEGATION_GENERAL_GUIDANCE = """\
+## Delegation Rules
+
+- Treat delegation as a first-choice option, not a last resort.
+- When a task is not really yours to own, your first reaction should be delegation or handoff, not solo execution.
+- Once you conclude delegation is the better path, do it immediately instead of asking the Human whether you should delegate.
+- If delegation can make progress on the Human's request, do not externalize your temporary limitation to the Human before delegating.
+- Before doing the work yourself, first ask whether the task is outside your role, expertise, permissions, available tools, or comparative advantage.
+- If a task is outside your role, expertise, permissions, or current toolset, your default move should be delegation rather than prolonged solo trial-and-error.
+- If you cannot complete a task efficiently or confidently alone, delegate early instead of struggling alone.
+- Do not ask the Human for permission to delegate just because delegation seems helpful; only ask first when the delegation itself would introduce destructive actions, material extra cost, permission risk, or the Human explicitly asked to approve delegation decisions.
+- Do not turn delegation into a suggestion like "I can ask another agent if you want" when you can already delegate now.
+- Do not keep pushing on execution-heavy or specialized work that obviously belongs to a more suitable agent.
+- Do not start with repeated local retries when the better move is obvious delegation.
+- Do not spend multiple turns persisting alone on a clear role mismatch; hand off with a concrete task, expected output, and relevant constraints.
+- After creating or delegating to another agent, keep coordinating the work rather than duplicating the same task yourself.
+- Before calling `idle`, check whether delegation, handoff, or creating another agent is the real next action.
+"""
+
+CONNECT_TOOL_GUIDANCE = """\
+## Connect Tool Rules
+
+- Use `connect` to create a directed workflow edge between node ports when the current Workflow Graph needs it.
+"""
+
+CONTACTS_TOOL_GUIDANCE = """\
+## Contacts Tool Rules
+
+- Use `contacts` to inspect the agents you can currently message directly.
+"""
+
+SEND_TOOL_GUIDANCE = """\
+## Send Tool Rules
+
+- Use `send` for every formal node-to-node message.
+- `send` takes exactly one `target` and one ordered `parts` array.
+- Use `contacts` before `send` when you need to inspect reachable target ids or names.
+- `send.parts` preserves order. Keep text and image parts in the sequence you intend the receiver to see.
+- `@target:` and similar text prefixes inside normal content do not send anything.
+- If multiple nodes need messages in the same turn, call `send` multiple times in sequence.
+"""
+
+LIST_ROLES_TOOL_GUIDANCE = """\
+## List Roles Tool Rules
+
+- Use `list_roles` to inspect all registered roles and their included or optional tool configuration before choosing what nodes to create.
+"""
+
+LIST_WORKFLOWS_TOOL_GUIDANCE = """\
+## List Workflows Tool Rules
+
+- Use `list_workflows` to inspect the current persistent workflows.
+- Pass `workflow_id` when you need the detailed node and edge structure for one workflow before changing or continuing its work.
+"""
+
+LIST_TOOLS_TOOL_GUIDANCE = """\
+## List Tools Tool Rules
+
+- Use `list_tools` to inspect all registered tools in the system, not just the tools currently available to you.
+"""
+
+MANAGE_TOOLS_GUIDANCE = """\
+## Management Tool Rules
+
+- `manage_providers` manages provider configuration and model catalogs.
+- `manage_roles` manages role configuration.
+- `manage_settings` reads and updates runtime defaults.
+- `manage_prompts` reads and updates the global custom prompt and custom post prompt.
+- `set_permissions` updates an existing workflow's permission boundary.
+"""
+
+COMMUNICATION_USAGE_GUIDANCE = """\
+## Communication Rules
+
+- Use plain content only for your own direct output. Plain content is never delivered to another node.
+- Use `send` for every formal node-to-node message. Target selection belongs in `send.target`, not in the text body.
+- `send` takes one target at a time. If multiple nodes need messages, call `send` multiple times in sequence.
+- Use `contacts` to discover current contact names and ids before sending.
+- When you finish your assigned task, use `send` to deliver the result to the correct destination before calling `idle`.
+- `@target:` and similar `@name:` text inside normal content are just text. They do not send anything.
+- Do NOT output content just to "think out loud" between tool calls. Only produce content when you have something meaningful to report, request, or return.
+- You receive messages as: <message from="uuid">content</message>
+- Your previously sent messages appear in context as: <message to="uuid">content</message>
+- System context is injected as: <system>content</system>
+"""
+
+FILE_PATH_GUIDANCE = """\
+## File Path Rules
+
+- Always use relative paths for file operations (read, edit, exec). Do not guess absolute paths like /workspace or /home.
+- If you need the absolute working directory, run `pwd` first.
+"""
+
+ASSISTANT_ONLY_PROMPT = """\
+## Assistant-Only Communication Rules
+
+- Your content is pushed directly to the frontend chat panel as your reply to the Human.
+- Plain content is your reply to the Human.
+- If you need to send a message to a connected node instead of the Human, use `send`.
+- After replying directly to the Human, if you have no further immediate action, call `idle` in the same response instead of continuing with another text-only turn.
+- Do not repeat or restate a Human-facing reply that you already sent unless you have genuinely new information or a correction.
+- Entering a waiting state still requires an explicit `idle` tool call.
+"""
+
+DEFAULT_AGENT_ROLE_PROMPT = (
+    "You are a helpful agent. Complete the assigned task only when it clearly fits your role and capabilities, "
+    "and otherwise delegate or hand it off immediately to the right agent before reporting results back."
+)
+
+_MANAGEMENT_TOOL_NAMES = frozenset(
+    {
+        "manage_providers",
+        "manage_roles",
+        "manage_settings",
+        "manage_prompts",
+    }
+)
+
+
+def _normalize_tools(tools: list[str]) -> set[str]:
+    return {tool_name.strip() for tool_name in tools if tool_name.strip()}
+
+
+def _build_conditional_tool_guidance(tools: list[str]) -> list[str]:
+    tool_names = _normalize_tools(tools)
+    parts: list[str] = []
+
+    if "idle" in tool_names:
+        parts.append(IDLE_TOOL_GUIDANCE.strip())
+    if "sleep" in tool_names:
+        parts.append(SLEEP_TOOL_GUIDANCE.strip())
+    if "todo" in tool_names:
+        parts.append(TODO_TOOL_GUIDANCE.strip())
+    if "create_workflow" in tool_names:
+        parts.append(CREATE_WORKFLOW_TOOL_GUIDANCE.strip())
+    if "delete_workflow" in tool_names:
+        parts.append(DELETE_WORKFLOW_TOOL_GUIDANCE.strip())
+    if "set_permissions" in tool_names:
+        parts.append(SET_PERMISSIONS_TOOL_GUIDANCE.strip())
+    if "create_agent" in tool_names:
+        parts.append(CREATE_AGENT_TOOL_GUIDANCE.strip())
+    if "create_agent" in tool_names:
+        parts.append(DELEGATION_GENERAL_GUIDANCE.strip())
+    if "connect" in tool_names:
+        parts.append(CONNECT_TOOL_GUIDANCE.strip())
+    if "contacts" in tool_names:
+        parts.append(CONTACTS_TOOL_GUIDANCE.strip())
+    if "send" in tool_names:
+        parts.append(SEND_TOOL_GUIDANCE.strip())
+    if "list_roles" in tool_names:
+        parts.append(LIST_ROLES_TOOL_GUIDANCE.strip())
+    if "list_workflows" in tool_names:
+        parts.append(LIST_WORKFLOWS_TOOL_GUIDANCE.strip())
+    if "list_tools" in tool_names:
+        parts.append(LIST_TOOLS_TOOL_GUIDANCE.strip())
+    if _MANAGEMENT_TOOL_NAMES & tool_names:
+        parts.append(MANAGE_TOOLS_GUIDANCE.strip())
+    return parts
+
+
+def compose_system_prompt(
+    role_prompt: str,
+    custom_prompt: str = "",
+    is_assistant: bool = False,
+    tools: list[str] | None = None,
+) -> str:
+    custom_prompt_text = custom_prompt.strip()
+    role_specific_prompt = role_prompt.strip()
+
+    parts = [
+        COMMUNICATION_USAGE_GUIDANCE.strip(),
+        FILE_PATH_GUIDANCE.strip(),
+    ]
+    if tools is not None:
+        parts.extend(_build_conditional_tool_guidance(tools))
+    if is_assistant:
+        parts.append(ASSISTANT_ONLY_PROMPT.strip())
+    if custom_prompt_text:
+        parts.append(custom_prompt_text)
+    if role_specific_prompt:
+        parts.append(role_specific_prompt)
+    return "\n\n".join(parts).strip()