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