flowai-cli 0.2.0__py3-none-any.whl

flowai/config/settings.py

@@ -0,0 +1,204 @@
+"""Configuration: global user config, per-project file, and environment variables."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from flowai.errors import ConfigurationError
+
+#: Where `flowai configure` keeps the provider and key chosen once per machine.
+GLOBAL_CONFIG_DIR = Path.home() / ".flowai"
+GLOBAL_CONFIG_PATH = GLOBAL_CONFIG_DIR / "config.json"
+
+#: Project config filenames, in the order they are looked for.
+PROJECT_CONFIG_NAMES = ("flowai.yaml", "flowai.yml", "flowai.toml", "flowai.json")
+
+#: Environment variable holding each provider's key.
+PROVIDER_KEY_ENV = {
+    "anthropic": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "nvidia": "NVIDIA_API_KEY",
+    "gemini": "GEMINI_API_KEY",
+    "openrouter": "OPENROUTER_API_KEY",
+}
+
+#: Model used when a provider is chosen but no model is named.
+PROVIDER_DEFAULT_MODEL = {
+    "anthropic": "claude-sonnet-5-5",
+    "openai": "gpt-4o",
+    "nvidia": "deepseek-ai/deepseek-r1",
+    "gemini": "gemini-2.0-flash",
+    "openrouter": "deepseek/deepseek-r1",
+    "ollama": "llama3.2",
+}
+
+#: Order in which a provider is picked from whatever keys are present.
+PROVIDER_PREFERENCE = ("anthropic", "openai", "nvidia", "gemini", "openrouter")
+
+
+class ProviderConfig(BaseModel):
+    name: str = "openai"
+    model: str = "gpt-4o"
+    api_key: str | None = None
+    api_key_env: str | None = None
+    base_url: str | None = None
+    temperature: float = 0.7
+    max_tokens: int | None = None
+
+
+class MemoryConfig(BaseModel):
+    backend: str = "in_memory"  # in_memory, qdrant, chroma
+    url: str = "http://localhost:6333"
+    collection_name: str = "flowai_memory"
+
+
+class ServerConfig(BaseModel):
+    host: str = "127.0.0.1"
+    port: int = 8000
+    workers: int = 1
+
+
+class MCPServerConfig(BaseModel):
+    """An MCP server to start and borrow tools from."""
+    command: str
+    args: list[str] = Field(default_factory=list)
+    env: dict[str, str] = Field(default_factory=dict)
+    enabled: bool = True
+
+
+class Settings(BaseModel):
+    """Global FlowAI configuration."""
+    project_name: str = "flowai-project"
+    provider: str = "openai"
+    model: str = "gpt-4o"
+    max_iterations: int = 10
+    temperature: float = 0.7
+    #: "ask" prompts before a tool changes the machine; "auto" never prompts.
+    approval: str = "ask"
+    providers: dict[str, ProviderConfig] = Field(default_factory=dict)
+    memory: MemoryConfig = Field(default_factory=MemoryConfig)
+    server: ServerConfig = Field(default_factory=ServerConfig)
+    mcp_servers: dict[str, MCPServerConfig] = Field(default_factory=dict)
+
+    # ------------------------------------------------------------- loading
+
+    @classmethod
+    def load(cls, config_path: str | Path | None = None) -> Settings:
+        """Load settings: global user config, then project file, then environment."""
+        data: dict[str, Any] = {}
+
+        data.update(cls._load_global())
+        project_data, project_path = cls._load_project(config_path)
+        data.update(project_data)
+        if project_path and "project_name" not in project_data:
+            data["project_name"] = project_path.parent.name
+        cls._apply_environment(data)
+
+        return cls(**data)
+
+    @staticmethod
+    def _load_global() -> dict[str, Any]:
+        """Read ~/.flowai/config.json and export any keys it holds to the environment."""
+        if not GLOBAL_CONFIG_PATH.exists():
+            return {}
+        try:
+            data = json.loads(GLOBAL_CONFIG_PATH.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return {}
+        if not isinstance(data, dict):
+            return {}
+        # Provider SDKs and our own providers both read keys from the environment.
+        for key, value in data.items():
+            if key.endswith("_API_KEY") and isinstance(value, str) and not os.getenv(key):
+                os.environ[key] = value
+        return data
+
+    @staticmethod
+    def _load_project(config_path: str | Path | None) -> tuple[dict[str, Any], Path | None]:
+        """Find the nearest project config, walking up from the working directory."""
+        path: Path | None = None
+        if config_path:
+            path = Path(config_path)
+            if not path.exists():
+                raise FileNotFoundError(f"Config file not found: {config_path}")
+        else:
+            for directory in [Path.cwd(), *Path.cwd().parents]:
+                for name in PROJECT_CONFIG_NAMES:
+                    candidate = directory / name
+                    if candidate.is_file():
+                        path = candidate
+                        break
+                if path:
+                    break
+
+        if not path:
+            return {}, None
+
+        content = path.read_text(encoding="utf-8")
+        suffix = path.suffix.lower()
+        if suffix in (".yaml", ".yml"):
+            import yaml
+            parsed = yaml.safe_load(content) or {}
+        elif suffix == ".toml":
+            try:
+                import tomllib
+            except ImportError as exc:  # Python 3.10
+                raise ConfigurationError("flowai.toml needs Python 3.11+; use flowai.yaml instead.") from exc
+            parsed = tomllib.loads(content)
+        else:
+            parsed = json.loads(content)
+
+        if not isinstance(parsed, dict):
+            return {}, path
+        parsed.pop("version", None)
+        return parsed, path
+
+    @staticmethod
+    def _apply_environment(data: dict[str, Any]) -> None:
+        """Environment variables win, and a lone API key is enough to pick a provider."""
+        if os.getenv("FLOWAI_PROVIDER"):
+            data["provider"] = os.getenv("FLOWAI_PROVIDER")
+            data.pop("model", None)
+        elif "provider" not in data:
+            for provider in PROVIDER_PREFERENCE:
+                if os.getenv(PROVIDER_KEY_ENV[provider]):
+                    data["provider"] = provider
+                    break
+
+        provider = data.get("provider")
+        if provider and not data.get("model"):
+            data["model"] = PROVIDER_DEFAULT_MODEL.get(provider, "gpt-4o")
+
+        if os.getenv("FLOWAI_MODEL"):
+            data["model"] = os.getenv("FLOWAI_MODEL")
+
+    # ------------------------------------------------------------- helpers
+
+    def provider_options(self, provider: str | None = None) -> dict[str, Any]:
+        """Keyword arguments for building this provider (key and base URL, if set)."""
+        name = provider or self.provider
+        block = self.providers.get(name)
+        options: dict[str, Any] = {}
+        if not block:
+            return options
+        if block.base_url:
+            options["base_url"] = block.base_url
+        key = block.api_key or (os.getenv(block.api_key_env) if block.api_key_env else None)
+        if key:
+            options["api_key"] = key
+        return options
+
+    def has_credentials(self, provider: str | None = None) -> bool:
+        """True when this provider can actually be called right now."""
+        name = provider or self.provider
+        if name == "ollama":
+            return True
+        if self.provider_options(name).get("api_key"):
+            return True
+        env_name = PROVIDER_KEY_ENV.get(name)
+        return bool(env_name and os.getenv(env_name))

flowai/errors.py

@@ -0,0 +1,30 @@
+"""Error types FlowAI raises, so callers can tell apart what went wrong.
+
+The CLI prints these as a single clear line instead of a traceback: a missing
+API key is a setup problem the user can fix, not a crash.
+"""
+
+from __future__ import annotations
+
+
+class FlowAIError(Exception):
+    """Base class for every error FlowAI raises on purpose."""
+
+
+class ConfigurationError(FlowAIError):
+    """Something the user must set is missing or wrong (API key, provider name)."""
+
+
+class ProviderError(FlowAIError):
+    """An LLM provider rejected the request or returned an error response."""
+
+    def __init__(self, provider: str, status_code: int | None, message: str):
+        self.provider = provider
+        self.status_code = status_code
+        self.message = message
+        where = f"{provider} API" if status_code is None else f"{provider} API (HTTP {status_code})"
+        super().__init__(f"{where}: {message}")
+
+
+class ToolError(FlowAIError):
+    """A tool could not be run at all (as opposed to running and failing)."""

flowai/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""FlowAI MCP Support."""
+
+from flowai.mcp.client import MCPClient
+
+__all__ = ["MCPClient"]

flowai/mcp/client.py

@@ -0,0 +1,77 @@
+"""Model Context Protocol (MCP) Client and Tool Discovery."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from flowai.errors import ToolError
+from flowai.tools.base import BaseTool, ToolDefinition, ToolParameterSchema
+
+
+class MCPClient:
+    """MCP client for stdio servers: lists their tools and adapts them to FlowAI tools.
+
+    Each tool call starts the server, makes the call, and stops it again. That
+    is slower than a held-open session but needs no lifecycle management.
+    """
+
+    def __init__(self, command: str, args: list[str] | None = None, env: dict[str, str] | None = None):
+        self.command = command
+        self.args = args or []
+        self.env = env or {}
+
+    async def connect_and_discover_tools(self) -> list[BaseTool]:
+        """Discover tools exposed by the MCP server and adapt them to FlowAI BaseTools."""
+        tools: list[BaseTool] = []
+        try:
+            from mcp import ClientSession, StdioServerParameters
+            from mcp.client.stdio import stdio_client
+
+            server_params = StdioServerParameters(
+                command=self.command,
+                args=self.args,
+                # None inherits the parent environment; {} would wipe PATH.
+                env={**os.environ, **self.env} if self.env else None,
+            )
+
+            # We create an MCP bridge tool wrapper
+            class MCPRemoteTool(BaseTool):
+                def __init__(self, tool_name: str, desc: str, schema: dict):
+                    self.name = tool_name
+                    self.description = desc
+                    self.schema_definition = ToolDefinition(
+                        name=tool_name,
+                        description=desc,
+                        parameters=ToolParameterSchema(
+                            type="object",
+                            properties=schema.get("properties", {}),
+                            required=schema.get("required", []),
+                        ),
+                    )
+                    self.is_async = True
+                    # An external server can do anything, so its tools ask first.
+                    self.requires_approval = True
+
+                async def execute(self, **kwargs: Any) -> Any:
+                    async with stdio_client(server_params) as (read, write):
+                        async with ClientSession(read, write) as session:
+                            await session.initialize()
+                            res = await session.call_tool(self.name, arguments=kwargs)
+                            # MCP returns content blocks; hand the agent their text.
+                            texts = [getattr(block, "text", None) or str(block) for block in res.content]
+                            text = "\n".join(texts)
+                            return f"Error from MCP tool: {text}" if getattr(res, "isError", False) else text
+
+            # Attempt listing tools
+            async with stdio_client(server_params) as (read, write):
+                async with ClientSession(read, write) as session:
+                    await session.initialize()
+                    mcp_tools = await session.list_tools()
+                    for t in mcp_tools.tools:
+                        tools.append(MCPRemoteTool(t.name, t.description or "", t.inputSchema))
+
+        except ImportError as exc:
+            raise ToolError("MCP support needs the mcp package: pip install 'flowai-cli[mcp]'") from exc
+
+        return tools

flowai/memory/__init__.py

@@ -0,0 +1,16 @@
+"""FlowAI Memory Subsystem."""
+
+from flowai.memory.base import BaseMemory, MemoryRecord
+from flowai.memory.chroma import ChromaMemory
+from flowai.memory.in_memory import ConversationMemory, InMemory, ShortTermMemory
+from flowai.memory.qdrant import QdrantMemory
+
+__all__ = [
+    "BaseMemory",
+    "MemoryRecord",
+    "InMemory",
+    "ShortTermMemory",
+    "ConversationMemory",
+    "QdrantMemory",
+    "ChromaMemory",
+]

flowai/memory/base.py

@@ -0,0 +1,45 @@
+"""Memory System Base Classes and Interfaces."""
+
+from __future__ import annotations
+
+import uuid
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class MemoryRecord(BaseModel):
+    """Atomic unit of agent memory storage."""
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    content: str
+    role: str = "assistant"  # user, assistant, system, context
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    embedding: list[float] | None = None
+    score: float | None = None
+
+
+class BaseMemory(ABC):
+    """Abstract interface for all memory backends in FlowAI."""
+
+    @abstractmethod
+    async def add(self, record: MemoryRecord | str, **metadata: Any) -> str:
+        """Store a new memory item and return its identifier."""
+        ...
+
+    @abstractmethod
+    async def search(self, query: str, limit: int = 5, **kwargs: Any) -> list[MemoryRecord]:
+        """Search memory for relevant records."""
+        ...
+
+    @abstractmethod
+    async def get_recent(self, limit: int = 10) -> list[MemoryRecord]:
+        """Retrieve recent interaction history."""
+        ...
+
+    @abstractmethod
+    async def clear(self) -> None:
+        """Clear all stored memories in this instance/session."""
+        ...

flowai/memory/chroma.py

@@ -0,0 +1,97 @@
+"""ChromaDB memory backend."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from flowai.memory.base import BaseMemory, MemoryRecord
+from flowai.providers.base import BaseProvider
+
+
+class ChromaMemory(BaseMemory):
+    """Vector memory backed by ChromaDB."""
+
+    def __init__(
+        self,
+        collection_name: str = "flowai_memory",
+        persist_directory: str | None = None,
+        embedding_provider: BaseProvider | None = None,
+    ):
+        self.collection_name = collection_name
+        self.persist_directory = persist_directory
+        self.embedding_provider = embedding_provider
+        self._collection = None
+
+    def _get_collection(self):
+        if self._collection is None:
+            try:
+                import chromadb
+                if self.persist_directory:
+                    client = chromadb.PersistentClient(path=self.persist_directory)
+                else:
+                    client = chromadb.Client()
+                self._collection = client.get_or_create_collection(name=self.collection_name)
+            except ImportError as exc:
+                raise ImportError("chromadb is required for ChromaMemory. Install with: pip install 'flowai-cli[chroma]'") from exc
+        return self._collection
+
+    async def add(self, record: MemoryRecord | str, **metadata: Any) -> str:
+        col = self._get_collection()
+        rec = MemoryRecord(content=record, metadata=metadata) if isinstance(record, str) else record
+        rec_id = rec.id or str(uuid.uuid4())
+
+        embeddings = None
+        if self.embedding_provider:
+            vecs = await self.embedding_provider.embeddings([rec.content])
+            if vecs:
+                embeddings = vecs
+
+        col.add(
+            ids=[rec_id],
+            documents=[rec.content],
+            metadatas=[{"role": rec.role, **rec.metadata}],
+            embeddings=embeddings,
+        )
+        return rec_id
+
+    async def search(self, query: str, limit: int = 5, **kwargs: Any) -> list[MemoryRecord]:
+        col = self._get_collection()
+        query_embeddings = None
+        if self.embedding_provider:
+            vecs = await self.embedding_provider.embeddings([query])
+            if vecs:
+                query_embeddings = vecs
+
+        res = col.query(
+            query_texts=[query] if not query_embeddings else None,
+            query_embeddings=query_embeddings,
+            n_results=limit,
+        )
+
+        records = []
+        if res and res.get("documents"):
+            docs = res["documents"][0]
+            ids = res["ids"][0]
+            metadatas = res.get("metadatas", [[]])[0]
+            for i, doc in enumerate(docs):
+                meta = metadatas[i] if i < len(metadatas) else {}
+                records.append(
+                    MemoryRecord(
+                        id=ids[i],
+                        content=doc,
+                        role=meta.get("role", "assistant"),
+                        metadata=meta,
+                    )
+                )
+        return records
+
+    async def get_recent(self, limit: int = 10) -> list[MemoryRecord]:
+        return await self.search(query="", limit=limit)
+
+    async def clear(self) -> None:
+        col = self._get_collection()
+        # delete all items
+        existing = col.get()
+        if existing and existing.get("ids"):
+            col.delete(ids=existing["ids"])

flowai/memory/in_memory.py

@@ -0,0 +1,65 @@
+"""In-memory, Short-term, and Conversation memory implementations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from flowai.memory.base import BaseMemory, MemoryRecord
+
+
+class InMemory(BaseMemory):
+    """Fast in-memory store for session or ephemeral testing."""
+
+    def __init__(self):
+        self._records: list[MemoryRecord] = []
+
+    async def add(self, record: MemoryRecord | str, **metadata: Any) -> str:
+        if isinstance(record, str):
+            role = metadata.pop("role", "assistant")
+            rec = MemoryRecord(content=record, role=role, metadata=metadata)
+        else:
+            rec = record
+        self._records.append(rec)
+        return rec.id
+
+    async def search(self, query: str, limit: int = 5, **kwargs: Any) -> list[MemoryRecord]:
+        """Simple keyword substring search over in-memory records."""
+        q = query.lower()
+        matched = []
+        for r in reversed(self._records):
+            if q in r.content.lower():
+                matched.append(r)
+                if len(matched) >= limit:
+                    break
+        return matched
+
+    async def get_recent(self, limit: int = 10) -> list[MemoryRecord]:
+        return self._records[-limit:]
+
+    async def clear(self) -> None:
+        self._records.clear()
+
+
+class ShortTermMemory(InMemory):
+    """Sliding-window short term memory buffer."""
+
+    def __init__(self, capacity: int = 20):
+        super().__init__()
+        self.capacity = capacity
+
+    async def add(self, record: MemoryRecord | str, **metadata: Any) -> str:
+        rec_id = await super().add(record, **metadata)
+        if len(self._records) > self.capacity:
+            self._records = self._records[-self.capacity:]
+        return rec_id
+
+
+class ConversationMemory(InMemory):
+    """Conversation history buffer preserving turn order and message roles."""
+
+    def format_history(self) -> str:
+        """Format history into plain dialogue string."""
+        lines = []
+        for r in self._records:
+            lines.append(f"{r.role.capitalize()}: {r.content}")
+        return "\n".join(lines)

flowai/memory/qdrant.py

@@ -0,0 +1,104 @@
+"""Qdrant Vector Memory backend."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from flowai.memory.base import BaseMemory, MemoryRecord
+from flowai.providers.base import BaseProvider
+
+
+class QdrantMemory(BaseMemory):
+    """Semantic vector memory using Qdrant."""
+
+    def __init__(
+        self,
+        url: str = "http://localhost:6333",
+        api_key: str | None = None,
+        collection_name: str = "flowai_memory",
+        vector_size: int = 1536,
+        embedding_provider: BaseProvider | None = None,
+    ):
+        self.url = url
+        self.api_key = api_key
+        self.collection_name = collection_name
+        self.vector_size = vector_size
+        self.embedding_provider = embedding_provider
+        self._client = None
+
+    def _get_client(self):
+        if self._client is None:
+            try:
+                from qdrant_client import AsyncQdrantClient
+                self._client = AsyncQdrantClient(url=self.url, api_key=self.api_key)
+            except ImportError as exc:
+                raise ImportError("qdrant-client is required for QdrantMemory. Install with: pip install 'flowai-cli[qdrant]'") from exc
+        return self._client
+
+    async def add(self, record: MemoryRecord | str, **metadata: Any) -> str:
+        client = self._get_client()
+        from qdrant_client.http import models
+
+        rec = MemoryRecord(content=record, metadata=metadata) if isinstance(record, str) else record
+
+        # Generate embedding vector if provider available
+        vector = rec.embedding
+        if not vector and self.embedding_provider:
+            vecs = await self.embedding_provider.embeddings([rec.content])
+            vector = vecs[0] if vecs else [0.0] * self.vector_size
+        elif not vector:
+            vector = [0.0] * self.vector_size
+
+        point_id = str(uuid.uuid4())
+        await client.upsert(
+            collection_name=self.collection_name,
+            points=[
+                models.PointStruct(
+                    id=point_id,
+                    vector=vector,
+                    payload={"content": rec.content, "role": rec.role, "metadata": rec.metadata},
+                )
+            ],
+        )
+        return point_id
+
+    async def search(self, query: str, limit: int = 5, **kwargs: Any) -> list[MemoryRecord]:
+        client = self._get_client()
+        query_vector = [0.0] * self.vector_size
+        if self.embedding_provider:
+            vecs = await self.embedding_provider.embeddings([query])
+            if vecs:
+                query_vector = vecs[0]
+
+        try:
+            results = await client.search(
+                collection_name=self.collection_name,
+                query_vector=query_vector,
+                limit=limit,
+            )
+            records = []
+            for hit in results:
+                payload = hit.payload or {}
+                records.append(
+                    MemoryRecord(
+                        id=str(hit.id),
+                        content=payload.get("content", ""),
+                        role=payload.get("role", "assistant"),
+                        metadata=payload.get("metadata", {}),
+                        score=hit.score,
+                    )
+                )
+            return records
+        except Exception:
+            return []
+
+    async def get_recent(self, limit: int = 10) -> list[MemoryRecord]:
+        return await self.search(query="", limit=limit)
+
+    async def clear(self) -> None:
+        client = self._get_client()
+        try:
+            await client.delete_collection(self.collection_name)
+        except Exception:
+            pass

flowai/observability/__init__.py

@@ -0,0 +1,15 @@
+"""FlowAI Observability System."""
+
+from flowai.observability.events import EventBus, EventHandler, StreamEvent
+from flowai.observability.opentelemetry import LangSmithExporter, OpenTelemetryExporter
+from flowai.observability.tracer import Span, Tracer
+
+__all__ = [
+    "EventBus",
+    "StreamEvent",
+    "EventHandler",
+    "Tracer",
+    "Span",
+    "OpenTelemetryExporter",
+    "LangSmithExporter",
+]