flock-core 0.4.528__tar.gz → 0.4.529__tar.gz

{flock_core-0.4.528 → flock_core-0.4.529}/CONTRIBUTING.md

@@ -40,7 +40,7 @@ We follow the [Contributor Covenant](https://www.contributor-covenant.org/) code
 
 <!-- TOC --><a name="-reporting-issues"></a>
 ## ❗ Reporting Issues:
-- Before submitting a new issue, pleas check [existing issues](https://github.com/whiteducksoftware/flock/issues) if it has already been reported.
+- Before submitting a new issue, please check [existing issues](https://github.com/whiteducksoftware/flock/issues) if it has already been reported.
 - To submit a new issue, please use the provided **Issue Templates** and provide a clear and descriptive title along with a detailed description of the problem or feature request, including steps to reproduce if it's a bug.
 
 <!-- TOC --><a name="-pull-requests"></a>
@@ -104,15 +104,15 @@ We follow the [Contributor Covenant](https://www.contributor-covenant.org/) code
 <!-- TOC --><a name="a-few-best-practices-for-writing-good-documentation"></a>
 ### A few best practices for writing good documentation:
 1. Document the **Why**, not just the how:
-    - Documentation should explain the rational behind your decisions, rather than just describing the "how".
-    - This helps other developers understand the context and reasoning for the implementation, making the code more maintainable and modifyiable.
+    - Documentation should explain the rationale behind your decisions, rather than just describing the "how".
+    - This helps other developers understand the context and reasoning for the implementation, making the code more maintainable and modifiable.
 2. Keep it Up to Date:
    - Your documentation should evolve alongside the code. If you change the behavior of an existing component of Flock, please also take care to make sure the documentation reflects this fact.
 3. Write for the Reader:
    - Consider the audience for your documentation.
    - It should be accessible and understandable for developers who are not intimately familiar with the code.
 4. Document Intent and Design:
-   - Refering to Point 1, Document your decisions of **why** you chose to implement a new component or code change the way you did, if it is not immediately obvious.
+   - Referring to Point 1, Document your decisions of **why** you chose to implement a new component or code change the way you did, if it is not immediately obvious.
 5. Code as Documentation:
    - Well-written code can serve as it's own documentation.
    - Code should be clear, expressive and self-explanatory where possible.
@@ -120,19 +120,19 @@ We follow the [Contributor Covenant](https://www.contributor-covenant.org/) code
 6. Provide Examples:
    - Examples can help other developers understand your changes and are therefore encouraged.
 7. Use Comments Wisely:
-   - Aviod redundant comments that merely restate what the code does, which can clutter the codebase and detract from its readability.
+   - Avoid redundant comments that merely restate what the code does, which can clutter the codebase and detract from its readability.
 8. Be Pragmatic:
    - There is no need for you to excessively comment every line of code you provide.
    - Add documentation where necessary and focus on keeping documentation on a high level.
 
 <!-- TOC --><a name="-testing-and-reliability"></a>
 ## 🔭 Testing and Reliability:
-Flock aims to provide a easy and reliable way to implement agentic applications. Therefore, well tested code is crucial.
+Flock aims to provide an easy and reliable way to implement agentic applications. Therefore, well tested code is crucial.
 
 - Test your changes thoroughly! Ensure that existing tests pass and add **new tests** for any new functionality.
 - Follow Flock's testing conventions and use the provided testing framework.
 - Run the tests before submitting your pull request to confirm that nothing is broken.
-- Test can be run locally with `pytest -q`
+- Tests can be run locally with `pytest -q`
 - Place new tests in `tests/` mirroring the package path.
 - Use [`pytest`](https://docs.pytest.org/en/stable/) fixtures instead of duplicating setup code.
 - For Temporal code, rely on the *Temporal Test Server* fixture.
@@ -140,7 +140,7 @@ Flock aims to provide a easy and reliable way to implement agentic applications.
 
 <!-- TOC --><a name="release-process"></a>
 ## Release Process:
-1. Maintainer bumps versiion in `pyproject.toml` following **SemVer**.
+1. Maintainer bumps version in `pyproject.toml` following **SemVer**.
 2. Changelog entry added in `docs/about/changelog.md`.
 3. `uv pip install -e .[all] && pytest`
 4. `git tag v.X.Y.Z && git push --tags`

{flock_core-0.4.528 → flock_core-0.4.529}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.4.528
+Version: 0.4.529
 Summary: Declarative LLM Orchestration at Scale
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -10,6 +10,7 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.10
 Requires-Dist: aiosqlite>=0.21.0
 Requires-Dist: azure-data-tables>=12.7.0
+Requires-Dist: azure-storage-blob>=12.25.1
 Requires-Dist: cloudpickle>=3.1.1
 Requires-Dist: croniter>=6.0.0
 Requires-Dist: devtools>=0.12.2
@@ -50,6 +51,7 @@ Requires-Dist: uvicorn>=0.34.0
 Requires-Dist: wd-di>=0.2.14
 Requires-Dist: websockets>=15.0.1
 Requires-Dist: werkzeug>=3.1.3
+Requires-Dist: xlsxwriter>=3.2.3
 Provides-Extra: all
 Requires-Dist: azure-identity>=1.23.0; extra == 'all'
 Requires-Dist: azure-search-documents>=11.5.2; extra == 'all'

{flock_core-0.4.528 → flock_core-0.4.529}/SECURITY.md

@@ -15,7 +15,7 @@ and actively encourage our community-members to report
 any issues with the Flock framework as soon as possible
 in order to mitigate any potential risks.
 
-To report a vulnerability, you have serveral options available:
+To report a vulnerability, you have several options  available:
 
 ### 1. Creating a Vulnerability Report (preferred):
 

flock_core-0.4.529/docs/about/changelog.md

@@ -0,0 +1,133 @@
+---
+hide: # Optional: Hide table of contents on simple pages
+  - toc
+---
+
+# Changelog 📝
+
+All notable changes to **Flock** will be documented in this file.
+
+The format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- Core concepts & component documentation.
+- Placeholder replacement across docs.
+- Documentation improvements and typo fixes.
+
+---
+
+## [0.4.52] – 2025-05-30
+
+### Added
+- Package versioning updates and dependency improvements.
+
+### Fixed
+- Various bug fixes and stability improvements.
+
+---
+
+## [0.4.51] – 2025-05-24
+
+### Added
+- Enhanced error logging as default log level.
+- Zendesk article count feature.
+- Zendesk tools as MCP server.
+- Configurable protocol support.
+
+### Fixed
+- Removed init definitions for tools to avoid requiring all tool dependencies.
+- Chat in sidebar functionality.
+
+---
+
+## [0.4.5] – 2025-05-21 "MCP Integration"
+
+### Added
+- **Model Context Protocol (MCP) Support**: Declaratively connect to thousands of different tools.
+- MCP server creation with `FlockFactory.create_mcp_server()`.
+- Support for WebSocket, SSE, and STDIO transport protocols.
+- Tool discovery and integration through MCP servers.
+- Enhanced server management and client handling.
+
+### Fixed
+- OTLPSpanExporter crash issues.
+- Literal data type handling in Flock agents.
+- Various serialization and deserialization improvements.
+
+---
+
+## [0.4.3] – 2025-05-21
+
+### Added
+- High-level changelog documentation in README.
+- Enhanced REST API deployment features.
+
+### Changed
+- Updated documentation structure and content.
+
+---
+
+## [0.4.1] – 2025-05-21 "Magpie"
+
+### Added
+- **Magpie** release branding and logo.
+- Enhanced CLI messaging with release information.
+
+### Changed
+- Updated version display in CLI helper.
+- Improved UI design elements.
+
+---
+
+## [0.4.0] – 2025-04-30 "Magpie" 🐤
+
+### Added
+- **REST API Deployment**: Deploy Flock agents as scalable REST API endpoints with `flock.serve()`.
+- **Web UI**: Test and interact with Flock agents directly in browser with integrated web interface.
+- **CLI Tool**: Manage configurations, run agents, and inspect results from terminal.
+- **Enhanced Serialization**: Share, deploy, and run Flocks from YAML files with complete portability.
+- **Batch and Evaluation Modes**: Process multiple inputs and benchmark agents against Q/A pairs.
+- **First-Class Temporal Integration**: Production-grade workflows with retry policies and timeout control.
+- **@flockclass Hydrator**: Turn any Pydantic model into a self-hydrating agent.
+- Custom endpoint support with `FlockEndpoint` for business logic integration.
+- Chat functionality and UI modes (standalone chat, agent execution).
+- Shareable links with frozen agent configurations.
+- Direct feedback system for issue reproduction.
+
+### Changed
+- Major architecture improvements for production deployment.
+- Enhanced documentation with comprehensive guides and examples.
+- Improved serialization system with type safety.
+
+---
+
+## [0.3.0] – 2025-02-24 "Hummingbird"
+
+### Added
+- **Redesigned Core Architecture**: Modular and flexible design with Modules and Evaluators.
+- **FlockFactory**: Pre-configured agents for rapid development.
+- **Module System**: Lifecycle hooks (`initialize`, `pre_evaluate`, `post_evaluate`, `terminate`).
+- **Evaluator System**: `DeclarativeEvaluator` and `NaturalLanguageEvaluator`.
+- **Built-in Modules**: `MemoryModule`, `OutputModule`, and `MetricsModule`.
+- **CLI Interface**: Load flocks, theme builder, settings, advanced mode, and web server.
+- Release notes system with CLI integration.
+
+### Changed
+- `Flock` class initialization updated to include `init_console`.
+- Improved modularity and extensibility throughout the framework.
+
+---
+
+## [0.2.1] – 2025-01-15
+
+### Added
+- Initial public release to PyPI.
+- Declarative agent framework foundation.
+- Basic Temporal execution support.
+- Core tools: `get_web_content_as_markdown`, Azure Blob helper, markdown utilities.
+
+---
+
+*Older history prior to open-source release is maintained internally.*

{flock_core-0.4.528 → flock_core-0.4.529}/docs/about/contributing.md

@@ -23,7 +23,7 @@ First off, thanks for taking the time to contribute!  Flock is still early but w
 
 
 ## 2. Reporting Issues:
-* Before submitting a new issue, pleas check [existing issues](https://github.com/whiteducksoftware/flock/issues) if it has already been reported.
+* Before submitting a new issue, please check [existing issues](https://github.com/whiteducksoftware/flock/issues) if it has already been reported.
 * To submit a new issue, please use the provided **Issue Templates** and provide a clear and descriptive title along with a detailed description of the problem or feature request, including steps to reproduce if it's a bug.
 
 ---
@@ -84,8 +84,4 @@ mkdocs serve  # live-reload at http://localhost:8000
 
 --- 
 
-
-
-
-
 Happy hacking! 🐦

{flock_core-0.4.528 → flock_core-0.4.529}/docs/getting-started/installation.md

@@ -98,6 +98,6 @@ print("Flock imported successfully!")
 
 If this runs without errors, you're all set!
 
-Next Steps
+## Next Steps
 
-With Flock installed, you're ready for the Quick Start guide to build and run your first agent!
+With Flock installed, you're ready for the Quick Start guide to build and run your first agent!

{flock_core-0.4.528 → flock_core-0.4.529}/docs/getting-started/quickstart.md

@@ -102,14 +102,14 @@ Let's break down the magic:
 
 **Define Your Agent Declaratively**: This is the core of Flock! Instead of writing a long prompt, you used FlockFactory.create_default_agent and simply declared:
 
-input="topic: str": The agent needs one input called topic, which should be a string.
+`input="topic: str"`: The agent needs one input called topic, which should be a string.
 
-output="fun_title: str, fun_slide_headers: list[str]": The agent should produce two outputs: fun_title (a string) and fun_slide_headers (a list of strings).
+`output="fun_title: str, fun_slide_headers: list[str]"`: The agent should produce two outputs: fun_title (a string) and fun_slide_headers (a list of strings).
 Flock's default evaluator takes care of constructing the necessary instructions for the LLM based on these declarations and the agent's description.
 
 **Add the Agent**: You registered your presentation_agent with the flock.
 
-**Run the Flock**: flock.run() kicked off the process, starting with your specified agent and input.
+**Run the Flock**: `flock.run()` kicked off the process, starting with your specified agent and input.
 
 **Admire the Results**: Flock executed the agent (calling the LLM behind the scenes) and returned the output as a convenient Box object, allowing you to access the results using dot notation (like result.fun_title).
 
@@ -121,4 +121,4 @@ Explore adding Tools to give your agents superpowers (like web search or code ex
 
 Learn how to Chain Agents together for more complex workflows.
 
-Dive deeper into the Core Concepts that make Flock tick.
+Dive deeper into the Core Concepts that make Flock tick.

{flock_core-0.4.528 → flock_core-0.4.529}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flock-core"
-version = "0.4.528"
+version = "0.4.529"
 description = "Declarative LLM Orchestration at Scale"
 readme = "README.md"
 authors = [
@@ -55,6 +55,8 @@ dependencies = [
     "azure-data-tables>=12.7.0",
     "croniter>=6.0.0",
     "werkzeug>=3.1.3",
+    "azure-storage-blob>=12.25.1",
+    "xlsxwriter>=3.2.3",
 ]
 
 [project.optional-dependencies]

{flock_core-0.4.528 → flock_core-0.4.529}/src/flock/webapp/app/api/execution.py

@@ -1,10 +1,9 @@
 # src/flock/webapp/app/api/execution.py
+import html
 import json
-from datetime import datetime
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
-import html
 import markdown2  # Import markdown2
 from fastapi import (  # Ensure Form and HTTPException are imported
     APIRouter,
@@ -15,6 +14,14 @@ from fastapi import (  # Ensure Form and HTTPException are imported
 from fastapi.encoders import jsonable_encoder
 from fastapi.responses import FileResponse, HTMLResponse
 from fastapi.templating import Jinja2Templates
+from werkzeug.utils import secure_filename
+
+from flock.webapp.app.services.feedback_file_service import (
+    create_csv_feedback_file,
+    create_csv_feedback_file_for_agent,
+    create_xlsx_feedback_file,
+    create_xlsx_feedback_file_for_agent,
+)
 
 if TYPE_CHECKING:
     from flock.core.flock import Flock
@@ -385,6 +392,8 @@ async def htmx_submit_feedback_shared(
     expected_response: str | None = Form(None),
     actual_response: str | None = Form(None),
     flock_definition: str | None = Form(None),
+    flock_name: str | None = Form(None),
+    agent_name: str | None = Form(None),
     store: SharedLinkStoreInterface = Depends(get_shared_link_store),
 ):
     from uuid import uuid4
@@ -399,6 +408,8 @@ async def htmx_submit_feedback_shared(
         expected_response=expected_response,
         actual_response=actual_response,
         flock_definition=flock_definition,
+        agent_name=agent_name,
+        flock_name=flock_name,
     )
     await store.save_feedback(record)
     return HTMLResponse(
@@ -406,9 +417,10 @@ async def htmx_submit_feedback_shared(
     )
 
 
-@router.get("/htmx/feedback-download/", response_class=FileResponse)
+@router.get("/htmx/feedback-download/{format}", response_class=FileResponse)
 async def chat_feedback_download_all(
     request: Request,
+    format: Literal["csv", "xlsx"] = "csv",
     store: SharedLinkStoreInterface = Depends(get_shared_link_store),
 ):
     """Download all feedback records for all agents in the current flock as a CSV file.
@@ -421,170 +433,69 @@ async def chat_feedback_download_all(
         store: The shared link store interface dependency
 
     Returns:
-        FileResponse: CSV file containing all feedback records for all agents
+        FileResponse: CSV/XLSX file containing all feedback records for all agents
 
     Raises:
         HTTPException: If no flock is loaded or no agents are found in the flock
     """
-    import csv
-    import tempfile
-    from pathlib import Path
-
-    # Get the current flock instance to retrieve all agent names
-    from flock.core.flock import Flock
-
-    current_flock_instance: Flock | None = getattr(
-        request.app.state, "flock_instance", None
-    )
-
-    if not current_flock_instance:
-        # If no flock is loaded, return an error response
-        from fastapi import HTTPException
-
-        raise HTTPException(
-            status_code=400, detail="No Flock loaded to download feedback for"
+    safe_format = secure_filename(format)
+    if safe_format == "csv":
+        return await create_csv_feedback_file(
+            request=request,
+            store=store,
+            separator=","
         )
-
-    # Get all agent names from the current flock
-    all_agent_names = list(current_flock_instance.agents.keys())
-
-    if not all_agent_names:
-        # If no agents in the flock, return an error response
+    elif safe_format == "xlsx":
+        return await create_xlsx_feedback_file(
+            request=request,
+            store=store,
+        )
+    else:
         from fastapi import HTTPException
 
         raise HTTPException(
-            status_code=400, detail="No agents found in the current Flock"
+            status_code=400,
+            detail="Invalid file-format specified. Valid formats are: 'csv', 'xlsx'"
         )
 
-    # Collect all feedback records from all agents
-    all_records = []
-    for agent_name in all_agent_names:
-        records = await store.get_all_feedback_records_for_agent(
-            agent_name=agent_name
-        )
-        all_records.extend(records)
-
-    # Create a temporary CSV file
-    temp_dir = tempfile.gettempdir()
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    csv_filename = f"flock_feedback_all_agents_{timestamp}.csv"
-    csv_path = Path(temp_dir) / csv_filename
-
-    # Define CSV headers based on FeedbackRecord fields
-    headers = [
-        "feedback_id",
-        "share_id",
-        "context_type",
-        "reason",
-        "expected_response",
-        "actual_response",
-        "created_at",
-        "flock_name",
-        "agent_name",
-        "flock_definition",
-    ]
-
-    # Write records to CSV
-    with open(csv_path, "w", newline="", encoding="utf-8") as csvfile:
-        writer = csv.DictWriter(csvfile, fieldnames=headers)
-        writer.writeheader()
-
-        for record in all_records:
-            # Convert the Pydantic model to dict and ensure all fields are present
-            row_data = {}
-            for header in headers:
-                value = getattr(record, header, None)
-                # Convert datetime to ISO string for CSV
-                if header == "created_at" and value:
-                    row_data[header] = (
-                        value.isoformat()
-                        if isinstance(value, datetime)
-                        else str(value)
-                    )
-                else:
-                    row_data[header] = str(value) if value is not None else ""
-            writer.writerow(row_data)
-
-    # Return FileResponse with the CSV file
-    return FileResponse(
-        path=str(csv_path),
-        filename=csv_filename,
-        media_type="text/csv",
-        headers={"Content-Disposition": f"attachment; filename={csv_filename}"},
-    )
 
-
-@router.get("/htmx/feedback-download/{agent_name}", response_class=FileResponse)
+@router.get("/htmx/feedback-download/{agent_name}/{format}", response_class=FileResponse)
 async def chat_feedback_download(
     request: Request,
     agent_name: str,
+    format: Literal["csv", "xlsx"] = "csv",
     store: SharedLinkStoreInterface = Depends(get_shared_link_store),
 ):
-    """Download all feedback records for a specific agent as a CSV file.
+    """Download all feedback records for a specific agent as a file.
 
     Args:
         request: The FastAPI request object
         agent_name: Name of the agent to download feedback for
         store: The shared link store interface dependency
+        format: Either 'csv' or 'xlsx' the file format to use
 
     Returns:
-        FileResponse: CSV file containing all feedback records for the specified agent
+        FileResponse: CSV/XLSX file containing all feedback records for the specified agent
     """
-    import csv
-    import tempfile
-    from pathlib import Path
-    from werkzeug.utils import secure_filename
-
-    records = await store.get_all_feedback_records_for_agent(
-        agent_name=agent_name
-    )
-
-    # Create a temporary CSV file
-    temp_dir = tempfile.gettempdir()
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    safe_format = secure_filename(format)
     safe_agent_name = secure_filename(agent_name)
-    csv_filename = f"flock_feedback_{safe_agent_name}_{timestamp}.csv"
-    csv_path = Path(temp_dir) / csv_filename
-
-    # Define CSV headers based on FeedbackRecord fields
-    headers = [
-        "feedback_id",
-        "share_id",
-        "context_type",
-        "reason",
-        "expected_response",
-        "actual_response",
-        "created_at",
-        "flock_name",
-        "agent_name",
-        "flock_definition",
-    ]
-
-    # Write records to CSV
-    with open(csv_path, "w", newline="", encoding="utf-8") as csvfile:
-        writer = csv.DictWriter(csvfile, fieldnames=headers)
-        writer.writeheader()
-
-        for record in records:
-            # Convert the Pydantic model to dict and ensure all fields are present
-            row_data = {}
-            for header in headers:
-                value = getattr(record, header, None)
-                # Convert datetime to ISO string for CSV
-                if header == "created_at" and value:
-                    row_data[header] = (
-                        value.isoformat()
-                        if isinstance(value, datetime)
-                        else str(value)
-                    )
-                else:
-                    row_data[header] = str(value) if value is not None else ""
-            writer.writerow(row_data)
-
-    # Return FileResponse with the CSV file
-    return FileResponse(
-        path=str(csv_path),
-        filename=csv_filename,
-        media_type="text/csv",
-        headers={"Content-Disposition": f"attachment; filename={csv_filename}"},
-    )
+    if safe_format == "csv":
+        return await create_csv_feedback_file_for_agent(
+            request=request,
+            store=store,
+            separator=",",
+            agent_name=safe_agent_name,
+        )
+    elif safe_format == "xlsx":
+        return await create_xlsx_feedback_file_for_agent(
+            request=request,
+            store=store,
+            agent_name=safe_agent_name,
+        )
+    else:
+        from fastapi import HTTPException
+
+        raise HTTPException(
+            status_code=400,
+            detail="Invalid file-format specified. Valid formats are: 'csv', 'xlsx'"
+        )