flowai-cli 0.2.0__py3-none-any.whl

flowai/__init__.py

@@ -0,0 +1,72 @@
+"""FlowAI: An open-source, production-ready, extensible Python Agent Harness."""
+
+__version__ = "0.2.0"
+
+from flowai.agents import (
+    Agent,
+    AssistantAgent,
+    CriticAgent,
+    DebatePattern,
+    PlanAndExecutePattern,
+    PlannerAgent,
+    ReflectionPattern,
+    SupervisorAgent,
+    Swarm,
+    ToolAgent,
+)
+from flowai.config import Settings
+from flowai.memory import (
+    BaseMemory,
+    ChromaMemory,
+    ConversationMemory,
+    InMemory,
+    QdrantMemory,
+    ShortTermMemory,
+)
+from flowai.observability import EventBus, StreamEvent, Tracer
+from flowai.providers import (
+    BaseProvider,
+    Message,
+    ProviderResponse,
+    StreamChunk,
+    ToolCall,
+    ToolResult,
+)
+from flowai.tools import BaseTool, ToolRegistry, tool
+from flowai.workflow import END, START, AgentState, Workflow
+
+__all__ = [
+    "Agent",
+    "AssistantAgent",
+    "ToolAgent",
+    "PlannerAgent",
+    "CriticAgent",
+    "SupervisorAgent",
+    "ReflectionPattern",
+    "PlanAndExecutePattern",
+    "DebatePattern",
+    "Swarm",
+    "Workflow",
+    "AgentState",
+    "START",
+    "END",
+    "tool",
+    "BaseTool",
+    "ToolRegistry",
+    "Settings",
+    "BaseProvider",
+    "Message",
+    "ToolCall",
+    "ToolResult",
+    "ProviderResponse",
+    "StreamChunk",
+    "BaseMemory",
+    "InMemory",
+    "ShortTermMemory",
+    "ConversationMemory",
+    "QdrantMemory",
+    "ChromaMemory",
+    "Tracer",
+    "EventBus",
+    "StreamEvent",
+]

flowai/__main__.py

@@ -0,0 +1,8 @@
+"""Allows `python -m flowai`."""
+
+import sys
+
+from flowai.cli.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

flowai/agents/__init__.py

@@ -0,0 +1,21 @@
+"""FlowAI Agent Subsystem."""
+
+from flowai.agents.base import AgentContext, BaseAgent
+from flowai.agents.patterns import DebatePattern, PlanAndExecutePattern, ReflectionPattern, Swarm
+from flowai.agents.specialized import CriticAgent, PlannerAgent, SupervisorAgent, ToolAgent
+from flowai.agents.standard import Agent, AssistantAgent
+
+__all__ = [
+    "BaseAgent",
+    "AgentContext",
+    "Agent",
+    "AssistantAgent",
+    "ToolAgent",
+    "PlannerAgent",
+    "CriticAgent",
+    "SupervisorAgent",
+    "ReflectionPattern",
+    "PlanAndExecutePattern",
+    "DebatePattern",
+    "Swarm",
+]

flowai/agents/base.py

@@ -0,0 +1,61 @@
+"""Base Agent class and execution context."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator, Sequence
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from flowai.memory.base import BaseMemory
+from flowai.observability.events import EventBus
+from flowai.observability.tracer import Tracer
+from flowai.providers.base import BaseProvider, StreamChunk
+from flowai.providers.registry import get_provider
+from flowai.tools.base import BaseTool
+from flowai.tools.registry import ToolRegistry
+
+
+class AgentContext(BaseModel):
+    """Context passed across agent turns."""
+    session_id: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class BaseAgent(ABC):
+    """Abstract Base Class for all agents in FlowAI."""
+
+    def __init__(
+        self,
+        name: str = "Agent",
+        model: str = "gpt-4o",
+        provider: str | BaseProvider = "openai",
+        system_prompt: str = "You are a helpful autonomous AI assistant.",
+        tools: Sequence[BaseTool | Any] | ToolRegistry | None = None,
+        memory: BaseMemory | None = None,
+        max_iterations: int = 10,
+        temperature: float = 0.7,
+        tracer: Tracer | None = None,
+        event_bus: EventBus | None = None,
+    ):
+        self.name = name
+        self.model = model
+        self.provider = get_provider(provider, model=model) if isinstance(provider, str) else provider
+        self.system_prompt = system_prompt
+        self.tools = ToolRegistry(tools) if not isinstance(tools, ToolRegistry) else tools
+        self.memory = memory
+        self.max_iterations = max_iterations
+        self.temperature = temperature
+        self.tracer = tracer or Tracer()
+        self.event_bus = event_bus or EventBus()
+
+    @abstractmethod
+    async def run(self, prompt: str, **kwargs: Any) -> str:
+        """Execute agent reasoning on input prompt and return output."""
+        ...
+
+    @abstractmethod
+    async def stream(self, prompt: str, **kwargs: Any) -> AsyncIterator[StreamChunk]:
+        """Stream response tokens and event deltas."""
+        ...

flowai/agents/patterns/__init__.py

@@ -0,0 +1,11 @@
+"""Multi-agent execution patterns and topologies."""
+
+from flowai.agents.patterns.debate import DebatePattern, Swarm
+from flowai.agents.patterns.reflection import PlanAndExecutePattern, ReflectionPattern
+
+__all__ = [
+    "ReflectionPattern",
+    "PlanAndExecutePattern",
+    "DebatePattern",
+    "Swarm",
+]

flowai/agents/patterns/debate.py

@@ -0,0 +1,79 @@
+"""Debate and Swarm multi-agent interaction topologies."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from flowai.agents.standard import Agent
+
+
+class DebatePattern:
+    """Multi-agent adversarial debate with a judge/moderator."""
+
+    def __init__(self, debater_a: Agent, debater_b: Agent, judge: Agent, rounds: int = 2):
+        self.debater_a = debater_a
+        self.debater_b = debater_b
+        self.judge = judge
+        self.rounds = rounds
+
+    async def execute(self, topic: str) -> dict[str, Any]:
+        transcript = []
+        last_arg_a = await self.debater_a.run(f"Argue IN FAVOR of: {topic}")
+        transcript.append(f"{self.debater_a.name}: {last_arg_a}")
+
+        last_arg_b = await self.debater_b.run(f"Argue AGAINST: {topic}\nOpponent argument: {last_arg_a}")
+        transcript.append(f"{self.debater_b.name}: {last_arg_b}")
+
+        for r in range(1, self.rounds):
+            last_arg_a = await self.debater_a.run(f"Rebut: {last_arg_b}\nTopic: {topic}")
+            transcript.append(f"{self.debater_a.name} (Round {r+1}): {last_arg_a}")
+
+            last_arg_b = await self.debater_b.run(f"Rebut: {last_arg_a}\nTopic: {topic}")
+            transcript.append(f"{self.debater_b.name} (Round {r+1}): {last_arg_b}")
+
+        full_transcript = "\n\n".join(transcript)
+        verdict = await self.judge.run(
+            f"You are the impartial judge of this debate on '{topic}'. Review the transcript and determine the winner and reasoning:\n\n{full_transcript}"
+        )
+
+        return {
+            "transcript": transcript,
+            "verdict": verdict,
+        }
+
+
+class Swarm:
+    """Dynamic agent handoff network where agents can pass execution to peers."""
+
+    def __init__(self, agents: list[Agent], initial_agent: Agent | None = None):
+        self.agents = {a.name: a for a in agents}
+        self.current_agent = initial_agent or agents[0]
+
+    def add_agent(self, agent: Agent) -> None:
+        self.agents[agent.name] = agent
+
+    async def execute(self, prompt: str, max_handoffs: int = 5) -> str:
+        current = self.current_agent
+        current_prompt = prompt
+
+        for _ in range(max_handoffs):
+            # inject peers into context
+            peer_names = [name for name in self.agents.keys() if name != current.name]
+            directive = (
+                f"\n[SYSTEM NOTICE]: If another agent is better suited, respond with 'HANDOFF_TO: <AgentName> <Instructions>'. "
+                f"Available agents: {', '.join(peer_names)}"
+            )
+            response = await current.run(current_prompt + directive)
+
+            if "HANDOFF_TO:" in response:
+                parts = response.split("HANDOFF_TO:", 1)[1].strip().split(" ", 1)
+                target_name = parts[0].strip()
+                handoff_instruction = parts[1].strip() if len(parts) > 1 else current_prompt
+                if target_name in self.agents:
+                    current = self.agents[target_name]
+                    current_prompt = handoff_instruction
+                    continue
+
+            return response
+
+        return f"Completed with agent {current.name}: {response}"

flowai/agents/patterns/reflection.py

@@ -0,0 +1,74 @@
+"""Reflection and Plan-and-Execute multi-agent patterns."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from flowai.agents.specialized import CriticAgent, PlannerAgent
+from flowai.agents.standard import Agent
+
+
+class ReflectionPattern:
+    """Actor-Critic reflection pattern: generate candidate -> critique -> refine."""
+
+    def __init__(self, actor: Agent, critic: CriticAgent, max_rounds: int = 3):
+        self.actor = actor
+        self.critic = critic
+        self.max_rounds = max_rounds
+
+    async def execute(self, task: str) -> dict[str, Any]:
+        current_solution = await self.actor.run(f"Task: {task}\nProvide an initial solution:")
+        history = []
+
+        for round_idx in range(self.max_rounds):
+            evaluation = await self.critic.evaluate(task, current_solution)
+            history.append({
+                "round": round_idx + 1,
+                "solution": current_solution,
+                "critique": evaluation.get("critique"),
+                "is_approved": evaluation.get("is_approved"),
+            })
+
+            if evaluation.get("is_approved"):
+                break
+
+            # Refine solution based on critique
+            refine_prompt = (
+                f"Your previous solution received this critique:\n{evaluation.get('critique')}\n\n"
+                f"Please produce an improved and corrected version of the solution for:\n{task}"
+            )
+            current_solution = await self.actor.run(refine_prompt)
+
+        return {
+            "final_solution": current_solution,
+            "rounds_completed": len(history),
+            "history": history,
+        }
+
+
+class PlanAndExecutePattern:
+    """Planner decomposes task, Worker executes each step sequentially."""
+
+    def __init__(self, planner: PlannerAgent, worker: Agent):
+        self.planner = planner
+        self.worker = worker
+
+    async def execute(self, goal: str) -> dict[str, Any]:
+        plan = await self.planner.create_plan(goal)
+        step_results = []
+        cumulative_context = ""
+
+        for i, step in enumerate(plan, 1):
+            step_prompt = f"Goal: {goal}\nPrevious context:\n{cumulative_context}\nExecute Step {i}: {step}"
+            result = await self.worker.run(step_prompt)
+            step_results.append({"step": step, "output": result})
+            cumulative_context += f"\nStep {i} ({step}) output:\n{result}\n"
+
+        summary_prompt = f"Goal: {goal}\nReview all step outputs and provide a final answer:\n{cumulative_context}"
+        final_answer = await self.worker.run(summary_prompt)
+
+        return {
+            "plan": plan,
+            "step_results": step_results,
+            "final_answer": final_answer,
+        }

flowai/agents/specialized.py

@@ -0,0 +1,87 @@
+"""Specialized agents: ToolAgent, PlannerAgent, CriticAgent, SupervisorAgent."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from flowai.agents.standard import Agent
+
+
+class ToolAgent(Agent):
+    """Agent specialized strictly for executing tools and validating their results."""
+
+    def __init__(self, name: str = "ToolExpert", **kwargs):
+        system_prompt = kwargs.pop(
+            "system_prompt",
+            "You are a Tool Specialist. Always prioritize selecting the right tool, verifying arguments, and validating outputs.",
+        )
+        super().__init__(name=name, system_prompt=system_prompt, **kwargs)
+
+
+class PlannerAgent(Agent):
+    """Agent that decomposes complex user queries into structured sequential steps."""
+
+    def __init__(self, name: str = "Planner", **kwargs):
+        system_prompt = kwargs.pop(
+            "system_prompt",
+            "You are a Strategic Planning Agent. Analyze goals and output clear, numbered step-by-step execution plans.",
+        )
+        super().__init__(name=name, system_prompt=system_prompt, **kwargs)
+
+    async def create_plan(self, goal: str) -> list[str]:
+        prompt = f"Decompose the following goal into discrete execution steps. Output only the steps as a JSON array of strings:\nGoal: {goal}"
+        response = await self.run(prompt)
+        try:
+            start_idx = response.find("[")
+            end_idx = response.rfind("]") + 1
+            if start_idx != -1 and end_idx != -1:
+                return json.loads(response[start_idx:end_idx])
+        except Exception:
+            pass
+        return [s.strip("- ") for s in response.split("\n") if s.strip()]
+
+
+class CriticAgent(Agent):
+    """Agent that reviews, critiques, and suggests refinements to work products."""
+
+    def __init__(self, name: str = "Critic", **kwargs):
+        system_prompt = kwargs.pop(
+            "system_prompt",
+            "You are a Critical Reviewer. Scrutinize logic, identify hallucinations, point out omissions, and propose fixes.",
+        )
+        super().__init__(name=name, system_prompt=system_prompt, **kwargs)
+
+    async def evaluate(self, task: str, solution: str) -> dict[str, Any]:
+        prompt = (
+            f"Evaluate the proposed solution for the given task.\n"
+            f"Task: {task}\n"
+            f"Solution: {solution}\n\n"
+            f"Respond with a JSON object containing: 'is_approved' (boolean), 'score' (1-10), 'critique' (string)."
+        )
+        res = await self.run(prompt)
+        try:
+            start_idx = res.find("{")
+            end_idx = res.rfind("}") + 1
+            if start_idx != -1 and end_idx != -1:
+                return json.loads(res[start_idx:end_idx])
+        except Exception:
+            pass
+        return {"is_approved": True, "score": 8, "critique": res}
+
+
+class SupervisorAgent(Agent):
+    """Agent that orchestrates worker agents and routes queries to the appropriate specialist."""
+
+    def __init__(self, workers: dict[str, Agent] | None = None, name: str = "Supervisor", **kwargs):
+        self.workers = workers or {}
+        worker_descriptions = "\n".join([f"- {name}: {w.system_prompt}" for name, w in self.workers.items()])
+        system_prompt = kwargs.pop(
+            "system_prompt",
+            f"You are the Supervisor. Route questions to the appropriate worker agent:\n{worker_descriptions}\n"
+            f"Respond with the name of the worker agent followed by instructions.",
+        )
+        super().__init__(name=name, system_prompt=system_prompt, **kwargs)
+
+    def register_worker(self, name: str, agent: Agent) -> None:
+        self.workers[name] = agent

flowai/agents/standard.py

@@ -0,0 +1,176 @@
+"""Standard Agent and AssistantAgent implementations."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from flowai.agents.base import BaseAgent
+from flowai.providers.base import BaseProvider, Message, StreamChunk, ToolCall
+
+
+class Agent(BaseAgent):
+    """Core autonomous Agent capable of reasoning, tool execution, and memory recall."""
+
+    def __init__(self, **kwargs: Any):
+        super().__init__(**kwargs)
+        self.messages: list[Message] = [
+            Message(role="system", content=self.system_prompt)
+        ]
+
+    # ---------------------------------------------------------------- helpers
+
+    def switch_model(self, model: str, provider: str | BaseProvider | None = None) -> None:
+        """Switch provider or model mid-conversation while preserving full context history."""
+        from flowai.providers.registry import get_provider
+        self.model = model
+        if provider:
+            self.provider = get_provider(provider, model=model) if isinstance(provider, str) else provider
+        else:
+            # Re-instantiate current provider with new model
+            provider_name = self.provider.__class__.__name__.replace("Provider", "").lower()
+            self.provider = get_provider(provider_name, model=model, api_key=self.provider.api_key, base_url=self.provider.base_url)
+
+    def reset_session(self) -> None:
+        """Clear conversation history back to initial system prompt."""
+        self.messages = [Message(role="system", content=self.system_prompt)]
+
+    def _tool_schemas(self) -> list[dict[str, Any]] | None:
+        if not self.tools or not self.tools.list_tools():
+            return None
+        return self.tools.get_schemas(format="openai")
+
+    async def _recall(self, prompt: str) -> None:
+        """Pull relevant long-term memories into context, if a memory backend is attached."""
+        if not self.memory:
+            return
+        past = await self.memory.search(prompt, limit=5)
+        if past:
+            context_str = "\n".join(f"- [{p.role}] {p.content}" for p in past)
+            self.messages.append(
+                Message(role="system", content=f"Relevant background memories:\n{context_str}")
+            )
+
+    async def _run_tool_calls(self, tool_calls: list[ToolCall]) -> None:
+        """Execute every requested tool call and append its result to the transcript."""
+        for tc in tool_calls:
+            await self.event_bus.publish("tool_start", {"tool": tc.name, "arguments": tc.arguments})
+            output = await self.tools.execute(tc.name, **tc.arguments)
+            output_str = output if isinstance(output, str) else str(output)
+            await self.event_bus.publish("tool_end", {"tool": tc.name, "result": output_str})
+            self.messages.append(
+                Message(role="tool", name=tc.name, tool_call_id=tc.id, content=output_str)
+            )
+
+    # ------------------------------------------------------------------- run
+
+    async def run(self, prompt: str, **kwargs: Any) -> str:
+        span = self.tracer.start_span(f"{self.name}.run", prompt=prompt, model=self.model)
+        await self.event_bus.publish("agent_start", {"agent": self.name, "prompt": prompt, "model": self.model})
+
+        await self._recall(prompt)
+        self.messages.append(Message(role="user", content=prompt))
+
+        final_reply = ""
+        hit_limit = True
+        for iteration in range(1, self.max_iterations + 1):
+            await self.event_bus.publish("agent_iteration", {"iteration": iteration, "agent": self.name})
+
+            response = await self.provider.generate(
+                messages=self.messages,
+                tools=self._tool_schemas(),
+                temperature=self.temperature,
+            )
+
+            self.tracer.record_usage(
+                span,
+                self.model,
+                response.usage.prompt_tokens,
+                response.usage.completion_tokens,
+            )
+
+            # No tool calls means the model has reached its conclusion.
+            if not response.tool_calls:
+                final_reply = response.content
+                self.messages.append(Message(role="assistant", content=final_reply))
+                hit_limit = False
+                break
+
+            self.messages.append(
+                Message(role="assistant", content=response.content, tool_calls=response.tool_calls)
+            )
+            await self._run_tool_calls(response.tool_calls)
+
+        span.finish()
+        await self.event_bus.publish("agent_end", {"agent": self.name, "reply": final_reply})
+
+        if self.memory and final_reply:
+            await self.memory.add(f"User: {prompt}\nAssistant: {final_reply}")
+
+        if hit_limit and not final_reply:
+            return (
+                f"(Stopped after {self.max_iterations} tool-calling iterations without a final answer. "
+                "Raise max_iterations or simplify the task.)"
+            )
+        return final_reply or "(No output generated)"
+
+    # ---------------------------------------------------------------- stream
+
+    async def stream(self, prompt: str, **kwargs: Any) -> AsyncIterator[StreamChunk]:
+        """Stream the answer, running any tools the model asks for along the way.
+
+        Text deltas are yielded as they arrive. When the model asks for tools,
+        they run, their results are appended to the transcript, and the loop
+        continues streaming the next turn, so a streamed session is as capable
+        as a non-streamed one.
+        """
+        span = self.tracer.start_span(f"{self.name}.stream", prompt=prompt, model=self.model)
+        await self.event_bus.publish("agent_start", {"agent": self.name, "prompt": prompt, "model": self.model})
+
+        await self._recall(prompt)
+        self.messages.append(Message(role="user", content=prompt))
+
+        for iteration in range(1, self.max_iterations + 1):
+            await self.event_bus.publish("agent_iteration", {"iteration": iteration, "agent": self.name})
+
+            text_parts: list[str] = []
+            tool_calls: list[ToolCall] = []
+
+            async for chunk in self.provider.stream(
+                messages=self.messages,
+                tools=self._tool_schemas(),
+                temperature=self.temperature,
+            ):
+                if chunk.text_delta:
+                    text_parts.append(chunk.text_delta)
+                    await self.event_bus.publish("token", {"delta": chunk.text_delta})
+                if chunk.tool_call_delta is not None:
+                    tool_calls.append(chunk.tool_call_delta)
+                if chunk.usage:
+                    self.tracer.record_usage(
+                        span, self.model, chunk.usage.prompt_tokens, chunk.usage.completion_tokens
+                    )
+                yield chunk
+
+            reply_text = "".join(text_parts)
+
+            if not tool_calls:
+                if reply_text:
+                    self.messages.append(Message(role="assistant", content=reply_text))
+                break
+
+            self.messages.append(
+                Message(role="assistant", content=reply_text, tool_calls=tool_calls)
+            )
+            await self._run_tool_calls(tool_calls)
+
+        span.finish()
+        await self.event_bus.publish("agent_end", {"agent": self.name, "reply": ""})
+
+
+class AssistantAgent(Agent):
+    """Personalized assistant agent with customizable persona and role."""
+
+    def __init__(self, name: str = "Assistant", persona: str = "Expert AI Consultant", **kwargs):
+        system_prompt = kwargs.pop("system_prompt", f"You are {name}, a {persona}. Provide rigorous, concise, and helpful responses.")
+        super().__init__(name=name, system_prompt=system_prompt, **kwargs)

flowai/cli/__init__.py

@@ -0,0 +1,5 @@
+"""FlowAI CLI Package."""
+
+from flowai.cli.main import main
+
+__all__ = ["main"]