flowai-cli 0.2.0__py3-none-any.whl

flowai/observability/events.py

@@ -0,0 +1,45 @@
+"""Event Bus and Streaming Event definitions."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class StreamEvent(BaseModel):
+    """Event emitted during execution for observers, webhooks, or SSE."""
+    event: str  # e.g., "token", "tool_start", "tool_end", "agent_start", "error"
+    data: dict[str, Any] = Field(default_factory=dict)
+
+
+EventHandler = Callable[[StreamEvent], Coroutine[Any, Any, None] | None]
+
+
+class EventBus:
+    """Asynchronous publish-subscribe event bus for real-time telemetry."""
+
+    def __init__(self):
+        self._handlers: list[EventHandler] = []
+
+    def subscribe(self, handler: EventHandler) -> None:
+        """Register an observer handler."""
+        self._handlers.append(handler)
+
+    def unsubscribe(self, handler: EventHandler) -> None:
+        """Remove a previously registered handler."""
+        if handler in self._handlers:
+            self._handlers.remove(handler)
+
+    async def publish(self, event_name: str, data: dict[str, Any] | None = None) -> None:
+        """Broadcast an event to all subscribers."""
+        ev = StreamEvent(event=event_name, data=data or {})
+        for handler in self._handlers:
+            try:
+                res = handler(ev)
+                if asyncio.iscoroutine(res):
+                    await res
+            except Exception:
+                pass  # Observers should never crash the core loop

flowai/observability/opentelemetry.py

@@ -0,0 +1,56 @@
+"""OpenTelemetry and LangSmith integration adapters."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from flowai.observability.tracer import Span
+
+
+class OpenTelemetryExporter:
+    """Exports FlowAI spans to standard OpenTelemetry collector / APM."""
+
+    def __init__(self, service_name: str = "flowai-agent", endpoint: str | None = None):
+        self.service_name = service_name
+        self.endpoint = endpoint or os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
+        self._tracer = None
+
+    def export(self, span: Span) -> None:
+        """Export completed span to OTel."""
+        try:
+            from opentelemetry import trace
+            tracer = trace.get_tracer("flowai", "0.1.0")
+            with tracer.start_as_current_span(span.name) as otel_span:
+                otel_span.set_attribute("gen_ai.usage.prompt_tokens", span.prompt_tokens)
+                otel_span.set_attribute("gen_ai.usage.completion_tokens", span.completion_tokens)
+                otel_span.set_attribute("gen_ai.usage.cost_usd", span.cost_usd)
+                for k, v in span.attributes.items():
+                    otel_span.set_attribute(f"flowai.{k}", str(v))
+        except ImportError:
+            pass
+
+
+class LangSmithExporter:
+    """Exports agent traces to LangSmith platform."""
+
+    def __init__(self, project_name: str | None = None):
+        self.project_name = project_name or os.getenv("LANGCHAIN_PROJECT", "flowai-default")
+        self.api_key = os.getenv("LANGCHAIN_API_KEY")
+
+    def export_run(self, name: str, run_type: str, inputs: dict[str, Any], outputs: dict[str, Any], **kwargs: Any) -> None:
+        if not self.api_key:
+            return
+        try:
+            from langsmith import Client
+            client = Client(api_key=self.api_key)
+            client.create_run(
+                name=name,
+                run_type=run_type,
+                inputs=inputs,
+                outputs=outputs,
+                project_name=self.project_name,
+                extra=kwargs,
+            )
+        except Exception:
+            pass

flowai/observability/tracer.py

@@ -0,0 +1,80 @@
+"""Execution Tracer with Token Usage, Cost, and Latency tracking."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+# Pricing per million tokens (estimates in USD)
+MODEL_PRICING: dict[str, dict[str, float]] = {
+    "gpt-4o": {"input": 2.50, "output": 10.00},
+    "gpt-4o-mini": {"input": 0.15, "output": 0.60},
+    "claude-3-5-sonnet-20241022": {"input": 3.00, "output": 15.00},
+    "meta/llama-3.1-70b-instruct": {"input": 0.90, "output": 0.90},
+    "deepseek-ai/deepseek-r1": {"input": 0.55, "output": 2.19},
+    "gemini-2.0-flash": {"input": 0.10, "output": 0.40},
+}
+
+# Used when a model is not in the table above: a visible estimate, not a quote.
+DEFAULT_PRICING = {"input": 1.0, "output": 2.0}
+
+
+class Span(BaseModel):
+    """Represents a single traced execution operation."""
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    name: str
+    start_time: float = Field(default_factory=time.time)
+    end_time: float | None = None
+    duration_ms: float = 0.0
+    attributes: dict[str, Any] = Field(default_factory=dict)
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    cost_usd: float = 0.0
+
+    def finish(self) -> None:
+        self.end_time = time.time()
+        self.duration_ms = (self.end_time - self.start_time) * 1000.0
+
+
+class Tracer:
+    """Manages spans and calculates total resource spend."""
+
+    def __init__(self):
+        self.spans: list[Span] = []
+
+    def start_span(self, name: str, **attributes: Any) -> Span:
+        span = Span(name=name, attributes=attributes)
+        self.spans.append(span)
+        return span
+
+    def record_usage(self, span: Span, model: str, prompt_tokens: int, completion_tokens: int) -> None:
+        """Add one model call's usage to a span.
+
+        Usage accumulates: an agent turn that calls tools makes several model
+        calls inside a single span, and all of them cost money.
+        """
+        span.prompt_tokens += prompt_tokens
+        span.completion_tokens += completion_tokens
+        span.total_tokens = span.prompt_tokens + span.completion_tokens
+
+        pricing = MODEL_PRICING.get(model, DEFAULT_PRICING)
+        cost = (prompt_tokens * pricing["input"] + completion_tokens * pricing["output"]) / 1_000_000.0
+        span.cost_usd = round(span.cost_usd + cost, 6)
+
+    def total_tokens(self) -> int:
+        return sum(s.total_tokens for s in self.spans)
+
+    def total_cost(self) -> float:
+        return sum(s.cost_usd for s in self.spans)
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "total_spans": len(self.spans),
+            "total_tokens": self.total_tokens(),
+            "total_cost_usd": self.total_cost(),
+            "spans": [s.model_dump() for s in self.spans],
+        }

flowai/plugins/__init__.py

@@ -0,0 +1,5 @@
+"""FlowAI Plugin Architecture."""
+
+from flowai.plugins.loader import PluginLoader
+
+__all__ = ["PluginLoader"]

flowai/plugins/loader.py

@@ -0,0 +1,31 @@
+"""FlowAI Plugin interfaces and dynamic entry_points loader."""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+from flowai.providers.base import BaseProvider
+from flowai.providers.registry import ProviderRegistry
+
+
+class PluginLoader:
+    """Discovers and registers external plugins via Python entry points."""
+
+    @staticmethod
+    def load_all() -> dict[str, list[str]]:
+        loaded = {"providers": [], "tools": [], "memory": []}
+
+        # Discover entry_points in 'flowai.plugins'
+        try:
+            entry_points = importlib.metadata.entry_points()
+            flowai_eps = entry_points.select(group="flowai.plugins") if hasattr(entry_points, "select") else entry_points.get("flowai.plugins", [])
+            for ep in flowai_eps:
+                plugin_obj = ep.load()
+                name = ep.name
+                if issubclass(plugin_obj, BaseProvider):
+                    ProviderRegistry.register(name, plugin_obj)
+                    loaded["providers"].append(name)
+        except Exception:
+            pass
+
+        return loaded

flowai/providers/__init__.py

@@ -0,0 +1,35 @@
+"""FlowAI Providers Package."""
+
+from flowai.providers.anthropic import AnthropicProvider
+from flowai.providers.base import (
+    BaseProvider,
+    Message,
+    ProviderResponse,
+    ProviderUsage,
+    StreamChunk,
+    ToolCall,
+    ToolResult,
+)
+from flowai.providers.gemini import GeminiProvider
+from flowai.providers.nvidia import NvidiaProvider
+from flowai.providers.ollama import OllamaProvider
+from flowai.providers.openai import OpenAIProvider, OpenRouterProvider
+from flowai.providers.registry import ProviderRegistry, get_provider
+
+__all__ = [
+    "BaseProvider",
+    "Message",
+    "ToolCall",
+    "ToolResult",
+    "ProviderResponse",
+    "ProviderUsage",
+    "StreamChunk",
+    "NvidiaProvider",
+    "OllamaProvider",
+    "OpenAIProvider",
+    "OpenRouterProvider",
+    "AnthropicProvider",
+    "GeminiProvider",
+    "ProviderRegistry",
+    "get_provider",
+]

flowai/providers/anthropic.py

@@ -0,0 +1,268 @@
+"""Anthropic Claude Provider implementation."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import AsyncIterator, Sequence
+from typing import Any
+
+import httpx
+
+from flowai.errors import ProviderError
+from flowai.providers.base import (
+    BaseProvider,
+    Message,
+    ProviderResponse,
+    ProviderUsage,
+    StreamChunk,
+    ToolCall,
+)
+
+
+class AnthropicProvider(BaseProvider):
+    """Anthropic Provider for the Claude model family."""
+
+    DEFAULT_BASE_URL = "https://api.anthropic.com/v1"
+    api_key_env = "ANTHROPIC_API_KEY"
+
+    def __init__(
+        self,
+        model: str = "claude-sonnet-5-5",
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+        **kwargs: Any,
+    ):
+        resolved_key = api_key or os.getenv("ANTHROPIC_API_KEY", "")
+        resolved_url = base_url or os.getenv("ANTHROPIC_BASE_URL", self.DEFAULT_BASE_URL)
+        super().__init__(
+            model=model,
+            api_key=resolved_key,
+            base_url=resolved_url,
+            timeout=timeout,
+            **kwargs,
+        )
+
+    def _get_headers(self) -> dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "anthropic-version": "2023-06-01",
+        }
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+        return headers
+
+    def _convert_messages(self, messages: Sequence[Message]) -> tuple[str, list[dict[str, Any]]]:
+        system_prompts = []
+        anthropic_messages = []
+
+        for m in messages:
+            if m.role == "system":
+                if m.content:
+                    system_prompts.append(m.content)
+            elif m.role == "tool":
+                anthropic_messages.append({
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": m.tool_call_id,
+                            "content": m.content or "",
+                        }
+                    ],
+                })
+            elif m.role == "assistant":
+                content_blocks: list[dict[str, Any]] = []
+                if m.content:
+                    content_blocks.append({"type": "text", "text": m.content})
+                for tc in m.tool_calls:
+                    content_blocks.append({
+                        "type": "tool_use",
+                        "id": tc.id,
+                        "name": tc.name,
+                        "input": tc.arguments,
+                    })
+                anthropic_messages.append({"role": "assistant", "content": content_blocks})
+            else:
+                anthropic_messages.append({"role": "user", "content": m.content or ""})
+
+        system = "\n\n".join(system_prompts)
+        return system, anthropic_messages
+
+    def _convert_tools(self, tools: Sequence[dict[str, Any]]) -> list[dict[str, Any]]:
+        anthropic_tools = []
+        for t in tools:
+            # Handle standard OpenAI format or direct schema
+            if "function" in t:
+                fn = t["function"]
+                anthropic_tools.append({
+                    "name": fn.get("name"),
+                    "description": fn.get("description", ""),
+                    "input_schema": fn.get("parameters", {"type": "object", "properties": {}}),
+                })
+            else:
+                anthropic_tools.append({
+                    "name": t.get("name"),
+                    "description": t.get("description", ""),
+                    "input_schema": t.get("parameters", {"type": "object", "properties": {}}),
+                })
+        return anthropic_tools
+
+    async def generate(
+        self,
+        messages: Sequence[Message],
+        tools: Sequence[dict[str, Any]] | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> ProviderResponse:
+        url = f"{self.base_url.rstrip('/')}/messages"
+        system, formatted_msgs = self._convert_messages(messages)
+        payload: dict[str, Any] = {
+            "model": self.model,
+            "messages": formatted_msgs,
+            "max_tokens": max_tokens or 4096,
+            "temperature": temperature,
+        }
+        if system:
+            payload["system"] = system
+        if tools:
+            payload["tools"] = self._convert_tools(tools)
+
+        self.require_api_key()
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.post(url, headers=self._get_headers(), json=payload)
+            await self._raise_for_status(resp)
+            data = resp.json()
+
+        text_parts = []
+        tool_calls: list[ToolCall] = []
+        for block in data.get("content", []):
+            if block.get("type") == "text":
+                text_parts.append(block.get("text", ""))
+            elif block.get("type") == "tool_use":
+                tool_calls.append(
+                    ToolCall(
+                        id=block.get("id", ""),
+                        name=block.get("name", ""),
+                        arguments=block.get("input", {}),
+                    )
+                )
+
+        raw_usage = data.get("usage", {})
+        usage = ProviderUsage(
+            prompt_tokens=raw_usage.get("input_tokens", 0),
+            completion_tokens=raw_usage.get("output_tokens", 0),
+            total_tokens=raw_usage.get("input_tokens", 0) + raw_usage.get("output_tokens", 0),
+        )
+
+        return ProviderResponse(
+            content="".join(text_parts),
+            tool_calls=tool_calls,
+            finish_reason=data.get("stop_reason", "end_turn"),
+            usage=usage,
+        )
+
+    async def stream(
+        self,
+        messages: Sequence[Message],
+        tools: Sequence[dict[str, Any]] | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[StreamChunk]:
+        url = f"{self.base_url.rstrip('/')}/messages"
+        system, formatted_msgs = self._convert_messages(messages)
+        payload: dict[str, Any] = {
+            "model": self.model,
+            "messages": formatted_msgs,
+            "max_tokens": max_tokens or 4096,
+            "temperature": temperature,
+            "stream": True,
+        }
+        if system:
+            payload["system"] = system
+        if tools:
+            payload["tools"] = self._convert_tools(tools)
+
+        self.require_api_key()
+        # A tool_use block arrives as a start event, then its input as a run of
+        # partial JSON deltas; it is assembled here and emitted once, complete.
+        pending: dict[int, dict[str, Any]] = {}
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            async with client.stream("POST", url, headers=self._get_headers(), json=payload) as response:
+                await self._raise_for_status(response)
+                async for line in response.aiter_lines():
+                    line = line.strip()
+                    if not line.startswith("data: "):
+                        continue
+                    try:
+                        event = json.loads(line[6:])
+                    except json.JSONDecodeError:
+                        continue
+
+                    ev_type = event.get("type")
+
+                    if ev_type == "content_block_start":
+                        block = event.get("content_block", {})
+                        if block.get("type") == "tool_use":
+                            pending[event.get("index", 0)] = {
+                                "id": block.get("id", ""),
+                                "name": block.get("name", ""),
+                                "json": "",
+                            }
+
+                    elif ev_type == "content_block_delta":
+                        delta = event.get("delta", {})
+                        if delta.get("type") == "text_delta":
+                            yield StreamChunk(text_delta=delta.get("text", ""))
+                        elif delta.get("type") == "input_json_delta":
+                            slot = pending.get(event.get("index", 0))
+                            if slot is not None:
+                                slot["json"] += delta.get("partial_json", "")
+
+                    elif ev_type == "content_block_stop":
+                        slot = pending.pop(event.get("index", 0), None)
+                        if slot:
+                            yield StreamChunk(tool_call_delta=self._assemble_tool_call(slot))
+
+                    elif ev_type == "message_delta":
+                        raw_usage = event.get("usage") or {}
+                        if raw_usage:
+                            yield StreamChunk(
+                                usage=ProviderUsage(
+                                    prompt_tokens=raw_usage.get("input_tokens", 0),
+                                    completion_tokens=raw_usage.get("output_tokens", 0),
+                                    total_tokens=raw_usage.get("input_tokens", 0) + raw_usage.get("output_tokens", 0),
+                                ),
+                                finish_reason=(event.get("delta") or {}).get("stop_reason"),
+                            )
+
+                    elif ev_type == "message_stop":
+                        yield StreamChunk(finish_reason="end_turn")
+
+                    elif ev_type == "error":
+                        detail = (event.get("error") or {}).get("message", "unknown streaming error")
+                        raise ProviderError(self.provider_name, None, detail)
+
+    @staticmethod
+    def _assemble_tool_call(slot: dict[str, Any]) -> ToolCall:
+        """Turn an accumulated tool_use block into a complete ToolCall."""
+        raw = slot.get("json") or ""
+        try:
+            arguments = json.loads(raw) if raw.strip() else {}
+        except json.JSONDecodeError:
+            arguments = {"raw": raw}
+        if not isinstance(arguments, dict):
+            arguments = {"value": arguments}
+        return ToolCall(id=slot.get("id", ""), name=slot.get("name", ""), arguments=arguments)
+
+    async def embeddings(
+        self,
+        texts: list[str],
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> list[list[float]]:
+        raise NotImplementedError("Anthropic does not natively host vector embeddings API; use an embedding provider.")