flowai-cli 0.2.0__py3-none-any.whl

flowai/server/app.py

@@ -0,0 +1,133 @@
+"""FastAPI REST and SSE Streaming API Server."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pydantic import BaseModel
+
+try:
+    from fastapi import FastAPI, HTTPException
+    from fastapi.middleware.cors import CORSMiddleware
+    from fastapi.responses import StreamingResponse
+except ImportError:
+    FastAPI = None
+
+from flowai import __version__
+from flowai.agents.standard import Agent
+from flowai.config.settings import Settings
+from flowai.errors import FlowAIError
+from flowai.tools.builtin import default_system_prompt, default_toolset
+from flowai.tools.registry import ToolRegistry
+
+
+class ChatRequest(BaseModel):
+    message: str
+    agent: str = "default"
+    provider: str | None = None
+    model: str | None = None
+    stream: bool = False
+
+
+class AgentCreateRequest(BaseModel):
+    name: str
+    provider: str = "openai"
+    model: str = "gpt-4o"
+    system_prompt: str = "You are a helpful AI assistant."
+
+
+def create_app(settings: Settings | None = None) -> Any:
+    if FastAPI is None:
+        raise ImportError("FastAPI is required to run the server. Install with: pip install 'flowai-cli[server]'")
+
+    cfg = settings or Settings.load()
+    app = FastAPI(title="FlowAI Agent Harness API", version=__version__)
+
+    # Agents here can run shell commands, so only local pages may call the API.
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["http://localhost", "http://127.0.0.1"],
+        allow_origin_regex=r"^http://(localhost|127\.0\.0\.1)(:\d+)?$",
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Active runtime registries
+    tool_registry = ToolRegistry(default_toolset())
+    agents_store: dict[str, Agent] = {
+        "default": Agent(
+            name="DefaultAgent",
+            provider=cfg.provider,
+            model=cfg.model,
+            system_prompt=default_system_prompt(),
+            tools=tool_registry,
+        )
+    }
+
+    @app.get("/health")
+    async def health():
+        return {"status": "ok", "version": __version__, "project": cfg.project_name}
+
+    @app.get("/tools")
+    async def list_tools():
+        return {"tools": tool_registry.get_schemas(format="openai")}
+
+    @app.get("/agents")
+    async def list_agents():
+        return {
+            "agents": [
+                {
+                    "name": a.name,
+                    "model": a.model,
+                    "provider": a.provider.__class__.__name__,
+                    "system_prompt": a.system_prompt,
+                }
+                for a in agents_store.values()
+            ]
+        }
+
+    @app.post("/agents")
+    async def create_agent(req: AgentCreateRequest):
+        agent = Agent(
+            name=req.name,
+            provider=req.provider,
+            model=req.model,
+            system_prompt=req.system_prompt,
+            tools=tool_registry,
+        )
+        agents_store[req.name] = agent
+        return {"message": f"Agent '{req.name}' created successfully."}
+
+    @app.post("/chat")
+    async def chat(req: ChatRequest):
+        agent = agents_store.get(req.agent)
+        if not agent:
+            # instantiate on demand
+            agent = Agent(
+                name=req.agent,
+                provider=req.provider or cfg.provider,
+                model=req.model or cfg.model,
+                tools=tool_registry,
+            )
+            agents_store[req.agent] = agent
+
+        if not req.stream:
+            try:
+                reply = await agent.run(req.message)
+            except FlowAIError as exc:
+                raise HTTPException(status_code=502, detail=str(exc)) from exc
+            return {"reply": reply, "agent": req.agent}
+
+        async def sse_generator():
+            try:
+                async for chunk in agent.stream(req.message):
+                    if chunk.text_delta:
+                        yield f"data: {json.dumps({'token': chunk.text_delta})}\n\n"
+            except FlowAIError as exc:
+                yield f"data: {json.dumps({'error': str(exc)})}\n\n"
+            yield f"data: {json.dumps({'done': True})}\n\n"
+
+        return StreamingResponse(sse_generator(), media_type="text/event-stream")
+
+    return app

flowai/tools/__init__.py

@@ -0,0 +1,39 @@
+"""FlowAI Tool System."""
+
+from flowai.tools.base import BaseTool, ToolDefinition, ToolParameterSchema
+from flowai.tools.builtin import (
+    bash,
+    default_system_prompt,
+    default_toolset,
+    edit_file,
+    fetch_url,
+    glob_files,
+    grep_files,
+    list_dir,
+    python_repl,
+    read_file,
+    search_web,
+    write_file,
+)
+from flowai.tools.decorator import tool
+from flowai.tools.registry import ToolRegistry
+
+__all__ = [
+    "BaseTool",
+    "ToolDefinition",
+    "ToolParameterSchema",
+    "tool",
+    "ToolRegistry",
+    "bash",
+    "python_repl",
+    "search_web",
+    "fetch_url",
+    "read_file",
+    "write_file",
+    "edit_file",
+    "list_dir",
+    "glob_files",
+    "grep_files",
+    "default_toolset",
+    "default_system_prompt",
+]

flowai/tools/base.py

@@ -0,0 +1,56 @@
+"""Base data classes for Tool definitions and schemas."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ToolParameterSchema(BaseModel):
+    """JSON schema representing tool function parameters."""
+    type: str = "object"
+    properties: dict[str, Any] = Field(default_factory=dict)
+    required: list[str] = Field(default_factory=list)
+
+
+class ToolDefinition(BaseModel):
+    """OpenAI/Anthropic compatible tool metadata representation."""
+    name: str
+    description: str
+    parameters: ToolParameterSchema
+
+
+class BaseTool(ABC):
+    """Abstract class for all tools in FlowAI."""
+    name: str
+    description: str
+    schema_definition: ToolDefinition
+    is_async: bool = False
+    # Tools that change the machine (shell, arbitrary code) ask before running.
+    requires_approval: bool = False
+
+    @abstractmethod
+    async def execute(self, **kwargs: Any) -> Any:
+        """Execute the tool with keyword arguments and return the result."""
+        ...
+
+    def to_openai_schema(self) -> dict[str, Any]:
+        """Convert to standard OpenAI function-calling format."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.schema_definition.parameters.model_dump(),
+            },
+        }
+
+    def to_anthropic_schema(self) -> dict[str, Any]:
+        """Convert to Anthropic tool format."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.schema_definition.parameters.model_dump(),
+        }

flowai/tools/builtin.py

@@ -0,0 +1,128 @@
+"""Built-in tools and the default toolset the CLI and server hand to an agent."""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import sys
+from contextlib import redirect_stdout
+
+from flowai.tools.decorator import tool
+from flowai.tools.files import (
+    edit_file,
+    glob_files,
+    grep_files,
+    list_dir,
+    read_file,
+    workspace_root,
+    write_file,
+)
+from flowai.tools.web import fetch_url, search_web
+
+BASH_TIMEOUT_SECONDS = 120
+
+
+@tool("bash", description="Run a shell command in the workspace directory.", requires_approval=True)
+async def bash(command: str) -> str:
+    """Run a shell command and return its combined output."""
+    try:
+        proc = await asyncio.create_subprocess_shell(
+            command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=str(workspace_root()),
+        )
+    except OSError as exc:
+        return f"Failed to start command: {exc}"
+
+    try:
+        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=BASH_TIMEOUT_SECONDS)
+    except asyncio.TimeoutError:
+        proc.kill()
+        await proc.wait()
+        return f"Command timed out after {BASH_TIMEOUT_SECONDS}s and was killed."
+
+    out = stdout.decode(errors="replace").strip()
+    err = stderr.decode(errors="replace").strip()
+    parts = []
+    if out:
+        parts.append(out)
+    if err:
+        parts.append(f"STDERR: {err}")
+    if proc.returncode != 0:
+        parts.append(f"(exit code {proc.returncode})")
+    return "\n".join(parts) or "(no output)"
+
+
+@tool("python_repl", description="Execute Python code in a fresh namespace and return its output.", requires_approval=True)
+def python_repl(code: str) -> str:
+    """Execute Python code and capture standard output."""
+    buffer = io.StringIO()
+    # One namespace for globals and locals: separate ones break comprehensions
+    # and any function that refers to a name defined alongside it.
+    namespace: dict = {"__name__": "__flowai_repl__"}
+    try:
+        with redirect_stdout(buffer):
+            exec(code, namespace)
+    except Exception as exc:
+        captured = buffer.getvalue().strip()
+        error = f"Python execution error: {type(exc).__name__}: {exc}"
+        return f"{captured}\n{error}".strip()
+
+    out = buffer.getvalue().strip()
+    if not out:
+        user_vars = {k: v for k, v in namespace.items() if not k.startswith("__")}
+        if user_vars:
+            name, value = list(user_vars.items())[-1]
+            out = f"{name} = {value!r}"
+    return out or "Executed successfully (no output)."
+
+
+def default_toolset() -> list:
+    """The tools an interactive FlowAI agent gets unless the caller says otherwise."""
+    return [
+        read_file,
+        write_file,
+        edit_file,
+        list_dir,
+        glob_files,
+        grep_files,
+        bash,
+        python_repl,
+        search_web,
+        fetch_url,
+    ]
+
+
+def default_system_prompt(workspace: str | None = None) -> str:
+    """System prompt describing the workspace the built-in tools operate on."""
+    root = workspace or str(workspace_root())
+    return (
+        "You are FlowAI, a terminal coding assistant working inside a user's project.\n"
+        f"The workspace root is: {root}\n"
+        f"The platform is: {sys.platform} (shell commands must be valid for it).\n\n"
+        "Guidelines:\n"
+        "- Inspect before you change: use list_dir, glob_files, grep_files and read_file.\n"
+        "- Prefer edit_file for targeted changes; use write_file only for new or fully rewritten files.\n"
+        "- Paths are relative to the workspace root and must stay inside it.\n"
+        "- Run commands with bash when you need to build, test or inspect the system.\n"
+        "- Never claim you ran something you did not run, and report failures exactly as they occurred.\n"
+        "- Keep answers short and concrete; the user is reading them in a terminal."
+    )
+
+
+__all__ = [
+    "bash",
+    "python_repl",
+    "search_web",
+    "fetch_url",
+    "read_file",
+    "write_file",
+    "edit_file",
+    "list_dir",
+    "glob_files",
+    "grep_files",
+    "default_toolset",
+    "default_system_prompt",
+    "BASH_TIMEOUT_SECONDS",
+]

flowai/tools/decorator.py

@@ -0,0 +1,103 @@
+"""@tool decorator with automatic Pydantic v2 schema generation."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any, get_type_hints
+
+from pydantic import create_model
+
+from flowai.tools.base import BaseTool, ToolDefinition, ToolParameterSchema
+
+
+def tool(
+    name_or_fn: str | Callable | None = None,
+    description: str | None = None,
+    requires_approval: bool = False,
+):
+    """Decorator to turn any standard or async Python function into a FlowAI tool.
+
+    Example:
+        @tool
+        def calculate_tax(amount: float, rate: float = 0.15) -> float:
+            '''Calculate total tax for an amount.'''
+            return amount * rate
+
+        @tool("web_search", description="Search the web for query")
+        async def fetch_results(query: str, max_results: int = 5):
+            ...
+
+    Pass requires_approval=True for a tool that changes the machine; a registry
+    with an approver attached will ask the user before each call.
+    """
+
+    _requires_approval = requires_approval
+
+    def decorator(fn: Callable[..., Any]) -> BaseTool:
+        tool_name = (name_or_fn if isinstance(name_or_fn, str) else None) or fn.__name__
+        raw_doc = fn.__doc__ or ""
+        tool_desc = (description or raw_doc.strip()) or f"Tool {tool_name}"
+
+        # Inspect parameters and types
+        sig = inspect.signature(fn)
+        type_hints = {}
+        try:
+            type_hints = get_type_hints(fn)
+        except Exception:
+            pass
+
+        fields: dict[str, Any] = {}
+        required_fields: list[str] = []
+
+        for param_name, param in sig.parameters.items():
+            if param_name in ("self", "cls"):
+                continue
+            param_type = type_hints.get(param_name, Any)
+            default = ... if param.default == inspect.Parameter.empty else param.default
+            if default is ...:
+                required_fields.append(param_name)
+            fields[param_name] = (param_type, default)
+
+        # Build dynamic Pydantic model for validation & schema generation
+        model_name = f"{tool_name.capitalize()}Args"
+        ArgsModel = create_model(model_name, **fields)
+        json_schema = ArgsModel.model_json_schema()
+
+        param_schema = ToolParameterSchema(
+            type="object",
+            properties=json_schema.get("properties", {}),
+            required=required_fields,
+        )
+
+        tool_def = ToolDefinition(
+            name=tool_name,
+            description=tool_desc,
+            parameters=param_schema,
+        )
+
+        class DecoratedTool(BaseTool):
+            name = tool_name
+            description = tool_desc
+            schema_definition = tool_def
+            is_async = inspect.iscoroutinefunction(fn)
+            requires_approval = _requires_approval
+
+            def __init__(self):
+                self._fn = fn
+                self._args_model = ArgsModel
+
+            async def execute(self, **kwargs: Any) -> Any:
+                validated_args = self._args_model(**kwargs).model_dump()
+                if self.is_async:
+                    return await self._fn(**validated_args)
+                return self._fn(**validated_args)
+
+            def __repr__(self) -> str:
+                return f"<Tool {self.name}: {self.description}>"
+
+        return DecoratedTool()
+
+    if callable(name_or_fn):
+        return decorator(name_or_fn)
+    return decorator

flowai/tools/files.py

@@ -0,0 +1,197 @@
+"""File system tools: the toolkit an agent needs to read and change a project.
+
+Every path is resolved against the workspace root (the directory FlowAI was
+started in, unless FLOWAI_WORKSPACE says otherwise) and must stay inside it.
+That keeps a confused model from reading ~/.ssh or writing outside the project.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import re
+from pathlib import Path
+
+from flowai.tools.decorator import tool
+
+# Files larger than this are refused rather than silently truncating context.
+MAX_READ_BYTES = 400_000
+
+# Directories never worth walking into during glob/grep.
+SKIP_DIRS = {
+    ".git", ".hg", ".svn", "__pycache__", ".venv", "venv", "node_modules",
+    ".mypy_cache", ".pytest_cache", ".ruff_cache", "dist", "build", ".flowai",
+}
+
+
+def workspace_root() -> Path:
+    """The directory the agent is allowed to touch."""
+    return Path(os.getenv("FLOWAI_WORKSPACE", ".")).resolve()
+
+
+def resolve_in_workspace(path: str) -> Path:
+    """Resolve a user/model supplied path, refusing anything outside the workspace."""
+    root = workspace_root()
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        candidate = root / candidate
+    resolved = candidate.resolve()
+    if resolved != root and root not in resolved.parents:
+        raise ValueError(f"Path '{path}' is outside the workspace ({root}).")
+    return resolved
+
+
+def _relative(path: Path) -> str:
+    try:
+        return str(path.relative_to(workspace_root()))
+    except ValueError:
+        return str(path)
+
+
+def _iter_files(root: Path):
+    """Walk the workspace, skipping directories that are never interesting."""
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".")]
+        for filename in filenames:
+            yield Path(dirpath) / filename
+
+
+@tool("read_file", description="Read a text file from the workspace. Returns numbered lines.")
+def read_file(path: str, start_line: int = 1, max_lines: int = 500) -> str:
+    """Read a file and return its contents with line numbers."""
+    target = resolve_in_workspace(path)
+    if not target.exists():
+        return f"Error: '{path}' does not exist."
+    if target.is_dir():
+        return f"Error: '{path}' is a directory. Use list_dir instead."
+    if target.stat().st_size > MAX_READ_BYTES:
+        return f"Error: '{path}' is larger than {MAX_READ_BYTES} bytes. Use grep_files to search it instead."
+
+    try:
+        text = target.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return f"Error: '{path}' is not a UTF-8 text file."
+
+    lines = text.splitlines()
+    start = max(1, start_line)
+    window = lines[start - 1: start - 1 + max_lines]
+    if not window:
+        return f"(no lines at or after line {start}; file has {len(lines)} lines)"
+
+    numbered = "\n".join(f"{start + i:>6}\t{line}" for i, line in enumerate(window))
+    shown_to = start + len(window) - 1
+    if shown_to < len(lines):
+        numbered += f"\n... ({len(lines) - shown_to} more lines; read again with start_line={shown_to + 1})"
+    return numbered
+
+
+@tool("write_file", description="Create or overwrite a text file in the workspace.")
+def write_file(path: str, content: str) -> str:
+    """Write content to a file, creating parent directories as needed."""
+    target = resolve_in_workspace(path)
+    if target.is_dir():
+        return f"Error: '{path}' is a directory."
+    existed = target.exists()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8")
+    verb = "Overwrote" if existed else "Created"
+    return f"{verb} {_relative(target)} ({len(content.splitlines())} lines)."
+
+
+@tool("edit_file", description="Replace an exact string in a workspace file. The string must appear exactly once.")
+def edit_file(path: str, old_text: str, new_text: str) -> str:
+    """Replace one exact occurrence of old_text with new_text."""
+    target = resolve_in_workspace(path)
+    if not target.exists():
+        return f"Error: '{path}' does not exist. Use write_file to create it."
+
+    try:
+        text = target.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return f"Error: '{path}' is not a UTF-8 text file."
+
+    occurrences = text.count(old_text)
+    if occurrences == 0:
+        return f"Error: old_text was not found in '{path}'. Read the file again and copy the text exactly."
+    if occurrences > 1:
+        return f"Error: old_text appears {occurrences} times in '{path}'. Include more surrounding lines to make it unique."
+
+    target.write_text(text.replace(old_text, new_text, 1), encoding="utf-8")
+    line_no = text[: text.index(old_text)].count("\n") + 1
+    return f"Edited {_relative(target)} at line {line_no}."
+
+
+@tool("list_dir", description="List the entries of a directory in the workspace.")
+def list_dir(path: str = ".") -> str:
+    """List files and subdirectories, directories first."""
+    target = resolve_in_workspace(path)
+    if not target.exists():
+        return f"Error: '{path}' does not exist."
+    if not target.is_dir():
+        return f"Error: '{path}' is not a directory."
+
+    entries = sorted(target.iterdir(), key=lambda p: (p.is_file(), p.name.lower()))
+    if not entries:
+        return f"{_relative(target)} is empty."
+
+    lines = []
+    for entry in entries:
+        if entry.name in SKIP_DIRS:
+            continue
+        if entry.is_dir():
+            lines.append(f"{entry.name}/")
+        else:
+            lines.append(f"{entry.name}  ({entry.stat().st_size} bytes)")
+    return "\n".join(lines) or f"{_relative(target)} has no visible entries."
+
+
+@tool("glob_files", description="Find workspace files whose path matches a glob pattern, e.g. '**/*.py'.")
+def glob_files(pattern: str, limit: int = 100) -> str:
+    """Return paths matching a glob pattern, newest first."""
+    root = workspace_root()
+    matches = []
+    for file_path in _iter_files(root):
+        rel = file_path.relative_to(root).as_posix()
+        if fnmatch.fnmatch(rel, pattern) or fnmatch.fnmatch(file_path.name, pattern):
+            matches.append(file_path)
+
+    if not matches:
+        return f"No files match '{pattern}'."
+
+    matches.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    shown = matches[:limit]
+    out = "\n".join(p.relative_to(root).as_posix() for p in shown)
+    if len(matches) > limit:
+        out += f"\n... ({len(matches) - limit} more matches)"
+    return out
+
+
+@tool("grep_files", description="Search workspace file contents with a regular expression.")
+def grep_files(pattern: str, path: str = ".", glob: str = "*", limit: int = 100) -> str:
+    """Search files for a regex and return 'path:line: text' hits."""
+    try:
+        regex = re.compile(pattern)
+    except re.error as exc:
+        return f"Error: invalid regular expression: {exc}"
+
+    root = resolve_in_workspace(path)
+    if root.is_file():
+        candidates = [root]
+    else:
+        candidates = [p for p in _iter_files(root) if fnmatch.fnmatch(p.name, glob)]
+
+    hits: list[str] = []
+    for file_path in candidates:
+        try:
+            if file_path.stat().st_size > MAX_READ_BYTES:
+                continue
+            text = file_path.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue
+        for line_no, line in enumerate(text.splitlines(), 1):
+            if regex.search(line):
+                hits.append(f"{_relative(file_path)}:{line_no}: {line.strip()[:200]}")
+                if len(hits) >= limit:
+                    return "\n".join(hits) + f"\n... (stopped at {limit} matches)"
+
+    return "\n".join(hits) if hits else f"No matches for '{pattern}'."