flock-core 0.4.528__py3-none-any.whl → 0.5.0b0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of flock-core might be problematic. Click here for more details.

Files changed (130) hide show
  1. flock/cli/execute_flock.py +1 -1
  2. flock/cli/manage_agents.py +6 -6
  3. flock/components/__init__.py +30 -0
  4. flock/components/evaluation/__init__.py +9 -0
  5. flock/components/evaluation/declarative_evaluation_component.py +222 -0
  6. flock/components/routing/__init__.py +15 -0
  7. flock/{routers/conditional/conditional_router.py → components/routing/conditional_routing_component.py} +61 -53
  8. flock/components/routing/default_routing_component.py +103 -0
  9. flock/components/routing/llm_routing_component.py +206 -0
  10. flock/components/utility/__init__.py +15 -0
  11. flock/{modules/enterprise_memory/enterprise_memory_module.py → components/utility/memory_utility_component.py} +195 -173
  12. flock/{modules/performance/metrics_module.py → components/utility/metrics_utility_component.py} +110 -95
  13. flock/{modules/output/output_module.py → components/utility/output_utility_component.py} +47 -45
  14. flock/core/__init__.py +26 -18
  15. flock/core/agent/__init__.py +16 -0
  16. flock/core/agent/flock_agent_components.py +104 -0
  17. flock/core/agent/flock_agent_execution.py +101 -0
  18. flock/core/agent/flock_agent_integration.py +206 -0
  19. flock/core/agent/flock_agent_lifecycle.py +177 -0
  20. flock/core/agent/flock_agent_serialization.py +381 -0
  21. flock/core/api/endpoints.py +2 -2
  22. flock/core/api/service.py +2 -2
  23. flock/core/component/__init__.py +15 -0
  24. flock/core/{flock_module.py → component/agent_component_base.py} +136 -34
  25. flock/core/component/evaluation_component.py +56 -0
  26. flock/core/component/routing_component.py +74 -0
  27. flock/core/component/utility_component.py +69 -0
  28. flock/core/config/flock_agent_config.py +49 -2
  29. flock/core/evaluation/utils.py +3 -2
  30. flock/core/execution/batch_executor.py +1 -1
  31. flock/core/execution/evaluation_executor.py +2 -2
  32. flock/core/execution/opik_executor.py +1 -1
  33. flock/core/flock.py +147 -493
  34. flock/core/flock_agent.py +195 -1032
  35. flock/core/flock_factory.py +114 -90
  36. flock/core/flock_scheduler.py +1 -1
  37. flock/core/flock_server_manager.py +8 -8
  38. flock/core/logging/logging.py +1 -0
  39. flock/core/mcp/flock_mcp_server.py +53 -48
  40. flock/core/mcp/{flock_mcp_tool_base.py → flock_mcp_tool.py} +2 -2
  41. flock/core/mcp/mcp_client.py +9 -9
  42. flock/core/mcp/mcp_client_manager.py +9 -9
  43. flock/core/mcp/mcp_config.py +24 -24
  44. flock/core/mixin/dspy_integration.py +5 -5
  45. flock/core/orchestration/__init__.py +18 -0
  46. flock/core/orchestration/flock_batch_processor.py +94 -0
  47. flock/core/orchestration/flock_evaluator.py +113 -0
  48. flock/core/orchestration/flock_execution.py +288 -0
  49. flock/core/orchestration/flock_initialization.py +125 -0
  50. flock/core/orchestration/flock_server_manager.py +67 -0
  51. flock/core/orchestration/flock_web_server.py +117 -0
  52. flock/core/registry/__init__.py +45 -0
  53. flock/core/registry/agent_registry.py +69 -0
  54. flock/core/registry/callable_registry.py +139 -0
  55. flock/core/registry/component_discovery.py +142 -0
  56. flock/core/registry/component_registry.py +64 -0
  57. flock/core/registry/config_mapping.py +64 -0
  58. flock/core/registry/decorators.py +137 -0
  59. flock/core/registry/registry_hub.py +205 -0
  60. flock/core/registry/server_registry.py +57 -0
  61. flock/core/registry/type_registry.py +86 -0
  62. flock/core/serialization/flock_serializer.py +36 -32
  63. flock/core/serialization/serialization_utils.py +28 -25
  64. flock/core/util/hydrator.py +1 -1
  65. flock/core/util/input_resolver.py +29 -2
  66. flock/mcp/servers/sse/flock_sse_server.py +10 -10
  67. flock/mcp/servers/stdio/flock_stdio_server.py +10 -10
  68. flock/mcp/servers/streamable_http/flock_streamable_http_server.py +10 -10
  69. flock/mcp/servers/websockets/flock_websocket_server.py +10 -10
  70. flock/platform/docker_tools.py +3 -3
  71. flock/webapp/app/chat.py +1 -1
  72. flock/webapp/app/main.py +9 -5
  73. flock/webapp/app/services/flock_service.py +1 -1
  74. flock/webapp/app/services/sharing_store.py +1 -0
  75. flock/workflow/activities.py +67 -92
  76. flock/workflow/agent_execution_activity.py +6 -6
  77. flock/workflow/flock_workflow.py +1 -1
  78. flock_core-0.5.0b0.dist-info/METADATA +272 -0
  79. {flock_core-0.4.528.dist-info → flock_core-0.5.0b0.dist-info}/RECORD +82 -95
  80. flock/core/flock_evaluator.py +0 -60
  81. flock/core/flock_registry.py +0 -702
  82. flock/core/flock_router.py +0 -83
  83. flock/evaluators/__init__.py +0 -1
  84. flock/evaluators/declarative/__init__.py +0 -1
  85. flock/evaluators/declarative/declarative_evaluator.py +0 -217
  86. flock/evaluators/memory/memory_evaluator.py +0 -90
  87. flock/evaluators/test/test_case_evaluator.py +0 -38
  88. flock/evaluators/zep/zep_evaluator.py +0 -59
  89. flock/modules/__init__.py +0 -1
  90. flock/modules/assertion/__init__.py +0 -1
  91. flock/modules/assertion/assertion_module.py +0 -286
  92. flock/modules/callback/__init__.py +0 -1
  93. flock/modules/callback/callback_module.py +0 -91
  94. flock/modules/enterprise_memory/README.md +0 -99
  95. flock/modules/mem0/__init__.py +0 -1
  96. flock/modules/mem0/mem0_module.py +0 -126
  97. flock/modules/mem0_async/__init__.py +0 -1
  98. flock/modules/mem0_async/async_mem0_module.py +0 -126
  99. flock/modules/memory/__init__.py +0 -1
  100. flock/modules/memory/memory_module.py +0 -429
  101. flock/modules/memory/memory_parser.py +0 -125
  102. flock/modules/memory/memory_storage.py +0 -736
  103. flock/modules/output/__init__.py +0 -1
  104. flock/modules/performance/__init__.py +0 -1
  105. flock/modules/zep/__init__.py +0 -1
  106. flock/modules/zep/zep_module.py +0 -192
  107. flock/routers/__init__.py +0 -1
  108. flock/routers/agent/__init__.py +0 -1
  109. flock/routers/agent/agent_router.py +0 -236
  110. flock/routers/agent/handoff_agent.py +0 -58
  111. flock/routers/default/__init__.py +0 -1
  112. flock/routers/default/default_router.py +0 -80
  113. flock/routers/feedback/feedback_router.py +0 -114
  114. flock/routers/list_generator/list_generator_router.py +0 -166
  115. flock/routers/llm/__init__.py +0 -1
  116. flock/routers/llm/llm_router.py +0 -365
  117. flock/tools/__init__.py +0 -0
  118. flock/tools/azure_tools.py +0 -781
  119. flock/tools/code_tools.py +0 -167
  120. flock/tools/file_tools.py +0 -149
  121. flock/tools/github_tools.py +0 -157
  122. flock/tools/markdown_tools.py +0 -205
  123. flock/tools/system_tools.py +0 -9
  124. flock/tools/text_tools.py +0 -810
  125. flock/tools/web_tools.py +0 -90
  126. flock/tools/zendesk_tools.py +0 -147
  127. flock_core-0.4.528.dist-info/METADATA +0 -675
  128. {flock_core-0.4.528.dist-info → flock_core-0.5.0b0.dist-info}/WHEEL +0 -0
  129. {flock_core-0.4.528.dist-info → flock_core-0.5.0b0.dist-info}/entry_points.txt +0 -0
  130. {flock_core-0.4.528.dist-info → flock_core-0.5.0b0.dist-info}/licenses/LICENSE +0 -0
@@ -1,675 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: flock-core
3
- Version: 0.4.528
4
- Summary: Declarative LLM Orchestration at Scale
5
- Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
6
- License-File: LICENSE
7
- Classifier: License :: OSI Approved :: MIT License
8
- Classifier: Operating System :: OS Independent
9
- Classifier: Programming Language :: Python :: 3
10
- Requires-Python: >=3.10
11
- Requires-Dist: aiosqlite>=0.21.0
12
- Requires-Dist: azure-data-tables>=12.7.0
13
- Requires-Dist: cloudpickle>=3.1.1
14
- Requires-Dist: croniter>=6.0.0
15
- Requires-Dist: devtools>=0.12.2
16
- Requires-Dist: dspy==2.6.23
17
- Requires-Dist: fastapi>=0.115.8
18
- Requires-Dist: httpx>=0.28.1
19
- Requires-Dist: litellm==1.69.3
20
- Requires-Dist: loguru>=0.7.3
21
- Requires-Dist: markdown2>=2.5.3
22
- Requires-Dist: mcp>=1.7.1
23
- Requires-Dist: msgpack>=1.1.0
24
- Requires-Dist: openai==1.75.0
25
- Requires-Dist: opentelemetry-api>=1.30.0
26
- Requires-Dist: opentelemetry-exporter-jaeger-proto-grpc>=1.21.0
27
- Requires-Dist: opentelemetry-exporter-jaeger>=1.21.0
28
- Requires-Dist: opentelemetry-exporter-otlp>=1.30.0
29
- Requires-Dist: opentelemetry-instrumentation-logging>=0.51b0
30
- Requires-Dist: opentelemetry-sdk>=1.30.0
31
- Requires-Dist: opik>=1.7.26
32
- Requires-Dist: pandas>=2.2.3
33
- Requires-Dist: pillow>=10.4.0
34
- Requires-Dist: prometheus-client>=0.21.1
35
- Requires-Dist: psutil>=6.1.1
36
- Requires-Dist: pydantic-settings>=2.7.1
37
- Requires-Dist: pydantic==2.10.5
38
- Requires-Dist: python-box>=7.3.2
39
- Requires-Dist: python-decouple>=3.8
40
- Requires-Dist: python-dotenv>=1.0.1
41
- Requires-Dist: pyyaml>=6.0
42
- Requires-Dist: questionary>=2.1.0
43
- Requires-Dist: rich>=13.9.4
44
- Requires-Dist: temporalio>=1.9.0
45
- Requires-Dist: thefuzz>=0.22.1
46
- Requires-Dist: tiktoken>=0.8.0
47
- Requires-Dist: toml>=0.10.2
48
- Requires-Dist: tqdm>=4.60.1
49
- Requires-Dist: uvicorn>=0.34.0
50
- Requires-Dist: wd-di>=0.2.14
51
- Requires-Dist: websockets>=15.0.1
52
- Requires-Dist: werkzeug>=3.1.3
53
- Provides-Extra: all
54
- Requires-Dist: azure-identity>=1.23.0; extra == 'all'
55
- Requires-Dist: azure-search-documents>=11.5.2; extra == 'all'
56
- Requires-Dist: azure-storage-blob>=12.25.1; extra == 'all'
57
- Requires-Dist: chromadb>=0.6.3; extra == 'all'
58
- Requires-Dist: datasets>=3.2.0; extra == 'all'
59
- Requires-Dist: docling>=2.34.0; extra == 'all'
60
- Requires-Dist: duckduckgo-search>=7.3.2; extra == 'all'
61
- Requires-Dist: markdownify>=0.14.1; extra == 'all'
62
- Requires-Dist: matplotlib>=3.10.0; extra == 'all'
63
- Requires-Dist: mem0ai[graph]>=0.1.101; extra == 'all'
64
- Requires-Dist: nltk>=3.9.1; extra == 'all'
65
- Requires-Dist: rouge-score>=0.1.2; extra == 'all'
66
- Requires-Dist: sentence-transformers>=3.4.1; extra == 'all'
67
- Requires-Dist: tavily-python>=0.5.0; extra == 'all'
68
- Requires-Dist: zep-python>=2.0.2; extra == 'all'
69
- Provides-Extra: all-tools
70
- Requires-Dist: azure-identity>=1.23.0; extra == 'all-tools'
71
- Requires-Dist: azure-search-documents>=11.5.2; extra == 'all-tools'
72
- Requires-Dist: azure-storage-blob>=12.25.1; extra == 'all-tools'
73
- Requires-Dist: docker>=7.1.0; extra == 'all-tools'
74
- Requires-Dist: docling>=2.34.0; extra == 'all-tools'
75
- Requires-Dist: duckduckgo-search>=7.3.2; extra == 'all-tools'
76
- Requires-Dist: markdownify>=0.14.1; extra == 'all-tools'
77
- Requires-Dist: nltk>=3.9.1; extra == 'all-tools'
78
- Requires-Dist: tavily-python>=0.5.0; extra == 'all-tools'
79
- Provides-Extra: azure-tools
80
- Requires-Dist: azure-identity>=1.23.0; extra == 'azure-tools'
81
- Requires-Dist: azure-search-documents>=11.5.2; extra == 'azure-tools'
82
- Requires-Dist: azure-storage-blob>=12.25.1; extra == 'azure-tools'
83
- Provides-Extra: basic-tools
84
- Requires-Dist: docling>=2.34.0; extra == 'basic-tools'
85
- Requires-Dist: duckduckgo-search>=7.3.2; extra == 'basic-tools'
86
- Requires-Dist: markdownify>=0.14.1; extra == 'basic-tools'
87
- Requires-Dist: tavily-python>=0.5.0; extra == 'basic-tools'
88
- Provides-Extra: code-tools
89
- Requires-Dist: docker>=7.1.0; extra == 'code-tools'
90
- Provides-Extra: evaluation
91
- Requires-Dist: datasets>=3.2.0; extra == 'evaluation'
92
- Requires-Dist: rouge-score>=0.1.2; extra == 'evaluation'
93
- Requires-Dist: sentence-transformers>=3.4.1; extra == 'evaluation'
94
- Provides-Extra: llm-tools
95
- Requires-Dist: nltk>=3.9.1; extra == 'llm-tools'
96
- Provides-Extra: memory
97
- Requires-Dist: chromadb>=0.6.3; extra == 'memory'
98
- Requires-Dist: matplotlib>=3.10.0; extra == 'memory'
99
- Requires-Dist: mem0ai[graph]>=0.1.101; extra == 'memory'
100
- Requires-Dist: zep-python>=2.0.2; extra == 'memory'
101
- Description-Content-Type: text/markdown
102
-
103
- <p align="center">
104
- <!-- Placeholder for your Flock Logo/Banner - Replace URL -->
105
- <img alt="Flock Banner" src="https://raw.githubusercontent.com/whiteducksoftware/flock/master/docs/assets/images/flock.png" width="600">
106
- </p>
107
- <p align="center">
108
- <!-- Update badges -->
109
- <a href="https://pypi.org/project/flock-core/" target="_blank"><img alt="PyPI Version" src="https://img.shields.io/pypi/v/flock-core?style=for-the-badge&logo=pypi&label=pip%20version"></a>
110
- <img alt="Python Version" src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python">
111
- <a href="https://github.com/whiteducksoftware/flock/actions/workflows/deploy-whiteduck-pypi.yml" target="_blank"><img alt="CI Status" src="https://img.shields.io/github/actions/workflow/status/whiteducksoftware/flock/deploy-whiteduck-pypi.yml?branch=master&style=for-the-badge&logo=githubactions&logoColor=white"></a>
112
- <a href="https://github.com/whiteducksoftware/flock/blob/master/LICENSE" target="_blank"><img alt="License" src="https://img.shields.io/pypi/l/flock-core?style=for-the-badge"></a>
113
- <a href="https://whiteduck.de" target="_blank"><img alt="Built by white duck" src="https://img.shields.io/badge/Built%20by-white%20duck%20GmbH-white?style=for-the-badge&labelColor=black"></a>
114
- <a href="https://www.linkedin.com/company/whiteduck" target="_blank"><img alt="LinkedIn" src="https://img.shields.io/badge/linkedin-%230077B5.svg?style=for-the-badge&logo=linkedin&logoColor=white&label=whiteduck"></a>
115
- <a href="https://bsky.app/profile/whiteduck-gmbh.bsky.social" target="_blank"><img alt="Bluesky" src="https://img.shields.io/badge/bluesky-Follow-blue?style=for-the-badge&logo=bluesky&logoColor=%23fff&color=%23333&labelColor=%230285FF&label=whiteduck-gmbh"></a>
116
- </p>
117
-
118
-
119
- ---
120
-
121
-
122
- ## The Problem You Know Too Well
123
-
124
- 🤯 **Prompt Hell**: Brittle 500-line prompts that break with every model update.
125
- 💥 **System Failures**: One bad LLM response crashes your entire workflow
126
- 🧪 **Testing Nightmares**: "How do I unit test a prompt?" (You don't.)
127
- 🧪 **Measuring Quality**: "How do I know my prompts are close to optimal?" (You also don't.)
128
- 📄 **Output Chaos**: Parsing unstructured LLM responses into reliable data
129
- ⛓️ **Orchestration Limits**: Moving beyond simple chains and DAGs? Good luck
130
- 🚀 **Production Gap**: Jupyter notebooks don't scale to enterprise systems
131
-
132
- *After building dozens of AI systems for enterprise clients, we realized the tooling was fundamentally broken.*
133
-
134
-
135
- **Build with agents, not against them.**
136
-
137
-
138
- ## The Flock Solution
139
-
140
- **What if you could just skip that 'prompt engineering' step?**
141
-
142
- Flock is an agent framework for declarative AI workflows. You define what goes in and what should come out, the how is handled by the agent.
143
- No brittle prompts. No guesswork. Just reliable, testable AI agents.
144
-
145
-
146
- ✅ **Declarative Contracts**: Define inputs/outputs with Pydantic models. Flock handles the LLM complexity.
147
- ⚡ **Built-in Resilience**: Automatic retries, state persistence, and workflow resumption via Temporal.io
148
- 🧪 **Actually Testable**: Clear contracts make agents unit-testable like any other code
149
- 🧪 **Optimal Quality**: Agents posses multiple self-optimization algorithms based on latest research
150
- 🚀 **Dynamic Workflows**: Self-correcting loops, conditional routing, and intelligent decision-making
151
- 🔧 **Zero-Config Production**: Deploy as REST APIs with one command. Scale without rewriting.
152
-
153
- **Ready to see it in action?**
154
-
155
- ## ⚡ Quick Start
156
-
157
- ```python
158
- from flock.core import Flock, FlockFactory
159
-
160
- # 1. Create the main orchestrator
161
- my_flock = Flock(model="openai/gpt-4o")
162
-
163
- # 2. Declaratively define an agent
164
- brainstorm_agent = FlockFactory.create_default_agent(
165
- name="idea_generator",
166
- input="topic",
167
- output="catchy_title, key_points"
168
- )
169
-
170
- # 3. Add the agent to the Flock
171
- my_flock.add_agent(brainstorm_agent)
172
-
173
- # 4. Run the agent!
174
- input_data = {"topic": "The future of AI agents"}
175
- result = my_flock.run(start_agent="idea_generator", input=input_data)
176
-
177
- # The result is a Box object (dot-accessible dict)
178
- print(f"Generated Title: {result.catchy_title}")
179
- print(f"Key Points: {result.key_points}")
180
- ```
181
-
182
- **No 20-line prompt fiddling. Just structured output, every time.**
183
-
184
- ![image](https://github.com/user-attachments/assets/37a897cb-910f-49fc-89d4-510a780ad775)
185
-
186
- **Explore more examples →** [**Flock Showcase Repository**](https://github.com/whiteducksoftware/flock-showcase)
187
-
188
- ## 📹 Video Demo
189
-
190
- https://github.com/user-attachments/assets/bdab4786-d532-459f-806a-024727164dcc
191
-
192
-
193
-
194
- ## 💾 Installation - Use Flock in your project
195
-
196
- Get started with the core Flock library:
197
-
198
- ```bash
199
- # Using uv (recommended)
200
- uv pip install flock-core
201
-
202
- # Using pip
203
- pip install flock-core
204
- ```
205
-
206
- Extras: Install optional dependencies for specific features:
207
-
208
- ```bash
209
- # Common tools (Tavily, Markdownify)
210
- uv pip install flock-core[all-tools]
211
-
212
- # All optional dependencies (including tools, docling, etc.)
213
- uv sync --all-extras
214
- ```
215
-
216
- ## 🔑 Installation - Develop Flock
217
-
218
- ```bash
219
- git clone https://github.com/whiteducksoftware/flock.git
220
- cd flock
221
-
222
- # One-liner dev setup after cloning
223
- pip install poethepoet && poe install
224
- ```
225
-
226
- Additional provided `poe` tasks and commands:
227
-
228
- ```bash
229
- poe install # Install the project
230
- poe build # Build the project
231
- poe docs # Serve the docs
232
- poe format # Format the code
233
- poe lint # Lint the code
234
- ```
235
-
236
- ## 🔑 Environment Setup
237
-
238
- Flock uses environment variables (typically in a .env file) for configuration, especially API keys. Create a .env file in your project root:
239
-
240
- ```bash
241
- # .env - Example
242
-
243
- # --- LLM Provider API Keys (Required by most examples) ---
244
- # Add keys for providers you use (OpenAI, Anthropic, Gemini, Azure, etc.)
245
- # Refer to litellm docs (https://docs.litellm.ai/docs/providers) for names
246
- OPENAI_API_KEY="your-openai-api-key"
247
- # ANTHROPIC_API_KEY="your-anthropic-api-key"
248
-
249
- # --- Tool-Specific Keys (Optional) ---
250
- # TAVILY_API_KEY="your-tavily-search-key"
251
- # GITHUB_PAT="your-github-personal-access-token"
252
-
253
- # --- Default Flock Settings (Optional) ---
254
- DEFAULT_MODEL="openai/gpt-4o" # Default LLM if agent doesn't specify
255
-
256
- # --- Flock CLI Settings (Managed by `flock settings`) ---
257
- # SHOW_SECRETS="False"
258
- # VARS_PER_PAGE="20"
259
- ```
260
-
261
- Be sure that the .env file is added to your .gitignore!
262
-
263
-
264
- ## 🐤 New in Flock 0.4.0 `Magpie` 🐤
265
- <p align="center">
266
- <img width="300" alt="image" src="https://github.com/user-attachments/assets/34c2fe2f-6dd2-498c-a826-1687cb158755" />
267
- </p>
268
-
269
- ### 0.4.5 - MCP Support - Declaratively connect to 1000s of different tools!
270
-
271
- Create a server
272
-
273
- ```python
274
- ws_fetch_server = FlockFactory.create_mcp_server(
275
- name="fetch_server",
276
- enable_tools_feature=True,
277
- connection_params=FlockFactory.WebsocketParams(
278
- url="ws://localhost:4001/message"
279
- ),
280
- ```
281
-
282
- Add it to Flock
283
-
284
- ```python
285
- flock = Flock(
286
- name="mcp_testbed",
287
- servers=[
288
- ws_fetch_server
289
- ]
290
- )
291
- ```
292
-
293
- And tell the flock agents which server to use
294
-
295
- ```python
296
- webcrawler_agent = FlockFactory.create_default_agent(
297
- name="webcrawler_agent",
298
- description="Expert for looking up and retrieving web content",
299
- input="query: str | User-Query, initial_url: Optional[str] | Optional url to start search from.",
300
- output="answer: str | Answer to user-query, page_url: str | The url of the page where the answer was found on, page_content: str | Markdown content of the page where the answer was found.",
301
- servers=[ws_fetch_server], # servers are passed here.
302
- )
303
- ```
304
-
305
- Done! The Flock agent has now access to every tool the server offers.
306
-
307
-
308
- ### 🚀 REST API – Deploy Flock Agents as REST API Endpoints
309
-
310
- Easily deploy your Flock agents as scalable REST API endpoints. Interact with your agent workflows via standard HTTP requests.
311
-
312
- The all-in-one `flock.serve()` method turns your Flock into a proper REST API!
313
-
314
- <img width="1135" alt="image" src="https://github.com/user-attachments/assets/95a58e96-d866-4fd1-aca3-c7635843503c" />
315
-
316
- Need custom endpoints to wrap abstract agent logic or add business logic? We've got you.
317
- Define them. Declaratively.
318
-
319
- ```python
320
- word_count_route = FlockEndpoint(
321
- path="/api/word_count",
322
- methods=["GET"],
323
- callback=word_count,
324
- query_model=WordCountParams,
325
- response_model=WordCountResponse,
326
- summary="Counts words in a text",
327
- description="Takes a text and returns the number of words in it.",
328
- )
329
-
330
- flock.serve(custom_endpoints=[img_url_route, word_count_route, yoda_route])
331
- ```
332
-
333
- <img width="1135" alt="image" src="https://github.com/user-attachments/assets/d9315648-ac10-4129-aca4-1cb4c8835672" />
334
-
335
- Want chat and UI too? Just turn them on.
336
-
337
- ```python
338
- flock.serve(ui=True, chat=True)
339
- ```
340
-
341
- ---
342
-
343
- ### 🖥️ Web UI – Test Flock Agents in the Browser
344
-
345
- Test and interact with your Flock agents directly in your browser using an integrated web interface.
346
-
347
- ![image](https://github.com/user-attachments/assets/5746ae82-757b-43a3-931d-56d19d39371a)
348
-
349
- Highlights of this feature-rich interface:
350
-
351
- * Run all your agents and agent flows
352
- * Chat with your agents
353
- * Create sharable links – these freeze agent config so testers can focus on evaluation
354
- * Send direct feedback – includes everything needed to reproduce issues
355
- * Switch modes – like standalone chat mode, which hides all but the chat
356
-
357
- <img width="1135" alt="image" src="https://github.com/user-attachments/assets/398337ee-e56e-4bce-8bd8-d258c261cb64" />
358
-
359
- And much, much more... All features are based on real-world client feedback and serve actual business needs.
360
-
361
- ---
362
-
363
- ### ⌨️ CLI Tool – Manage Flock Agents via Command Line
364
-
365
- Manage configurations, run agents, and inspect results – all from your terminal. A quick way to test and validate serialized flocks.
366
-
367
- ![image](https://github.com/user-attachments/assets/9370e7e8-94c3-4e26-8c7e-46ff2edd667a)
368
-
369
- ---
370
-
371
- ### 💾 Enhanced Serialization – Share, Deploy, and Run Flocks from YAML
372
-
373
- Define and share entire Flock configurations using readable YAML files. Perfect for versioning, deployment, and portability.
374
-
375
- Take note how even custom types like `FantasyCharacter` are serialized so the target system doesn't even need your code! Everything portable!
376
-
377
- ```yaml
378
- name: pydantic_example
379
- model: openai/gpt-4o
380
- enable_temporal: false
381
- show_flock_banner: false
382
- temporal_start_in_process_worker: true
383
- agents:
384
- character_agent:
385
- name: character_agent
386
- model: openai/gpt-4o
387
- description: Generates fantasy RPG character profiles for a specified number of
388
- characters.
389
- input: 'number_of_characters: int | The number of fantasy character profiles to
390
- generate.'
391
- output: 'character_list: list[FantasyCharacter] | A list containing the generated
392
- character profiles.'
393
- write_to_file: false
394
- wait_for_input: false
395
- evaluator:
396
- name: default
397
- config:
398
- model: openai/gpt-4o
399
- use_cache: true
400
- temperature: 0.8
401
- max_tokens: 8192
402
- stream: false
403
- include_thought_process: false
404
- kwargs: {}
405
- type: DeclarativeEvaluator
406
- modules:
407
- output:
408
- name: output
409
- config:
410
- enabled: true
411
- theme: abernathy
412
- render_table: false
413
- max_length: 1000
414
- truncate_long_values: true
415
- show_metadata: true
416
- format_code_blocks: true
417
- custom_formatters: {}
418
- no_output: false
419
- print_context: false
420
- type: OutputModule
421
- metrics:
422
- name: metrics
423
- config:
424
- enabled: true
425
- collect_timing: true
426
- collect_memory: true
427
- collect_token_usage: true
428
- collect_cpu: true
429
- storage_type: json
430
- metrics_dir: metrics/
431
- aggregation_interval: 1h
432
- retention_days: 30
433
- alert_on_high_latency: true
434
- latency_threshold_ms: 30000
435
- type: MetricsModule
436
- types:
437
- FantasyCharacter:
438
- module_path: __main__
439
- type: pydantic.BaseModel
440
- schema:
441
- description: 'Data model for fantasy RPG character information.
442
-
443
- Docstrings and Field descriptions can help guide the LLM.'
444
- properties:
445
- name:
446
- description: A creative fantasy character name.
447
- title: Name
448
- type: string
449
- race:
450
- description: The character's race.
451
- enum:
452
- - human
453
- - elf
454
- - dwarf
455
- - orc
456
- - halfling
457
- title: Race
458
- type: string
459
- class_type:
460
- description: The character's class.
461
- enum:
462
- - warrior
463
- - mage
464
- - rogue
465
- - cleric
466
- - ranger
467
- title: Class Type
468
- type: string
469
- level:
470
- description: Character level
471
- title: Level
472
- type: integer
473
- strength:
474
- description: Strength stat
475
- title: Strength
476
- type: integer
477
- dexterity:
478
- description: Dexterity stat
479
- title: Dexterity
480
- type: integer
481
- constitution:
482
- description: Constitution stat
483
- title: Constitution
484
- type: integer
485
- intelligence:
486
- description: Intelligence stat
487
- title: Intelligence
488
- type: integer
489
- wisdom:
490
- description: Wisdom stat
491
- title: Wisdom
492
- type: integer
493
- charisma:
494
- description: Charisma stat
495
- title: Charisma
496
- type: integer
497
- weapons:
498
- description: A list of weapons the character carries.
499
- items:
500
- type: string
501
- title: Weapons
502
- type: array
503
- backstory:
504
- description: A brief, engaging backstory (2-3 sentences).
505
- title: Backstory
506
- type: string
507
- motivation:
508
- description: The character's motivation for their adventuring.
509
- title: Motivation
510
- type: string
511
- alignment:
512
- description: Character's moral alignment
513
- title: Alignment
514
- type: string
515
- required:
516
- - name
517
- - race
518
- - class_type
519
- - level
520
- - strength
521
- - dexterity
522
- - constitution
523
- - intelligence
524
- - wisdom
525
- - charisma
526
- - weapons
527
- - backstory
528
- - motivation
529
- - alignment
530
- type: object
531
- components:
532
- DeclarativeEvaluator:
533
- type: flock_component
534
- module_path: flock.evaluators.declarative.declarative_evaluator
535
- file_path: src\\flock\\evaluators\\declarative\\declarative_evaluator.py
536
- description: Evaluator that uses DSPy for generation.
537
- OutputModule:
538
- type: flock_component
539
- module_path: flock.modules.output.output_module
540
- file_path: src\\flock\\modules\\output\\output_module.py
541
- description: Module that handles output formatting and display.
542
- MetricsModule:
543
- type: flock_component
544
- module_path: flock.modules.performance.metrics_module
545
- file_path: src\\flock\\modules\\performance\\metrics_module.py
546
- description: Module for collecting and analyzing agent performance metrics.
547
- dependencies:
548
- - pydantic>=2.0.0
549
- - flock-core>=0.4.0
550
- metadata:
551
- path_type: relative
552
- flock_version: 0.4.0
553
-
554
- ```
555
-
556
- Why is text-based serialization cool? Because agents can manipulate their own config – go wild with meta agents and experiments.
557
-
558
- ---
559
-
560
- ### 🌀 New Execution Flows – Batch and Evaluation Modes
561
-
562
- Run Flock in batch mode to process multiple inputs or in evaluation mode to benchmark agents against question/answer pairs.
563
-
564
- ```python
565
- batch_data = [
566
- {"topic": "Robot Kittens", "audience": "Tech Enthusiasts"},
567
- {"topic": "AI in Gardening", "audience": "Homeowners"},
568
- ...
569
- ]
570
-
571
- static_data = {"number_of_slides": 6}
572
-
573
- silent_results = flock.run_batch(
574
- start_agent=presentation_agent,
575
- batch_inputs=batch_data,
576
- static_inputs=static_data,
577
- parallel=True,
578
- max_workers=5,
579
- silent_mode=True,
580
- return_errors=True,
581
- write_to_csv=".flock/batch_results.csv",
582
- )
583
- ```
584
-
585
- Supports CSV in and out. Combine with `.evaluate()` to benchmark Flock with known Q/A sets.
586
-
587
- ---
588
-
589
- ### ⏱️ First-Class Temporal Integration
590
-
591
- Flock 0.4.0 brings seamless integration with Temporal.io. Build production-grade, reliable, and scalable agent workflows.
592
-
593
- ```python
594
- flock = Flock(
595
- enable_temporal=True,
596
- temporal_config=TemporalWorkflowConfig(
597
- task_queue="flock-test-queue",
598
- workflow_execution_timeout=timedelta(minutes=10),
599
- default_activity_retry_policy=TemporalRetryPolicyConfig(
600
- maximum_attempts=2
601
- ),
602
- ),
603
- )
604
- ```
605
-
606
- Just set a flag. Add your constraints. Now you've got retry policies, timeout control, and error handling baked in.
607
-
608
- ---
609
-
610
- ### ✨ Utility – @flockclass Hydrator
611
-
612
- Flock also adds conveniences. With `@flockclass`, you can turn any Pydantic model into a self-hydrating agent.
613
-
614
- ```python
615
- from pydantic import BaseModel
616
- from flock.util.hydrator import flockclass
617
-
618
- @flockclass(model="openai/gpt-4o")
619
- class CharacterIdea(BaseModel):
620
- name: str
621
- char_class: str
622
- race: str
623
- backstory_hook: str | None = None
624
- personality_trait: str | None = None
625
-
626
- async def create_character():
627
- char = CharacterIdea(name="Gorok", char_class="Barbarian", race="Orc")
628
- print(f"Before Hydration: {char}")
629
-
630
- hydrated_char = await char.hydrate()
631
-
632
- print(f"\nAfter Hydration: {hydrated_char}")
633
- print(f"Backstory Hook: {hydrated_char.backstory_hook}")
634
- ```
635
-
636
-
637
-
638
- --------------------------------
639
-
640
- ## 📚 Examples & Tutorials
641
-
642
- For a comprehensive set of examples, ranging from basic usage to complex projects and advanced features, please visit our dedicated showcase repository:
643
-
644
- ➡️ [github.com/whiteducksoftware/flock-showcase](https://github.com/whiteducksoftware/flock-showcase) ⬅️
645
-
646
- The showcase includes:
647
-
648
- - Step-by-step guides for core concepts.
649
- - Examples of tool usage, routing, memory, and more.
650
- - Complete mini-projects demonstrating practical applications.
651
-
652
- ## 📖 Documentation
653
-
654
- Full documentation, including API references and conceptual explanations, can be found at:
655
-
656
- ➡️ [whiteducksoftware.github.io/flock/](https://whiteducksoftware.github.io/flock/) ⬅️
657
-
658
- ## 🤝 Contributing
659
-
660
- We welcome contributions! Please see the CONTRIBUTING.md file (if available) or open an issue/pull request on GitHub.
661
-
662
- Ways to contribute:
663
-
664
- - Report bugs or suggest features.
665
- - Improve documentation.
666
- - Contribute new Modules, Evaluators, or Routers.
667
- - Add examples to the flock-showcase repository.
668
-
669
- ## 📜 License
670
-
671
- Flock is licensed under the MIT License. See the LICENSE file for details.
672
-
673
- ## 🏢 About
674
-
675
- Flock is developed and maintained by white duck GmbH, your partner for cloud-native solutions and AI integration.