flock-core 0.5.0b28__py3-none-any.whl → 0.5.56b0__py3-none-any.whl

flock/adapter/faiss_adapter.py

@@ -1,97 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Any
-
-import numpy as np
-
-from .vector_base import VectorAdapter, VectorHit
-
-
-class FAISSAdapter(VectorAdapter):
-    """Simple on-disk FAISS vector store.
-
-    Index is stored in `index_path` (flat L2).  Metadata & content are kept in a
-    parallel JSONL file for quick prototyping; not optimised for massive scale.
-    """
-
-    def __init__(self, *, index_path: str = "./faiss.index") -> None:
-        super().__init__()
-        try:
-            import faiss  # type: ignore
-        except ImportError as e:
-            raise RuntimeError("faiss library is required for FAISSAdapter") from e
-
-        self._faiss = __import__("faiss")  # lazy alias
-        self._index_path = Path(index_path)
-        self._meta_path = self._index_path.with_suffix(".meta.jsonl")
-        self._metadata: dict[int, dict[str, Any]] = {}
-
-        if self._index_path.exists():
-            self._index = self._faiss.read_index(str(self._index_path))
-            # Load metadata
-            if self._meta_path.exists():
-                import json
-
-                with open(self._meta_path) as f:
-                    for line_no, line in enumerate(f):
-                        self._metadata[line_no] = json.loads(line)
-        else:
-            self._index = None  # created on first add
-
-    # -----------------------------
-    def _ensure_index(self, dim: int):
-        if self._index is None:
-            self._index = self._faiss.IndexFlatL2(dim)
-
-    def add(
-        self,
-        *,
-        id: str,
-        content: str,
-        embedding: list[float],
-        metadata: dict[str, Any] | None = None,
-    ) -> None:
-        import json
-
-        vec = np.array([embedding], dtype="float32")
-        self._ensure_index(vec.shape[1])
-        self._index.add(vec)
-        # Row id is current size - 1
-        row_id = self._index.ntotal - 1
-        self._metadata[row_id] = {
-            "id": id,
-            "content": content,
-            "metadata": metadata or {},
-        }
-        # Append metadata to file for persistence
-        self._meta_path.parent.mkdir(parents=True, exist_ok=True)
-        with open(self._meta_path, "a") as f:
-            f.write(json.dumps(self._metadata[row_id]) + "\n")
-        # Persist index lazily every 100 inserts
-        if row_id % 100 == 0:
-            self._faiss.write_index(self._index, str(self._index_path))
-
-    def query(self, *, embedding: list[float], k: int) -> list[VectorHit]:
-        if self._index is None or self._index.ntotal == 0:
-            return []
-        vec = np.array([embedding], dtype="float32")
-        distances, indices = self._index.search(vec, k)
-        hits: list[VectorHit] = []
-        for dist, idx in zip(distances[0], indices[0]):
-            if idx == -1:
-                continue
-            meta = self._metadata.get(idx, {})
-            hits.append(
-                VectorHit(
-                    id=meta.get("id", str(idx)),
-                    content=meta.get("content"),
-                    metadata=meta.get("metadata", {}),
-                    score=1 - float(dist),  # approximate similarity
-                )
-            )
-        return hits
-
-    def close(self) -> None:
-        if self._index is not None:
-            self._faiss.write_index(self._index, str(self._index_path))

flock/adapter/pinecone_adapter.py

@@ -1,51 +0,0 @@
-from __future__ import annotations
-
-from typing import Any
-
-from .vector_base import VectorAdapter, VectorHit
-
-
-class PineconeAdapter(VectorAdapter):
-    """Adapter for Pinecone vector DB."""
-
-    def __init__(
-        self,
-        *,
-        api_key: str,
-        environment: str,
-        index: str,
-    ) -> None:
-        super().__init__()
-        try:
-            import pinecone
-        except ImportError as e:
-            raise RuntimeError("pinecone-client is required for PineconeAdapter") from e
-
-        pinecone.init(api_key=api_key, environment=environment)
-        self._index = pinecone.Index(index)
-
-    # -------------------------------
-    def add(
-        self,
-        *,
-        id: str,
-        content: str,
-        embedding: list[float],
-        metadata: dict[str, Any] | None = None,
-    ) -> None:
-        meta = {"content": content, **(metadata or {})}
-        self._index.upsert(vectors=[(id, embedding, meta)])
-
-    def query(self, *, embedding: list[float], k: int) -> list[VectorHit]:
-        res = self._index.query(vector=embedding, top_k=k, include_values=False, include_metadata=True)
-        hits: list[VectorHit] = []
-        for match in res.matches or []:
-            hits.append(
-                VectorHit(
-                    id=match.id,
-                    content=match.metadata.get("content") if match.metadata else None,
-                    metadata={k: v for k, v in (match.metadata or {}).items() if k != "content"},
-                    score=match.score,
-                )
-            )
-        return hits

flock/adapter/vector_base.py

@@ -1,47 +0,0 @@
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from dataclasses import dataclass
-from typing import Any
-
-
-@dataclass
-class VectorHit:
-    """Result object returned from vector search."""
-
-    id: str
-    content: str | None
-    metadata: dict[str, Any]
-    score: float  # similarity score (higher = more similar)
-
-
-class VectorAdapter(ABC):
-    """Protocol for vector-store adapters."""
-
-    def __init__(self, **kwargs):
-        """Store-specific kwargs are passed through subclass constructor."""
-        super().__init__()
-
-    # ----------------------
-    # CRUD operations
-    # ----------------------
-    @abstractmethod
-    def add(
-        self,
-        *,
-        id: str,
-        content: str,
-        embedding: list[float],
-        metadata: dict[str, Any] | None = None,
-    ) -> None:  # pragma: no cover – interface
-        """Insert or upsert a single document."""
-
-    @abstractmethod
-    def query(
-        self, *, embedding: list[float], k: int
-    ) -> list[VectorHit]:  # pragma: no cover – interface
-        """Return top-k most similar hits."""
-
-    def close(self) -> None:  # Optional override
-        """Free resources / flush buffers."""
-        return

flock/cli/assets/release_notes.md

@@ -1,140 +0,0 @@
-# Flock v0.3 - Hummingbird  
-
-We're excited to announce Flock v0.3, codenamed **"Hummingbird"**! This release brings a fundamental redesign of Flock's core architecture, introducing **unprecedented modularity and flexibility** to AI agent development.  
-
-Modules and evaluators were the last missing pieces to fully modularize Flock.  
-
-Worried this might lead to hard-to-manage boilerplate? No problem! **FlockFactory** provides pre-configured agents, making interaction with modules and evaluators **purely optional**, so you can focus on **what** the agent does, not **how** it works.  
-
-But if you want **total control** over your agent, feel free to dive into these new additions. They unlock **crazy new possibilities** in Flock!  
-
-Like a hummingbird, modules are small and nimble code packages. Put enough of them inside a flock, and... well, even we don't know what happens next.  
-
-### Other notable additions:  
-- **CLI Interface** – Flock now has a command-line interface  
-- **REST API Server** – Expose your agents via HTTP endpoints
-- **Color-coded logging** – Better debugging experience  
-- **New examples**  
-- ...and much more!  
-
----
-
-## Core Changes   
-
-### New Module System   
-- **Pluggable modules system á la FastAPI**   
-- **Easy-to-implement** module interface  
-- **Configuration system** for clean parameter management  
-
-### New Evaluator System  
-- **Pluggable evaluation system**  
-- Built-in support for multiple evaluation strategies:  
-  - **Declarative Evaluator** – The default way Flock is designed  
-  - **Natural Language Evaluator** – Use "classic" prompting  
-  - **Zep Evaluator** – Add or query data
-- **Easily extendable** with custom evaluation approaches  
-
-### New Router System
-- **Pluggable router system** for dynamic agent chaining
-- Built-in support for multiple routing strategies:
-  - **Default Router** – Uses the agent's hand_off property
-  - **LLM Router** – Uses an LLM to determine the next agent
-  - **Agent Router** – Uses a dedicated agent to make routing decisions
-- **Easily extendable** with custom routing approaches
-
-### REST API Server
-- **FastAPI-based** HTTP server for exposing agents
-- **Synchronous and asynchronous** execution modes
-- **Run status tracking** with unique run IDs
-- **Agent discovery** endpoint to list available agents
-- **Simple integration** with existing Flock instances
-
-### Auto-Handoff Feature
-- **Dynamic agent chaining** without explicit handoff definitions
-- **LLM-powered routing** to determine the best next agent
-- **Emergent behavior** in multi-agent systems
-- **Simple to use** with the "auto_handoff" string value
-
-### New high end examples like the Repository Analyzer
-- **Automatic documentation generation** for any codebase
-- **Rule-based version** using custom evaluators
-- **LLM-based version** for more flexible and powerful analysis
-- **Comprehensive documentation** including overview, architecture, components, and more
-
-### FlockFactory    
-- Provides **pre-configured agents**, so you don't have to manage modules and evaluators manually!  
-
-### Built-in Modules  
-- **Memory Module** – Persistent agent memory  
-- **Output Module** – Advanced output formatting and storage  
-- **Metrics Module** – Detailed performance tracking  
-- **Zep Module** – Uses Zep for Knowledge Graphs
-- **Azure Search Tools** – Integration with Azure AI Search for vector search and document retrieval
-
----
-
-## Breaking Changes  
-- **Removed callback handlers** from `FlockAgent` in favor of modules  
-- **Changed agent initialization** pattern to support evaluators  
-- **Simplified module lifecycle hooks** (removed redundant pre/post hooks)  
-
----
-
-## Small Changes & Fixes 
-
-### Theme Designer
-
-### Color Coded Logging
-
----
-
-## Code Rundown  
-
-### Old way:  
-```python
-agent = FlockAgent(
-    name="bloggy",
-    input="blog_idea",
-    output="funny_blog_title, blog_headers",
-)
-flock.add_agent(bloggy)
-```  
-
-### New way:  
-```python
-bloggy = FlockFactory.create_default_agent(
-    name="bloggy",
-    input="blog_idea",
-    output="funny_blog_title, blog_headers",
-)
-flock.add_agent(bloggy)
-```  
-
-See? **Basically nothing changed!** Just more modular and flexible.  
-
----
-
-## What's Next?  
-
-### Coming in v0.3 updates:  
-- **More modules** (built-in RAG coming soon!)  
-- **More evaluators**  
-- **CLI management tool improvements**  
-- **Finishing documentation**
-
-### Looking ahead to v0.4 – *Magpie*:  
-- **Flock WebUI** – Real-time monitoring, no-code agent creation & management  
-- **Seamless deployment** – Kubernetes, Docker, and enterprise-ready solutions  
-
----
-
-## Installation  
-
-```bash
-pip install flock-core>=0.3.0
-```  
-
----  
-
-**Full documentation**: [https://whiteducksoftware.github.io/flock](https://whiteducksoftware.github.io/flock)  
-**GitHub**: [https://github.com/whiteducksoftware/flock](https://github.com/whiteducksoftware/flock)

flock/cli/config.py

@@ -1,8 +0,0 @@
-def init_config_file():
-    """Initialize the config file."""
-    pass
-
-
-def load_config_file():
-    """Load the config file."""
-    pass

flock/cli/constants.py

@@ -1,36 +0,0 @@
-"""Constants for the CLI module."""
-
-CLI_CFG_FILE = ".env"
-CLI_DEFAULT_ENV_VARS = {
-    "FLICK_API_KEY": "flock-api-key",
-    "FLICK_API_URL": "https://api.flock.com",
-    "FLICK_API_VERSION": "v1",
-    "FLICK_API_KEY": "flock-api-key",
-    "FLICK_API_URL": "https://api.flock.com",
-    "FLICK_API_VERSION": "v1",
-}
-CLI_DEFAULT_FOLDER = ".flock"
-
-CLI_CREATE_AGENT = "Create an agent"
-CLI_CREATE_FLOCK = "Create a new Flock"
-CLI_LOAD_AGENT = "Load an agent"
-CLI_LOAD_FLOCK = "Load a *.flock file"
-CLI_THEME_BUILDER = "Theme builder"
-CLI_LOAD_EXAMPLE = "Load a example"
-CLI_SETTINGS = "Settings"
-CLI_NOTES = "'Magpie' release notes"
-CLI_START_WEB_SERVER = "Start web server"
-CLI_REGISTRY_MANAGEMENT = "Registry management"
-CLI_EXIT = "Exit"
-CLI_CHOICES = [
-    CLI_CREATE_AGENT,
-    CLI_CREATE_FLOCK,
-    CLI_LOAD_AGENT,
-    CLI_LOAD_FLOCK,
-    CLI_LOAD_EXAMPLE,
-    CLI_THEME_BUILDER,
-    CLI_REGISTRY_MANAGEMENT,
-    CLI_SETTINGS,
-    CLI_START_WEB_SERVER,
-    CLI_EXIT,
-]

flock/cli/create_agent.py

@@ -1 +0,0 @@
-# TODO

flock/cli/create_flock.py

@@ -1,280 +0,0 @@
-"""Create a new Flock through a guided wizard.
-
-This module provides a wizard-like interface for creating new Flock instances,
-with options for basic configuration and initial agent creation.
-"""
-
-from datetime import datetime
-from pathlib import Path
-
-import questionary
-from rich.console import Console
-from rich.panel import Panel
-
-from flock.cli.constants import CLI_DEFAULT_FOLDER
-from flock.cli.loaded_flock_cli import start_loaded_flock_cli
-from flock.core.flock import Flock
-from flock.core.flock_factory import FlockFactory
-from flock.core.logging.logging import get_logger
-from flock.core.util.cli_helper import init_console
-
-# Create console instance
-console = Console()
-logger = get_logger("cli.create_flock")
-
-
-def create_flock():
-    """Create a new Flock through a guided wizard."""
-    init_console()
-    console.print(Panel("[bold green]Create New Flock[/]"), justify="center")
-    console.line()
-
-    # Step 1: Basic Flock Configuration
-    console.print("[bold]Step 1: Basic Flock Configuration[/]")
-    console.line()
-
-    flock_name = questionary.text(
-        "Enter a name for this Flock:",
-        default="",
-    ).ask()
-
-    # Get description
-    description = questionary.text(
-        "Enter a description for this Flock (optional):",
-        default="",
-    ).ask()
-
-    # Default model selection
-    default_models = [
-        "openai/gpt-4o",
-        "openai/gpt-3.5-turbo",
-        "anthropic/claude-3-opus-20240229",
-        "anthropic/claude-3-sonnet-20240229",
-        "gemini/gemini-1.5-pro",
-        "Other (specify)",
-    ]
-
-    model_choice = questionary.select(
-        "Select a default model:",
-        choices=default_models,
-    ).ask()
-
-    if model_choice == "Other (specify)":
-        model = questionary.text(
-            "Enter the model identifier:",
-            default="openai/gpt-4o",
-        ).ask()
-    else:
-        model = model_choice
-
-    # Execution options
-    # enable_temporal = questionary.confirm(
-    #     "Enable Temporal for distributed execution?",
-    #     default=False,
-    # ).ask()
-    enable_temporal = False
-
-    # Create the Flock instance
-    flock = Flock(
-        name=flock_name,
-        model=model,
-        description=description,
-        enable_temporal=enable_temporal,
-    )
-
-    console.print("\n[green]✓[/] Flock created successfully!")
-    console.line()
-
-    # Step 2: Create Initial Agent (optional)
-    create_agent = questionary.confirm(
-        "Would you like to create an initial agent?",
-        default=True,
-    ).ask()
-
-    if create_agent:
-        _create_initial_agent(flock)
-
-    # Step 3: Save Options
-    console.print("\n[bold]Step 3: Save Options[/]")
-    console.line()
-
-    save_choice = questionary.select(
-        "What would you like to do with this Flock?",
-        choices=[
-            "Save to YAML file",
-            "Continue in CLI without saving",
-            "Execute immediately",
-            "Cancel and discard",
-        ],
-    ).ask()
-
-    if save_choice == "Save to YAML file":
-        _save_flock_to_yaml(flock)
-
-        # Ask if user wants to continue working with this Flock
-        continue_with_flock = questionary.confirm(
-            "Would you like to continue working with this Flock in the CLI?",
-            default=True,
-        ).ask()
-
-        if continue_with_flock:
-            start_loaded_flock_cli(flock, server_name="New Flock")
-
-    elif save_choice == "Continue in CLI without saving":
-        start_loaded_flock_cli(flock, server_name="New Flock")
-
-    elif save_choice == "Execute immediately":
-        from flock.cli.execute_flock import execute_flock
-
-        try:
-            execute_flock(flock)
-        except ImportError:
-            console.print(
-                "[yellow]Execute functionality not yet implemented.[/]"
-            )
-            input("\nPress Enter to continue...")
-            start_loaded_flock_cli(flock, server_name="New Flock")
-
-
-def _create_initial_agent(flock):
-    """Create an initial agent for the Flock.
-
-    Args:
-        flock: The Flock instance to add the agent to
-    """
-    console.print("\n[bold]Step 2: Create Initial Agent[/]")
-    console.line()
-
-    # Get agent name
-    name = questionary.text(
-        "Enter a name for the agent:",
-        default="my_agent",
-    ).ask()
-
-    # Get agent description
-    description = questionary.text(
-        "Enter a description for the agent (optional):",
-        default="",
-    ).ask()
-
-    # Get input specification
-    input_spec = questionary.text(
-        "Enter input specification (e.g., 'query: str | The search query'):",
-        default="query",
-    ).ask()
-
-    # Get output specification
-    output_spec = questionary.text(
-        "Enter output specification (e.g., 'result: str | The generated result'):",
-        default="result",
-    ).ask()
-
-    # Additional options
-    use_cache = questionary.confirm(
-        "Enable caching for this agent?",
-        default=True,
-    ).ask()
-
-    enable_rich_tables = questionary.confirm(
-        "Enable rich table output for this agent?",
-        default=True,
-    ).ask()
-
-    # Create the agent
-    agent = FlockFactory.create_default_agent(
-        name=name,
-        description=description,
-        input=input_spec,
-        output=output_spec,
-        use_cache=use_cache,
-        enable_rich_tables=enable_rich_tables,
-    )
-
-    # Add the agent to the Flock
-    flock.add_agent(agent)
-    console.print(f"\n[green]✓[/] Agent '{name}' created and added to Flock!")
-
-
-def _save_flock_to_yaml(flock):
-    """Save the Flock to a YAML file.
-
-    Args:
-        flock: The Flock instance to save
-    """
-    # Get file path
-    # default = flock.name + current date in 04_04_2025 format
-    default_name = f"{flock.name}_{datetime.now().strftime('%m_%d_%Y')}"
-    file_path = questionary.text(
-        "Enter file path to save Flock:",
-        default=default_name,
-    ).ask()
-
-    # Ensure the file has the correct extension
-    if not file_path.endswith((".yaml", ".yml")):
-        file_path += ".flock.yaml"
-
-    file_path = CLI_DEFAULT_FOLDER + "/" + file_path
-
-    # Create directory if it doesn't exist
-    save_path = Path(file_path)
-    save_path.parent.mkdir(parents=True, exist_ok=True)
-
-    # Ask about path_type
-    path_type_choice = questionary.select(
-        "How should file paths be formatted?",
-        choices=[
-            "absolute (full paths, best for local use)",
-            "relative (relative paths, better for sharing)",
-        ],
-        default="absolute (full paths, best for local use)",
-    ).ask()
-
-    # Extract just the first word
-    path_type = path_type_choice.split()[0]
-
-    console.print(
-        f"[bold]Path type selected: [green]{path_type}[/green][/bold]"
-    )
-
-    try:
-        # Check if the flock has tools to provide a helpful message
-        has_tools = False
-        for agent in flock.agents.values():
-            if agent.tools and len(agent.tools) > 0:
-                has_tools = True
-                break
-
-        # Save the Flock to YAML with proper tool serialization
-        logger.info(f"Saving Flock to {file_path}")
-        flock.to_yaml_file(file_path, path_type=path_type)
-        console.print(
-            f"\n[green]✓[/] Flock saved to {file_path} with {path_type} paths"
-        )
-
-        # Provide helpful information about tool serialization
-        if has_tools:
-            console.print("\n[bold blue]Tools Information:[/]")
-            console.print(
-                "This Flock contains tools that have been serialized as callable references."
-            )
-            console.print(
-                "When loading this Flock on another system, ensure that:"
-            )
-            console.print(
-                "  - The tools/functions are registered in the Flock registry"
-            )
-            console.print(
-                "  - The containing modules are available in the Python path"
-            )
-    except Exception as e:
-        logger.error(f"Error saving Flock: {e}", exc_info=True)
-        console.print(f"\n[bold red]Error saving Flock:[/] {e!s}")
-
-        # Provide guidance on potential issues with tool serialization
-        if "callable" in str(e).lower() or "registry" in str(e).lower():
-            console.print(
-                "\n[yellow]This error might be related to tool serialization.[/]"
-            )
-            console.print(
-                "[yellow]Check if all tools are properly registered in the Flock registry.[/]"
-            )