flock-core 0.5.0b71__tar.gz → 0.5.1__tar.gz

flock_core-0.5.1/.github/workflows/deploy-documentation.yml

@@ -0,0 +1,18 @@
+name: Deploy MkDocs
+on:
+  push:
+    branches:
+      - main  # or master
+      - docs/*  # or docs/*
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - run: pip install mkdocs-material mkdocs mkdocstrings[python] mkdocs-gen-files mkdocs-literate-nav mkdocs-section-index mkdocs-minify-plugin mkdocs-git-revision-date-localized-plugin mkdocs-glightbox
+      - run: pip install -e .
+      - run: mkdocs gh-deploy --force

{flock_core-0.5.0b71 → flock_core-0.5.1}/AGENTS.md

@@ -75,14 +75,15 @@ uv run python -c "from flock import Flock; print('✅ Ready!')"
 ### Run Examples
 
 ```bash
-# Core examples
-uv run python examples/01-the-declarative-way/01_declarative_pizza.py
-uv run python examples/01-the-declarative-way/02_input_and_output.py
+# CLI examples (with detailed output)
+uv run python examples/01-cli/01_declarative_pizza.py
+uv run python examples/01-cli/02_input_and_output.py
+uv run python examples/01-cli/03_code_detective.py
 
-# Dashboard examples
-uv run python examples/03-the-dashboard/01_declarative_pizza.py
-uv run python examples/03-the-dashboard/02-dashboard-edge-cases.py
-uv run python examples/03-the-dashboard/03-scale-test-100-agents.py
+# Dashboard examples (with visualization)
+uv run python examples/02-dashboard/01_declarative_pizza.py
+uv run python examples/02-dashboard/02_input_and_output.py
+uv run python examples/02-dashboard/03_code_detective.py
 ```
 
 ---
@@ -1010,13 +1011,13 @@ uv run python examples/03-the-dashboard/01_declarative_pizza.py
 
 Wait for these success indicators in the output:
 - `[Dashboard] Production build completed`
-- `INFO: Uvicorn running on http://127.0.0.1:8000`
+- `INFO: Uvicorn running on http://127.0.0.1:8344`
 - `[Dashboard] Browser launched successfully`
 
 **2. Navigate and Verify Initial Load**
 ```python
 # Use playwright-mcp tools
-mcp__playwright__browser_navigate(url="http://localhost:8000")
+mcp__playwright__browser_navigate(url="http://localhost:8344")
 ```
 
 **✅ What to verify:**
@@ -1158,7 +1159,7 @@ mcp__playwright__browser_take_screenshot(filename="dashboard-test.png")
 - ✅ **Screenshot capture** - Document UI state for debugging/documentation
 - ✅ **Interactive debugging** - Click, type, inspect like a real user
 
-📖 **Dashboard examples:** [`examples/03-the-dashboard/`](examples/03-the-dashboard/)
+📖 **Dashboard examples:** [`examples/02-dashboard/`](examples/02-dashboard/)
 
 ---
 
@@ -1278,7 +1279,7 @@ Plan your testing time accordingly!
 - Counters increment as artifacts produced/consumed
 - WebSocket delivers updates without page refresh
 
-📖 **Dashboard examples:** [`examples/03-the-dashboard/`](examples/03-the-dashboard/)
+📖 **Dashboard examples:** [`examples/02-dashboard/`](examples/02-dashboard/)
 
 ---
 
@@ -1408,5 +1409,5 @@ await orchestrator.serve(dashboard=True)
 
 ---
 
-*Last updated: October 8, 2025*
+*Last updated: October 13, 2025*
 *This file follows the modern AGENTS.md format for AI coding agents.*

flock_core-0.5.1/AUTO_TRACING.md

@@ -0,0 +1,96 @@
+# AUTO_TRACING.md
+
+Windows-friendly cheatsheet for enabling auto tracing and mining `.flock/traces.duckdb` without fighting PowerShell quoting. Use it when you only need the commands; the long-form philosophy still lives in `docs/UNIFIED_TRACING.md`.
+
+---
+
+## 1. Enable tracing for the current PowerShell session
+
+```powershell
+$env:FLOCK_AUTO_TRACE = 'true'
+$env:FLOCK_TRACE_FILE = 'true'
+```
+
+These flags ensure every run writes spans into `.flock/traces.duckdb`. Repeat them inside new terminals (or add them to `.env`).
+
+---
+
+## 2. Verify traces exist
+
+```powershell
+Get-ChildItem .flock\traces.duckdb
+```
+
+If the file is missing, tracing was off—re-run the script you care about after setting the env vars.
+
+---
+
+## 3. List the most recent traces (PowerShell-safe `uv run`)
+
+```powershell
+uv run python -c "import duckdb`nconn=duckdb.connect('.flock/traces.duckdb', read_only=True)`nrows=conn.execute('SELECT trace_id, MIN(start_time) AS started_at_ns, COUNT(*) AS spans FROM spans GROUP BY trace_id ORDER BY started_at_ns DESC LIMIT 5').fetchall()`nfor trace_id, started_ns, span_count in rows:`n    print(trace_id, started_ns, span_count)`nconn.close()"
+```
+
+Why the backticks? PowerShell treats `` `n`` as a newline, giving you readable Python inside the string. Avoid single quotes around the command—PowerShell would disable the `` `n`` substitution.
+
+---
+
+## 4. Inspect the latest `Agent.execute` output (e.g., pizza ingredients)
+
+```powershell
+uv run python -c "import duckdb, json`nconn=duckdb.connect('.flock/traces.duckdb', read_only=True)`ntrace_id, = conn.execute(\"SELECT trace_id FROM spans WHERE name = 'Agent.execute' ORDER BY start_time DESC LIMIT 1\").fetchone()`nrow = conn.execute(\"SELECT attributes FROM spans WHERE trace_id = ? AND name = 'Agent.execute' ORDER BY start_time DESC LIMIT 1\", [trace_id]).fetchone()`ndata = json.loads(row[0])`nartifacts = json.loads(data['output.value'])`npayload = artifacts[0]['payload']`nprint('Trace:', trace_id)`nprint('Ingredients:')`nfor item in payload.get('ingredients', []):`n    print(' -', item)`nconn.close()"
+```
+
+This mirrors the manual inspection from the last debugging session and works out of the box on Windows terminals.
+
+---
+
+## 5. Keep helper scripts handy (optional)
+
+For longer queries, drop a temporary script into `.tmp`:
+
+```powershell
+New-Item -ItemType Directory -Force -Path .tmp | Out-Null
+$code = @'
+import duckdb
+import json
+
+conn = duckdb.connect(".flock/traces.duckdb", read_only=True)
+query = """
+    SELECT trace_id, name, attributes
+    FROM spans
+    WHERE name IN ('Agent.execute', 'Flock.publish')
+    ORDER BY start_time DESC
+    LIMIT 10
+"""
+for trace_id, name, attrs_json in conn.execute(query).fetchall():
+    attrs = json.loads(attrs_json)
+    print(trace_id, name, attrs.get("output.type"))
+conn.close()
+'@
+Set-Content .tmp\trace_query.py $code
+uv run python .tmp\trace_query.py
+Remove-Item .tmp\trace_query.py
+```
+
+This approach avoids quoting entirely and keeps the workspace clean.
+
+---
+
+## 6. Clean up stale traces
+
+```powershell
+uv run python -c "from flock import Flock`nprint(Flock.clear_traces())"
+```
+
+The output shows how many spans were deleted. Run this before collecting a fresh trace set so queries stay fast.
+
+---
+
+## 7. Cross-reference
+
+- Full tracing deep dive: `docs/UNIFIED_TRACING.md`
+- Observability dashboard tips: `docs/guides/dashboard.md`
+- Need to debug without touching PowerShell? Launch the same scripts in Git Bash or WSL—the SQL snippets above translate directly.
+
+Happy tracing!

{flock_core-0.5.0b71 → flock_core-0.5.1}/CONTRIBUTING.md

@@ -451,7 +451,7 @@ uv run python examples/showcase/04_dashboard.py
 cd frontend
 npm run dev
 
-# Dashboard opens at http://localhost:8000
+# Dashboard opens at http://localhost:8344
 ```
 
 ### Debug Tests
@@ -476,7 +476,7 @@ uv run pytest tests/test_orchestrator.py --cov=src/flock/orchestrator.py
 # Build docs locally
 poe docs
 
-# Docs served at http://127.0.0.1:8000
+# Docs served at http://127.0.0.1:8344
 ```
 
 ## 🚨 Troubleshooting

{flock_core-0.5.0b71 → flock_core-0.5.1}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.0b71
-Summary: Add your description here
+Version: 0.5.1
+Summary: Flock: A declrative framework for building and orchestrating AI agents.
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: devtools>=0.12.2
-Requires-Dist: dspy==3.0.0
+Requires-Dist: dspy==3.0.4b1
 Requires-Dist: duckdb>=1.1.0
 Requires-Dist: fastapi>=0.117.1
 Requires-Dist: hanging-threads>=2.0.7
@@ -31,7 +31,7 @@ Requires-Dist: websockets>=15.0.1
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img alt="Flock Banner" src="https://raw.githubusercontent.com/whiteducksoftware/flock/master/docs/assets/images/flock.png" width="800">
+  <img alt="Flock Banner" src="docs/assets/images/flock.png" width="800">
 </p>
 <p align="center">
   <a href="https://docs.flock.whiteduck.de" target="_blank"><img alt="Documentation" src="https://img.shields.io/badge/docs-online-blue?style=for-the-badge&logo=readthedocs"></a>
@@ -675,13 +675,15 @@ Flock uses a fundamentally different coordination pattern than most multi-agent
 - Type-safe retrieval API (`get_by_type()`)
 
 **⚠️ What's missing for large-scale production:**
-- **Persistent blackboard** - Currently in-memory only
-- **Advanced retry logic** - Basic only
+- **Advanced retry logic** - Basic only (exponential backoff planned)
 - **Event replay** - No Kafka integration yet
 - **Kubernetes-native deployment** - No Helm chart yet
 - **OAuth/RBAC** - Dashboard has no auth
 
-All planned for v1.0
+**✅ Available today:**
+- **Persistent blackboard** - SQLiteBlackboardStore (see above)
+
+All missing features planned for v1.0
 
 ### Recommended Use Cases Today
 
@@ -873,16 +875,21 @@ pip install flock-core
 # Set API key
 export OPENAI_API_KEY="sk-..."
 
-# Try the workshop
+# Try the examples
 git clone https://github.com/whiteducksoftware/flock-flow.git
 cd flock-flow
-uv run python examples/05-claudes-workshop/lesson_01_code_detective.py
+
+# CLI examples with detailed output
+uv run python examples/01-cli/01_declarative_pizza.py
+
+# Dashboard examples with visualization
+uv run python examples/02-dashboard/01_declarative_pizza.py
 ```
 
 **Learn by doing:**
-- 📚 [7-Lesson Workshop](examples/05-claudes-workshop/) - Progressive lessons from basics to advanced
-- 🆚 [The Blackboard](examples/02-the-blackboard/) - See data-driven orchestration without graphs
-- 🎯 [Declarative Basics](examples/01-the-declarative-way/) - Understanding declarative programming
+- 📚 [Examples README](examples/README.md) - 12-step learning path from basics to advanced
+- 🖥️ [CLI Examples](examples/01-cli/) - Detailed console output examples (01-12)
+- 📊 [Dashboard Examples](examples/02-dashboard/) - Interactive visualization examples (01-12)
 - 📖 [Documentation](https://docs.flock.whiteduck.de) - Complete online documentation
 - 📘 [AGENTS.md](AGENTS.md) - Development guide
 
@@ -959,6 +966,6 @@ We're calling this 0.5 to signal:
 
 ---
 
-**Last Updated:** October 8, 2025
+**Last Updated:** October 13, 2025
 **Version:** Flock 0.5.0 (Blackboard Edition)
 **Status:** Production-Ready Core, Enterprise Features Roadmapped

{flock_core-0.5.0b71 → flock_core-0.5.1}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img alt="Flock Banner" src="https://raw.githubusercontent.com/whiteducksoftware/flock/master/docs/assets/images/flock.png" width="800">
+  <img alt="Flock Banner" src="docs/assets/images/flock.png" width="800">
 </p>
 <p align="center">
   <a href="https://docs.flock.whiteduck.de" target="_blank"><img alt="Documentation" src="https://img.shields.io/badge/docs-online-blue?style=for-the-badge&logo=readthedocs"></a>
@@ -643,13 +643,15 @@ Flock uses a fundamentally different coordination pattern than most multi-agent
 - Type-safe retrieval API (`get_by_type()`)
 
 **⚠️ What's missing for large-scale production:**
-- **Persistent blackboard** - Currently in-memory only
-- **Advanced retry logic** - Basic only
+- **Advanced retry logic** - Basic only (exponential backoff planned)
 - **Event replay** - No Kafka integration yet
 - **Kubernetes-native deployment** - No Helm chart yet
 - **OAuth/RBAC** - Dashboard has no auth
 
-All planned for v1.0
+**✅ Available today:**
+- **Persistent blackboard** - SQLiteBlackboardStore (see above)
+
+All missing features planned for v1.0
 
 ### Recommended Use Cases Today
 
@@ -841,16 +843,21 @@ pip install flock-core
 # Set API key
 export OPENAI_API_KEY="sk-..."
 
-# Try the workshop
+# Try the examples
 git clone https://github.com/whiteducksoftware/flock-flow.git
 cd flock-flow
-uv run python examples/05-claudes-workshop/lesson_01_code_detective.py
+
+# CLI examples with detailed output
+uv run python examples/01-cli/01_declarative_pizza.py
+
+# Dashboard examples with visualization
+uv run python examples/02-dashboard/01_declarative_pizza.py
 ```
 
 **Learn by doing:**
-- 📚 [7-Lesson Workshop](examples/05-claudes-workshop/) - Progressive lessons from basics to advanced
-- 🆚 [The Blackboard](examples/02-the-blackboard/) - See data-driven orchestration without graphs
-- 🎯 [Declarative Basics](examples/01-the-declarative-way/) - Understanding declarative programming
+- 📚 [Examples README](examples/README.md) - 12-step learning path from basics to advanced
+- 🖥️ [CLI Examples](examples/01-cli/) - Detailed console output examples (01-12)
+- 📊 [Dashboard Examples](examples/02-dashboard/) - Interactive visualization examples (01-12)
 - 📖 [Documentation](https://docs.flock.whiteduck.de) - Complete online documentation
 - 📘 [AGENTS.md](AGENTS.md) - Development guide
 
@@ -927,6 +934,6 @@ We're calling this 0.5 to signal:
 
 ---
 
-**Last Updated:** October 8, 2025
+**Last Updated:** October 13, 2025
 **Version:** Flock 0.5.0 (Blackboard Edition)
 **Status:** Production-Ready Core, Enterprise Features Roadmapped