flock-core 0.4.0b49__tar.gz → 0.4.1__tar.gz

flock_core-0.4.1/.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,27 @@
+name: 🐞 Bug Report
+description: File a Bug Report to help us improve
+title: "🐞 [BUG] <title>"
+labels: ["bug"]
+body:
+  - type: textarea
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: To Reproduce
+      description: Describe how to reproduce the bug.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Expected behavior
+      description: A clear and concise description of what you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Screenshots/Logs
+      description: If applicable, add screenshots and console output to help explain your problem. (You can drag and drop files here).

flock_core-0.4.1/.github/ISSUE_TEMPLATE/documentation_improvement.yaml

@@ -0,0 +1,17 @@
+name: 📚 Documentation Improvement
+description: Suggest improvements or report issues in the documentation
+title: "📚 [DOCS] <title>"
+labels: ["documentation"]
+body:
+  - type: textarea
+    attributes:
+      label: What is unclear or incorrect?
+      description: Describe the issue or suggestion for improvement.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Suggested improvement
+      description: How could the documentation be improved?
+    validations:
+      required: false

flock_core-0.4.1/.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -0,0 +1,29 @@
+name: 🆕 Feature Request
+description: Suggest an idea for this project
+title: "🆕 [FEATURE] <title>"
+labels: ["enhancement"]
+body:
+  - type: textarea
+    attributes:
+      label: Is your feature request related to a problem?
+      description: Please describe. A clear and concise description of what the problem is.
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Describe the solution you want to see
+      description: A clear and concise description of what you want to happen.
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Describe alternatives you have considered
+      description: A clear and concise description of any alternative solutions or features you have considered.
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Additional context
+      description: Add any other context or code snippets about the feature request here.
+    validations:
+      required: false

flock_core-0.4.1/.github/ISSUE_TEMPLATE/question_support_request.yaml

@@ -0,0 +1,17 @@
+name: ❓ Question
+description: Ask a question or request support
+title: "❓ [QUESTION] <title>"
+labels: ["question"]
+body:
+  - type: textarea
+    attributes:
+      label: Your question
+      description: Please describe your question as clearly as possible.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Context
+      description: Add any relevant context, code examples, or screenshots.
+    validations:
+      required: false

flock_core-0.4.1/.github/ISSUE_TEMPLATE/vulnerability_report.md

@@ -0,0 +1,35 @@
+name: 🚨 Security Vulnerability
+description: Report a security vulnerability
+title: "🚨 [SECURITY] <title>"
+labels: ["security"]
+body:
+  - type: textarea
+    attributes:
+      label: Vulnerability description
+      description: Please describe the vulnerability in detail.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Steps to reproduce
+      description: How can we reproduce the vulnerability?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Impact
+      description: What is the potential impact of this vulnerability?
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Suggested mitigation
+      description: Do you have any suggestions for how to fix this?
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Additional context
+      description: Any other information you want to share?
+    validations:
+      required: false

flock_core-0.4.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,30 @@
+## 🔄 Pull Request
+
+### Describe your Pull Request
+A clear and concise description of what the Pull Request is about.
+
+---
+
+### Is there an existing issue for this?
+- [ ] Existing Issue
+
+If yes, please specify:
+
+**Label/Name of the existing issue (if applicable):**
+<!-- Write here -->
+
+---
+
+### Please select relevant options:
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation Improvement
+
+---
+
+### Checklist
+- [ ] My code follows the style guidelines of this project
+- [ ] I have made corresponding changes to the documentation
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] I have checked my code and corrected any misspellings

{flock_core-0.4.0b49 → flock_core-0.4.1}/.vscode/launch.json

@@ -6,12 +6,14 @@
             "type": "debugpy",
             "request": "launch",
             "justMyCode": false,
+            "subProcess": true,
             "program": "${file}",
             "console": "integratedTerminal"
         },
         {
             "name": "Attach to debugpy",
             "type": "python",
+            "subProcess": true,
             "request": "attach",
             "connect": {
                 "host": "localhost",

{flock_core-0.4.0b49 → flock_core-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.4.0b49
+Version: 0.4.1
 Summary: Declarative LLM Orchestration at Scale
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -21,7 +21,7 @@ Requires-Dist: litellm==1.69.3
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: markdown2>=2.5.3
 Requires-Dist: matplotlib>=3.10.0
-Requires-Dist: mem0ai[graph]>=0.1.100
+Requires-Dist: mem0ai[graph]>=0.1.101
 Requires-Dist: msgpack>=1.1.0
 Requires-Dist: notion-client>=2.3.0
 Requires-Dist: openai==1.75.0
@@ -50,6 +50,8 @@ Requires-Dist: tiktoken>=0.8.0
 Requires-Dist: toml>=0.10.2
 Requires-Dist: tqdm>=4.67.1
 Requires-Dist: uvicorn>=0.34.0
+Requires-Dist: wd-di>=0.2.14
+Requires-Dist: zep-python>=2.0.2
 Provides-Extra: all-tools
 Requires-Dist: azure-identity>=1.23.0; extra == 'all-tools'
 Requires-Dist: azure-search-documents>=11.5.2; extra == 'all-tools'
@@ -91,7 +93,7 @@ Description-Content-Type: text/markdown
 
 🐤 `pip install flock-core` will install the latest non-beta version 🐤
 
-🐤  Expected Release for 0.4.0 `Magpie`: End of April 2025 🐤
+🐤 The 0.4.0 Magpie release is in the works! 🐤
 
 ---
 
@@ -296,7 +298,7 @@ Flock makes this easy with:
 *   **Declarative Configuration:** Define Temporal timeouts, retry policies, and task queues directly within your `Flock` and `FlockAgent` configurations (YAML or Python).
 *   **Correct Patterns:** Uses Temporal's recommended granular activity execution for better control and visibility.
 *   **Clear Worker Separation:** Provides guidance and flags for running dedicated Temporal workers, separating development convenience from production best practices.
-  
+
 Visit the [Temporal Documentation](https://learn.temporal.io/python/workflows/) for more information on how to use Temporal.
 
 Or check out the [Flock Showcase](https://github.com/whiteducksoftware/flock-showcase) for a complete example of a Flock that uses Temporal or our [docs](https://whiteducksoftware.github.io/flock/guides/temporal-configuration/) for more information.

{flock_core-0.4.0b49 → flock_core-0.4.1}/README.md

@@ -17,7 +17,7 @@
 
 🐤 `pip install flock-core` will install the latest non-beta version 🐤
 
-🐤  Expected Release for 0.4.0 `Magpie`: End of April 2025 🐤
+🐤 The 0.4.0 Magpie release is in the works! 🐤
 
 ---
 
@@ -222,7 +222,7 @@ Flock makes this easy with:
 *   **Declarative Configuration:** Define Temporal timeouts, retry policies, and task queues directly within your `Flock` and `FlockAgent` configurations (YAML or Python).
 *   **Correct Patterns:** Uses Temporal's recommended granular activity execution for better control and visibility.
 *   **Clear Worker Separation:** Provides guidance and flags for running dedicated Temporal workers, separating development convenience from production best practices.
-  
+
 Visit the [Temporal Documentation](https://learn.temporal.io/python/workflows/) for more information on how to use Temporal.
 
 Or check out the [Flock Showcase](https://github.com/whiteducksoftware/flock-showcase) for a complete example of a Flock that uses Temporal or our [docs](https://whiteducksoftware.github.io/flock/guides/temporal-configuration/) for more information.

flock_core-0.4.1/docs/core-concepts/di.md

@@ -0,0 +1,153 @@
+# Dependency Injection in Flock
+
+> *New in 0.6* — Flock ships with a first-class integration for the [`wd.di`](https://pypi.org/project/wd.di/) service-container.
+>
+> The feature is **completely optional**: existing projects continue to run if you ignore it.  But once you taste constructor injection, you will never want to go back to hand-rolled singletons.
+
+---
+
+## 1  Why DI?
+
+1. **Reuse expensive resources**  
+   Most agents and modules need an embedding model, a vector store, a logger, …
+   The container guarantees a *single* instance per run (or per request) without global variables.
+2. **Constructor injection**  
+   Dependencies are spelled out in the `__init__()` signature – no more `from … import SOME_GLOBAL`.
+3. **Testability**  
+   Replace real services with fakes in one line:
+   ```python
+   sc.add_singleton(S3Client, FakeS3Client())
+   ```
+4. **Middleware**  
+   Cross-cutting concerns such as tracing, error handling or retries are just pipeline components.
+
+---
+
+## 2  Bootstrapping a container
+
+Create and fill a `ServiceCollection` *once* at the beginning of a run — usually in your CLI entry-point or notebook.
+
+```python
+from wd.di import ServiceCollection
+from flock.modules.performance.metrics_module import MetricsModule
+from flock.core.logging.logging import get_logger
+
+sc = ServiceCollection()
+
+# 1. Register concrete instances
+sc.add_singleton(MetricsModule())
+sc.add_singleton(get_logger("run"))
+
+# 2. Register types – the container will build them on demand
+from sentence_transformers import SentenceTransformer
+sc.add_singleton(SentenceTransformer)  # 👈 singleton lifetime
+
+# 3. Build the provider (immutable after this call)
+container = sc.build()
+```
+
+Attach the container to the **runtime context** so that every component can reach it:
+
+```python
+from flock.core.context.context import FlockContext
+ctx = FlockContext()
+ctx.set_variable("di.container", container)
+```
+
+If you do not have the context at bootstrap time (e.g. inside `agent.run()`), store the container in a global and copy it into the context later.  The key name `di.container` is conventional.
+
+---
+
+## 3  Resolving services
+
+### 3.1  Inside modules / agents
+
+Call the convenience helper that was added to `FlockContext`:
+
+```python
+logger = context.resolve(Logger)
+```
+
+It returns `None` if no container is attached or the type is not registered, making the call safe in older projects.
+
+### 3.2  Anywhere else
+
+Import the tiny wrapper shipped in `flock.di`:
+
+```python
+from flock.di import get_current_container
+
+container = get_current_container(context)
+embedding_model = container.get_service(SentenceTransformer)
+```
+
+---
+
+## 4  Using middleware
+
+The `wd.di` package comes with a lightweight **`MiddlewarePipeline`**.  When you register one as a singleton, Flock will automatically wrap evaluator execution:
+
+```python
+from wd.di.middleware_di import create_application_builder
+from wd.di.middleware import LoggingMiddleware, ExceptionHandlerMiddleware
+
+builder = create_application_builder(sc)  # sc is your ServiceCollection
+builder.configure_middleware(
+    lambda m: (
+        m.use_middleware(ExceptionHandlerMiddleware)
+         .use_middleware(LoggingMiddleware)  # <- your own too!
+    )
+)
+
+container = builder.build()  # replaces sc.build()
+```
+
+Each middleware receives `(context, next)` where *context* is the **current FlockContext**.  You can therefore obtain scoped services, record traces, short-circuit execution, etc.
+
+---
+
+## 5  Gradual refactoring pattern
+
+1. **Accept an optional container** in your module constructor:
+   ```python
+   def __init__(self, name: str, config: MyConfig, *, container=None):
+       super().__init__(name=name, config=config)
+       self._metrics = (container or Default()).get_service(MetricsModule)
+   ```
+2. **Resolve shared services** instead of calling module globals.
+3. **Fallback** to the current "global" singletons to stay backward compatible.
+4. Migrate call-sites one by one.
+
+---
+
+## 6  Testing with DI
+
+Creating an isolated container inside your pytest fixtures is easy:
+
+```python
+import pytest
+from wd.di import ServiceCollection
+from flock.modules.performance.metrics_module import MetricsModule
+
+@pytest.fixture()
+def di_container():
+    sc = ServiceCollection()
+    sc.add_singleton(MetricsModule, FakeMetricsModule())
+    return sc.build()
+```
+
+Pass the fixture to your SUT and you never have to monkey-patch again.
+
+---
+
+## 7  FAQ
+
+**Does it work without `wd.di` installed?**  Yes.  Flock guards every optional import so your code still runs.
+
+**Can I have per-request lifetimes?**  Absolutely. Just call `container.create_scope()` before the request, store the scoped provider under the `di.container` key for the duration and dispose it afterwards.
+
+**Will the registry go away?**  No.  The registry continues to handle *serialization* and *lookup by name*.  DI is about *instantiation* and *lifetimes*.
+
+---
+
+Happy wiring! 🚀 

flock_core-0.4.1/docs/wd-di.md

@@ -0,0 +1,108 @@
+# Proposal: Integrating `wd.di` Into Flock
+
+## 1  Background
+The current `FlockRegistry` solves *discovery* and *serialization*:
+* maps names ↔️ Agent / Module / Router / Evaluator classes
+* keeps a cache of callables & types for JSON / YAML (de)serialization
+
+What it **does not** try to solve:
+* lifetime-controlled instantiation of shared services (e.g. embedding model)
+* constructor / property injection
+* request-scoped objects
+* middleware cross-cutting concerns.
+
+The in-house package located at `.flock/wd-di/src/wd/di` already implements a
+robust DI container inspired by ASP.NET:
+* `ServiceCollection` ➜ registration DSL
+* `Container` ➜ resolver with Singleton / Scoped / Transient lifetimes
+* Middleware pipeline with scoped injection
+* YAML-backed config binder (optional)
+
+Pairing that with Flock yields cleaner construction and resource reuse while
+leaving backward compatibility intact.
+
+---
+## 2  Why keep the Registry?
+`FlockRegistry` is tightly coupled to serialization.  Replacing it would break
+existing save-/load flows, YAML configs, and inter-component look-ups by name.
+Therefore **both systems should coexist**:
+
+```
+           ┌─────────────┐          ┌──────────────┐
+ Agent ⇆──▶│  Registry   │          │   DI Container│
+           └─────────────┘◀────────┴──────────────┘
+                  ▲  names                    ▲ types
+                  └───────────────────────────┘
+```
+
+---
+## 3  Migration sketch
+
+1. **Bootstrap a container per run**
+   In `flock.core.context.initialize_context` (or new helper):
+
+   ```python
+   from wd.di import ServiceCollection
+
+   sc = ServiceCollection()
+   sc.add_singleton(MetricsModule())  # attach a metrics collector
+   sc.add_singleton(lambda: get_logger("run"))
+   sc.add_singleton(trace.get_tracer("flock"))
+
+   # Share embedding model across modules if desired
+   for module in agent.get_enabled_modules():
+       sc.add_singleton(type(module), module)
+
+   container = sc.build()
+   run_context.set_variable("di.container", container)
+   ```
+
+2. **Helper for resolution**
+   Add to `FlockContext`:
+
+   ```python
+   def resolve(self, svc_type):
+       container = self.get_variable("di.container")
+       return container.resolve(svc_type) if container else None
+   ```
+
+3. **Gradual module refactor**
+   *Example* (EnterpriseMemoryModule constructor):
+   ```python
+   def __init__(self, name: str, config: Config, container=None):
+       super().__init__(name=name, config=config)
+       self.metrics = (container or Default()).resolve(MetricsModule)  # fallback
+   ```
+
+4. **Middleware pipeline (optional)**
+   Build an onion around evaluator execution:
+   ```python
+   async def evaluator_middleware(next, ctx):
+       tracer = ctx.resolve(Tracer)
+       with tracer.start_as_current_span("evaluator"):
+           return await next()
+   ```
+
+5. **Testing**
+   Tests create a lightweight `ServiceCollection` and inject fakes, reducing
+   patching/monkey-patching need.
+
+---
+## 4  Immediate tasks
+1. Add `wd.di` to `pyproject.toml` as optional extra.
+2. Create `flock.di` thin wrapper exposing `get_current_container()` helper.
+3. Update EnterpriseMemoryModule to accept an optional container and resolve
+   MetricsModule instead of static call (maintain the static fallback).
+4. Document the pattern in `docs/components/di.md`.
+
+---
+## 5  Long-term improvements
+* Replace ad-hoc singletons (embedding cache, adapters) with DI singletons.
+* Use scoped lifetimes for per-run data (OpenAI usage counters, run metadata).
+* Enable declarative middleware in YAML/JSON Flock configs.
+
+---
+## 6  Verdict
+Integrating `wd.di` **adds value** without disrupting existing workflows.  It
+should be adopted as an *internal service container* while the Registry
+continues to serve serialization/discovery needs. 

{flock_core-0.4.0b49 → flock_core-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flock-core"
-version = "0.4.0b-49"
+version = "0.4.1"
 description = "Declarative LLM Orchestration at Scale"
 readme = "README.md"
 authors = [
@@ -52,9 +52,11 @@ dependencies = [
     "toml>=0.10.2",
     "tqdm>=4.67.1",
     "uvicorn>=0.34.0",
-    "mem0ai[graph]>=0.1.100",
+    "mem0ai[graph]>=0.1.101",
     "aiosqlite>=0.21.0",
     "markdown2>=2.5.3",
+    "wd-di>=0.2.14",
+    "zep-python>=2.0.2",
 ]
 
 [project.optional-dependencies]

flock_core-0.4.1/src/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_core-0.4.1/src/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_core-0.4.1/src/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