flock-core 0.4.0b50__py3-none-any.whl → 0.4.2__py3-none-any.whl

flock/adapter/__init__.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+"""Adapter package for pluggable vector-store back-ends.
+
+Importing the package will NOT import heavy third-party clients by default –
+individual adapters are only loaded when referenced explicitly.
+"""
+
+from .vector_base import VectorAdapter, VectorHit
+
+__all__ = [
+    "VectorAdapter",
+    "VectorHit",
+]

flock/adapter/azure_adapter.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .vector_base import VectorAdapter, VectorHit
+
+
+class AzureSearchAdapter(VectorAdapter):
+    """Adapter for Azure Cognitive Search vector capabilities."""
+
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        key: str,
+        index_name: str,
+        embedding_field: str = "embedding",
+    ) -> None:
+        super().__init__()
+        try:
+            from azure.core.credentials import AzureKeyCredential
+            from azure.search.documents import SearchClient
+        except ImportError as e:
+            raise RuntimeError("azure-search-documents package is required for AzureSearchAdapter") from e
+
+        self._client = SearchClient(
+            endpoint=endpoint,
+            index_name=index_name,
+            credential=AzureKeyCredential(key),
+        )
+        self._embedding_field = embedding_field
+
+    # -----------------------------
+    def add(
+        self,
+        *,
+        id: str,
+        content: str,
+        embedding: list[float],
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        document = {
+            "id": id,
+            "content": content,
+            self._embedding_field: embedding,
+            **(metadata or {}),
+        }
+        # Upload is sync but returns iterator; consume to check errors
+        list(self._client.upload_documents(documents=[document]))
+
+    def query(self, *, embedding: list[float], k: int) -> list[VectorHit]:
+        results = self._client.search(
+            search_text=None,
+            vector=embedding,
+            k=k,
+            vector_fields=self._embedding_field,
+        )
+        hits: list[VectorHit] = []
+        for doc in results:
+            hits.append(
+                VectorHit(
+                    id=doc["id"],
+                    content=doc.get("content"),
+                    metadata={k: v for k, v in doc.items() if k not in ("id", "content", self._embedding_field, "@search.score")},
+                    score=doc["@search.score"],
+                )
+            )
+        return hits

flock/adapter/chroma_adapter.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .vector_base import VectorAdapter, VectorHit
+
+
+class ChromaAdapter(VectorAdapter):
+    """Adapter for Chroma vector DB (local or HTTP)."""
+
+    def __init__(
+        self,
+        *,
+        collection: str = "flock_memories",
+        host: str | None = None,
+        port: int = 8000,
+        path: str | None = "./vector_store",
+    ) -> None:
+        super().__init__()
+        try:
+            import chromadb
+            from chromadb.config import Settings
+        except ImportError as e:
+            raise RuntimeError("chromadb is required for ChromaAdapter") from e
+
+        if host:
+            client = chromadb.HttpClient(host=host, port=port)
+        else:
+            p = Path(path or "./vector_store")
+            p.mkdir(parents=True, exist_ok=True)
+            client = chromadb.PersistentClient(settings=Settings(path=str(p)))
+
+        self._collection = client.get_or_create_collection(collection)
+
+    # -------------------------------
+    # VectorAdapter implementation
+    # -------------------------------
+    def add(
+        self,
+        *,
+        id: str,
+        content: str,
+        embedding: list[float],
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self._collection.add(
+            ids=[id],
+            documents=[content],
+            embeddings=[embedding],
+            metadatas=[metadata or {}],
+        )
+
+    def query(self, *, embedding: list[float], k: int) -> list[VectorHit]:
+        res = self._collection.query(
+            query_embeddings=[embedding],
+            n_results=k,
+            include=["documents", "metadatas", "distances", "ids"],
+        )
+        hits: list[VectorHit] = []
+        if res and res["ids"]:
+            for idx in range(len(res["ids"][0])):
+                dist = res["distances"][0][idx]
+                score = 1 - dist  # Convert L2 → similarity
+                hits.append(
+                    VectorHit(
+                        id=res["ids"][0][idx],
+                        content=res["documents"][0][idx],
+                        metadata=res["metadatas"][0][idx],
+                        score=score,
+                    )
+                )
+        return hits

flock/adapter/faiss_adapter.py

@@ -0,0 +1,97 @@
+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

@@ -0,0 +1,51 @@
+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

@@ -0,0 +1,47 @@
+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/constants.py

@@ -18,7 +18,7 @@ CLI_LOAD_FLOCK = "Load a *.flock file"
 CLI_THEME_BUILDER = "Theme builder"
 CLI_LOAD_EXAMPLE = "Load a example"
 CLI_SETTINGS = "Settings"
-CLI_NOTES = "'Hummingbird' release notes"
+CLI_NOTES = "'Magpie' release notes"
 CLI_START_WEB_SERVER = "Start web server"
 CLI_REGISTRY_MANAGEMENT = "Registry management"
 CLI_EXIT = "Exit"

flock/config.py

@@ -22,7 +22,7 @@ GITHUB_USERNAME = config("GITHUB_USERNAME", "")
 # -- Debugging and Logging Configurations --
 LOCAL_DEBUG = config("LOCAL_DEBUG", True)
 LOG_LEVEL = config("LOG_LEVEL", "DEBUG")
-LOGGING_DIR = config("LOGGING_DIR", "logs")
+LOGGING_DIR = config("LOGGING_DIR", ".flock/logs")
 
 OTEL_SERVICE_NAME = config("OTL_SERVICE_NAME", "otel-flock")
 JAEGER_ENDPOINT = config(

flock/core/context/context.py

@@ -192,3 +192,23 @@ class FlockContext(Serializable, BaseModel):
 
         converted = convert(data)
         return cls(**converted)
+
+    def resolve(self, svc_type):
+        """Resolve a service from the request-scoped DI container if present.
+
+        The bootstrap code is expected to store the active `ServiceProvider` from
+        `wd.di` in the context variable key ``di.container``.  This helper
+        provides a convenient façade so that Flock components can simply call
+        ``context.resolve(SomeType)`` regardless of whether a container is
+        available.  When the container is missing or the service cannot be
+        resolved, ``None`` is returned instead of raising to keep backward
+        compatibility.
+        """
+        container = self.get_variable("di.container")
+        if container is None:
+            return None
+        try:
+            return container.get_service(svc_type)
+        except Exception:
+            # Service not registered or other resolution error – fall back to None
+            return None

flock/core/flock.py

@@ -4,10 +4,11 @@
 from __future__ import annotations  # Ensure forward references work
 
 import asyncio
-import concurrent.futures  # Added import
+import contextvars
 import os
 import uuid
-from collections.abc import Callable, Sequence
+from collections.abc import Awaitable, Callable, Sequence
+from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 from typing import (
     TYPE_CHECKING,
@@ -16,6 +17,7 @@ from typing import (
     TypeVar,
 )
 
+_R = TypeVar("_R")
 # Third-party imports
 from box import Box
 from temporalio import workflow
@@ -142,6 +144,28 @@ class Flock(BaseModel, Serializable):
         "ignored_types": (type(FlockRegistry),),
     }
 
+    def _run_sync(self, coro: Awaitable[_R]) -> _R:
+        """Execute *coro* synchronously.
+
+        * If no loop is running → ``asyncio.run``.
+        * Otherwise run ``asyncio.run`` inside a fresh thread **with**
+          context-vars propagation.
+        """
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:                       # no loop → simple
+            return asyncio.run(coro)
+
+        # A loop is already running – Jupyter / ASGI / etc.
+        ctx = contextvars.copy_context()           # propagate baggage
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            future = pool.submit(ctx.run, asyncio.run, coro)
+            try:
+                return future.result()
+            finally:
+                if not future.done():
+                    future.cancel()
+
     def __init__(
         self,
         name: str | None = None,
@@ -356,39 +380,19 @@ class Flock(BaseModel, Serializable):
         run_id: str = "",
         box_result: bool = True,
         agents: list[FlockAgent] | None = None,
+        memo: dict[str, Any] | None = None
     ) -> Box | dict:
-        """Entry point for running an agent system synchronously."""
-        # Prepare the coroutine that needs to be run
-        coro = self.run_async(
-            start_agent=start_agent,
-            input=input,
-            context=context,
-            run_id=run_id,
-            box_result=box_result,  # run_async handles boxing
-            agents=agents,
-        )
-
-        try:
-            # Check if an event loop is already running in the current thread
-            loop = asyncio.get_running_loop()
-        except RuntimeError:
-            # No event loop is running in the current thread.
-            # We can safely use asyncio.run() to create a new loop,
-            # run the coroutine, and close the loop.
-            return asyncio.run(coro)
-        else:
-            # An event loop is already running in the current thread.
-            # Calling loop.run_until_complete() or asyncio.run() here would raise an error.
-            # To run the async code and wait for its result synchronously,
-            # we execute it in a separate thread with its own event loop.
-            logger.debug(
-                "Flock.run called in a context with an existing event loop. "
-                "Running async task in a separate thread to avoid event loop conflict."
+        return self._run_sync(
+            self.run_async(
+                start_agent=start_agent,
+                input=input,
+                context=context,
+                run_id=run_id,
+                box_result=box_result,
+                agents=agents,
+                memo=memo,
             )
-            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
-                future = executor.submit(asyncio.run, coro)
-                # Block and wait for the result from the other thread
-                return future.result()
+        )
 
 
     async def run_async(
@@ -602,35 +606,24 @@ class Flock(BaseModel, Serializable):
         hide_columns: list[str] | None = None,
         delimiter: str = ",",
     ) -> list[Box | dict | None | Exception]:
-        """Synchronous wrapper for run_batch_async."""
-        coro = self.run_batch_async(
-            start_agent=start_agent,
-            batch_inputs=batch_inputs,
-            input_mapping=input_mapping,
-            static_inputs=static_inputs,
-            parallel=parallel,
-            max_workers=max_workers,
-            use_temporal=use_temporal,
-            box_results=box_results,
-            return_errors=return_errors,
-            silent_mode=silent_mode,
-            write_to_csv=write_to_csv,
-            hide_columns=hide_columns,
-            delimiter=delimiter,
+        return self._run_sync(
+            self.run_batch_async(
+                start_agent=start_agent,
+                batch_inputs=batch_inputs,
+                input_mapping=input_mapping,
+                static_inputs=static_inputs,
+                parallel=parallel,
+                max_workers=max_workers,
+                use_temporal=use_temporal,
+                box_results=box_results,
+                return_errors=return_errors,
+                silent_mode=silent_mode,
+                write_to_csv=write_to_csv,
+                hide_columns=hide_columns,
+                delimiter=delimiter,
+            )
         )
 
-        try:
-            loop = asyncio.get_running_loop()
-        except RuntimeError:
-            return asyncio.run(coro)
-        else:
-            logger.debug(
-                "Flock.run_batch called in a context with an existing event loop. "
-                "Running async task in a separate thread."
-            )
-            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
-                future = executor.submit(asyncio.run, coro)
-                return future.result()
 
     # --- Evaluation (Delegation) ---
     async def evaluate_async(
@@ -704,38 +697,25 @@ class Flock(BaseModel, Serializable):
         silent_mode: bool = False,
         metadata_columns: list[str] | None = None,
     ) -> DataFrame | list[dict[str, Any]]: # type: ignore
-        """Synchronous wrapper for evaluate_async."""
-        coro = self.evaluate_async(
-            dataset=dataset,
-            start_agent=start_agent,
-            input_mapping=input_mapping,
-            answer_mapping=answer_mapping,
-            metrics=metrics,
-            metric_configs=metric_configs,
-            static_inputs=static_inputs,
-            parallel=parallel,
-            max_workers=max_workers,
-            use_temporal=use_temporal,
-            error_handling=error_handling,
-            output_file=output_file,
-            return_dataframe=return_dataframe,
-            silent_mode=silent_mode,
-            metadata_columns=metadata_columns,
-        )
-
-        try:
-            loop = asyncio.get_running_loop()
-        except RuntimeError:
-            return asyncio.run(coro)
-        else:
-            logger.debug(
-                "Flock.evaluate called in a context with an existing event loop. "
-                "Running async task in a separate thread."
+        return self._run_sync(
+            self.evaluate_async(
+                dataset=dataset,
+                start_agent=start_agent,
+                input_mapping=input_mapping,
+                answer_mapping=answer_mapping,
+                metrics=metrics,
+                metric_configs=metric_configs,
+                static_inputs=static_inputs,
+                parallel=parallel,
+                max_workers=max_workers,
+                use_temporal=use_temporal,
+                error_handling=error_handling,
+                output_file=output_file,
+                return_dataframe=return_dataframe,
+                silent_mode=silent_mode,
+                metadata_columns=metadata_columns,
             )
-            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
-                future = executor.submit(asyncio.run, coro)
-                return future.result()
-
+        )
     # --- Server & CLI Starters (Delegation) ---
     def start_api(
         self,

flock/core/flock_agent.py

@@ -335,9 +335,64 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
                     # For now, assume evaluator handles tool resolution if necessary
                     registered_tools = self.tools
 
-                result = await self.evaluator.evaluate(
-                    self, current_inputs, registered_tools
-                )
+                # --------------------------------------------------
+                # Optional DI middleware pipeline
+                # --------------------------------------------------
+                container = None
+                if self.context is not None:
+                    container = self.context.get_variable("di.container")
+
+                # If a MiddlewarePipeline is registered in DI, wrap the evaluator
+                result: dict[str, Any] | None = None
+
+                if container is not None:
+                    try:
+                        from wd.di.middleware import (
+                            MiddlewarePipeline,
+                        )
+
+                        pipeline: MiddlewarePipeline | None = None
+                        try:
+                            pipeline = container.get_service(MiddlewarePipeline)
+                        except Exception:
+                            pipeline = None
+
+                        if pipeline is not None:
+                            # Build execution chain where the evaluator is the terminal handler
+
+                            async def _final_handler():
+                                return await self.evaluator.evaluate(
+                                    self, current_inputs, registered_tools
+                                )
+
+                            idx = 0
+
+                            async def _invoke_next():
+                                nonlocal idx
+
+                                if idx < len(pipeline._middleware):
+                                    mw = pipeline._middleware[idx]
+                                    idx += 1
+                                    return await mw(self.context, _invoke_next)  # type: ignore[arg-type]
+                                return await _final_handler()
+
+                            # Execute pipeline
+                            result = await _invoke_next()
+                        else:
+                            # No pipeline registered, direct evaluation
+                            result = await self.evaluator.evaluate(
+                                self, current_inputs, registered_tools
+                            )
+                    except ImportError:
+                        # wd.di not installed – fall back
+                        result = await self.evaluator.evaluate(
+                            self, current_inputs, registered_tools
+                        )
+                else:
+                    # No DI container – standard execution
+                    result = await self.evaluator.evaluate(
+                        self, current_inputs, registered_tools
+                    )
             except Exception as eval_error:
                 logger.error(
                     "Error during evaluate",