flock-core 0.5.311__tar.gz

flock_core-0.5.311/.devcontainer/devcontainer.json

@@ -0,0 +1,31 @@
+{
+  "name": "flock dev",
+  "image": "ghcr.io/astral-sh/uv:python3.12-bookworm",
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "22",
+      "nodeGypDependencies": true
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "charliermarsh.ruff"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": "/usr/local/bin/python",
+        "[python]": {
+          "editor.defaultFormatter": "charliermarsh.ruff",
+          "editor.formatOnSave": true,
+          "editor.codeActionsOnSave": {
+            "source.fixAll": "explicit",
+            "source.organizeImports": "explicit"
+          }
+        }
+      }
+    }
+  },
+  "forwardPorts": [8888],
+  "postCreateCommand": "uv sync --all-groups --all-extras --frozen"
+}

flock_core-0.5.311/.envtemplate

@@ -0,0 +1,90 @@
+# ============================================================================
+# Model Configuration
+# ============================================================================
+# Flock supports all litellm-compatible models, including OpenAI and Azure OpenAI.
+# Documentation: https://docs.litellm.ai/docs/providers
+# Common models:
+
+# AZURE - "azure/{model_name}"
+
+; AZURE_API_KEY=xxx
+; AZURE_API_BASE=https://xxx-foundry.cognitiveservices.azure.com/
+; AZURE_API_VERSION="2024-12-01-preview"
+; DEFAULT_MODEL="azure/gtp-4.1"
+
+# OPENAI - "openai/{model_name}"
+
+; OPENAI_API_KEY=xxx
+; OPENAI_API_BASE=https://api.openai.com/v1/
+; DEFAULT_MODEL="openai/gpt-5"
+
+# OPENROUTER - "openrouter/{model_name}"
+
+; OPENROUTER_API_KEY=
+; OPENROUTER_API_BASE=
+; DEFAULT_MODEL="openrouter/polaris-alpha"
+
+# ============================================================================
+# OpenTelemetry Tracing Configuration
+# ============================================================================
+
+# Enable auto-tracing for all agents and operations
+# Set to "true" to enable OpenTelemetry distributed tracing
+# Traces are stored in DuckDB for fast analytical queries
+FLOCK_AUTO_TRACE=true
+
+# Store traces in DuckDB database (recommended for production)
+# Creates .flock/traces.duckdb with full input/output capture
+# Set to "true" to enable DuckDB storage
+FLOCK_TRACE_FILE=true
+
+# 🆕 Unified Workflow Tracing (v0.5.0+)
+# Automatically wrap operations in workflow traces for better observability
+# When disabled (default), use explicit `async with flock.traced_run("name")`
+# Set to "true" to enable automatic workflow trace detection
+# FLOCK_AUTO_WORKFLOW_TRACE=true
+
+# Filter: Trace only specific services (whitelist)
+# Format: JSON array of service names (case-insensitive)
+# If not set or empty, all services are traced
+# Recommended: Trace core services, avoid streaming token overhead
+# Example: FLOCK_TRACE_SERVICES=["flock", "agent", "dspyengine", "outpututilitycomponent"]
+FLOCK_TRACE_SERVICES=["flock", "agent", "dspyengine", "outpututilitycomponent"]
+
+# Filter: Ignore specific operations (blacklist)
+# Format: JSON array of operation names in "Service.method" format
+# Use this to exclude noisy or low-value operations from traces
+# Example: FLOCK_TRACE_IGNORE=["DashboardEventCollector.set_websocket_manager"]
+FLOCK_TRACE_IGNORE=["DashboardEventCollector.set_websocket_manager"]
+
+# Trace Time-To-Live (TTL): Auto-delete old traces
+# Deletes traces older than specified days on application startup
+# Keeps database size manageable and removes stale debugging data
+# Set to empty or comment out to keep traces forever
+# Example: FLOCK_TRACE_TTL_DAYS=30
+FLOCK_TRACE_TTL_DAYS=30
+
+# ============================================================================
+# Unified Tracing Usage (Code-based approach - RECOMMENDED)
+# ============================================================================
+#
+# Instead of using FLOCK_AUTO_WORKFLOW_TRACE, use explicit traced_run():
+#
+#   async with flock.traced_run("workflow_name"):
+#       await flock.publish(data)
+#       await flock.run_until_idle()
+#
+# Benefits:
+#   ✅ Single trace for entire workflow (all operations share trace_id)
+#   ✅ Proper parent-child span hierarchy
+#   ✅ Custom workflow names for better organization
+#   ✅ Add custom attributes: span.set_attribute("key", "value")
+#   ✅ Nested workflow support
+#
+# Clearing traces for fresh debug sessions:
+#   result = Flock.clear_traces()  # Deletes all spans, runs VACUUM
+#
+# See docs/UNIFIED_TRACING.md for complete guide
+# ============================================================================
+
+OPENAI_API_KEY=xxx

flock_core-0.5.311/.github/issue_draft_non_blocking_serve.md

@@ -0,0 +1,205 @@
+# 🚀 [FEATURE] Non-Blocking `serve()` for Dashboard Examples
+
+### Is your feature request related to a problem?
+
+Dashboard examples currently face a limitation: once `flock.serve(dashboard=True)` is called, execution blocks indefinitely. This makes it impossible to publish messages or perform any setup logic after starting the dashboard server, unlike CLI examples which use `run_until_idle()` for controlled execution.
+
+**Current workaround:**
+Users must publish all messages *before* calling `serve()`, which is awkward for demos and prevents realistic workflows where the server runs continuously while processing incoming messages.
+
+**Example of the problem:**
+```python
+# This doesn't work - can't execute after serve()
+async def main():
+    await flock.serve(dashboard=True)  # blocks forever
+
+    # This code never runs! ❌
+    pizza = MyDreamPizza(pizza_idea="pizza with pineapple")
+    await flock.publish(pizza)
+    await flock.run_until_idle()
+```
+
+### Describe the solution you want to see
+
+Add a `blocking` parameter to `serve()` that allows starting the dashboard server as a background task:
+
+```python
+async def serve(
+    self,
+    *,
+    dashboard: bool = False,
+    dashboard_v2: bool = False,
+    host: str = "127.0.0.1",
+    port: int = 8344,
+    blocking: bool = True,  # NEW: default True for backwards compatibility
+) -> Task[None] | None:
+```
+
+**Usage example:**
+```python
+async def main():
+    # Start dashboard in background
+    await flock.serve(dashboard=True, blocking=False)
+
+    # Now we can publish messages!
+    pizza = MyDreamPizza(pizza_idea="pizza with pineapple")
+    await flock.publish(pizza)
+    await flock.run_until_idle()
+
+    # Dashboard stays alive for inspection
+    print("Check dashboard at http://localhost:8344")
+    await asyncio.Event().wait()  # Keep running
+```
+
+**Key requirements:**
+- Backwards compatible (`blocking=True` by default)
+- Return `Task[None]` handle when `blocking=False`
+- Proper cleanup of dashboard launcher and server on shutdown or task cancellation
+- Works seamlessly with `run_until_idle()`
+
+### Describe alternatives you have considered
+
+**Option 1: Startup hook pattern**
+```python
+async def setup():
+    await flock.publish(...)
+
+await flock.serve(dashboard=True, on_startup=setup)
+```
+❌ Less flexible, doesn't allow continuous message publishing
+
+**Option 2: Separate `serve_background()` method**
+```python
+await flock.serve_background(dashboard=True)
+```
+❌ API duplication, less discoverable
+
+**Option 3: Always non-blocking**
+```python
+await flock.serve(dashboard=True)  # always returns immediately
+```
+❌ Breaking change for existing users
+
+### Additional context
+
+**Complexity: Medium** (6-9 hours estimated)
+- Core async pattern is straightforward (codebase already uses `asyncio.create_task` extensively)
+- Cleanup coordination requires careful handling (dashboard launcher + server task lifecycle)
+- Backwards compatibility is preserved with default parameter
+
+---
+
+## 🛠️ Implementation Plan
+
+### 1. Core Changes
+
+**File: `src/flock/orchestrator.py`**
+
+- Add `blocking: bool = True` parameter to `serve()` method (line 753)
+- Add `_server_task: Task[None] | None = None` field to `__init__` (around line 165)
+- Update return type: `-> Task[None] | None`
+- When `blocking=False`:
+  - Wrap server execution in `asyncio.create_task()`
+  - Add cleanup callback for dashboard launcher on task completion
+  - Track task in `_server_task` field
+  - Return task handle
+
+**Estimated effort:** 2-3 hours
+
+### 2. Cleanup Logic
+
+**File: `src/flock/orchestrator.py`**
+
+- Add server cleanup to `shutdown()` method (line 718)
+  - Cancel `_server_task` if running
+  - Stop `_dashboard_launcher` if present
+  - Handle `asyncio.CancelledError` gracefully
+- Ensure proper resource cleanup on both normal completion and cancellation
+
+**Estimated effort:** 1-2 hours
+
+### 3. Testing
+
+**File: `tests/integration/test_orchestrator_dashboard.py` (or new test file)**
+
+Test scenarios:
+- ✅ Non-blocking serve starts successfully and returns task
+- ✅ Can publish messages after non-blocking serve
+- ✅ Server processes messages during `run_until_idle()`
+- ✅ Dashboard launcher cleanup on task completion
+- ✅ Cleanup on explicit `shutdown()` call
+- ✅ Backwards compatibility: `blocking=True` works as before
+- ✅ Task cancellation cleans up resources properly
+
+**Estimated effort:** 2-3 hours
+
+### 4. Documentation
+
+**Files to update:**
+- `src/flock/orchestrator.py` - Update `serve()` docstring with:
+  - New `blocking` parameter description
+  - Example showing non-blocking usage
+  - Return type documentation
+
+**Estimated effort:** 30 minutes
+
+### 5. Example
+
+**File: `examples/02-dashboard/02_non_blocking_serve.py` (new)**
+
+Create example demonstrating:
+- Starting dashboard in non-blocking mode
+- Publishing messages after server starts
+- Using `run_until_idle()` to process messages
+- Keeping server alive for inspection
+
+**Estimated effort:** 1 hour
+
+---
+
+## ✅ Definition of Done
+
+- [ ] `blocking` parameter implemented with default `True`
+- [ ] Non-blocking mode returns `Task[None]` handle
+- [ ] Server cleanup logic handles both normal and cancelled completion
+- [ ] All tests passing (new + existing)
+- [ ] Docstring updated with parameter and examples
+- [ ] New example created: `examples/02-dashboard/02_non_blocking_serve.py`
+- [ ] Backwards compatibility verified (existing examples still work)
+- [ ] Manual validation: example runs and dashboard stays accessible
+
+---
+
+## 🧪 Validation Strategy
+
+**Automated:**
+- Unit/integration tests for non-blocking behavior
+- Cleanup verification tests
+- Backwards compatibility regression tests
+
+**Manual:**
+1. Run new example: `python examples/02-dashboard/02_non_blocking_serve.py`
+2. Verify dashboard accessible at http://localhost:8344
+3. Verify messages appear in dashboard
+4. Verify server stays alive after `run_until_idle()`
+5. Test graceful shutdown (Ctrl+C)
+
+---
+
+## 📅 Timeline Estimate
+
+**Total effort:** 6-9 hours
+
+Breakdown:
+- Implementation: 3-5 hours
+- Testing: 2-3 hours
+- Documentation + Example: 1.5 hours
+
+---
+
+## 🔗 Technical References
+
+- `orchestrator.py:753` - Current `serve()` implementation
+- `orchestrator.py:580, 588, 1417` - Existing `asyncio.create_task` usage patterns
+- `orchestrator.py:718` - Existing `shutdown()` method
+- `service.py:279` - `BlackboardHTTPService.run_async()` (blocks on `uvicorn.Server.serve()`)

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

@@ -0,0 +1,23 @@
+name: Deploy MkDocs
+on:
+  push:
+    branches:
+      - main  # or master
+      - docs/*  # or docs/*
+
+# Explicit permissions for security best practices
+permissions:
+  contents: write
+  pages: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - 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.311/.github/workflows/deploy-whiteduck-pypi.yml

@@ -0,0 +1,50 @@
+# .github/workflows/publish.yml
+
+name: Publish Python Package
+
+on:
+  push:
+    branches:
+      - main # Replace with your default branch
+    paths:
+      - 'pyproject.toml'  # Only trigger on changes to pyproject.toml (version number)
+
+jobs:
+  build-and-publish:
+    strategy:
+      matrix:
+        python-version:
+          - "3.12"
+          - "3.13"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install the project
+        run: uv sync
+
+      - name: Build the project
+        run: uv build
+
+      - name: Check if should skip
+        id: skip-check
+        run: |
+          if echo "${{ github.event.head_commit.message }}" | grep -iq "\[skip publish\]"; then
+            echo "skip=true" >> $GITHUB_OUTPUT
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Publish to pypi
+        if: steps.skip-check.outputs.skip != 'true'
+        run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}

flock_core-0.5.311/.github/workflows/quality.yml

@@ -0,0 +1,146 @@
+# Flock Quality Gates CI/CD
+# Runs comprehensive quality checks on all pull requests and pushes
+# Matches pre-commit hooks with additional test coverage requirements
+
+name: Quality Gates
+
+on:
+  push:
+    branches:
+      - main # Replace with your default branch
+      - 0.5.0b
+  pull_request:
+    branches:
+      - main # Replace with your default branch
+      - 0.5.0b
+
+jobs:
+  # Backend quality checks
+  backend-quality:
+    name: Backend Quality
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install UV
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Install dependencies
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          uv sync --dev --all-groups --all-extras
+
+      - name: Lint with Ruff
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          uv run ruff check src/flock/ --fix --exit-zero
+
+      - name: Format check with Ruff
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          uv run ruff format --check src/flock/
+
+      - name: Run tests with coverage
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          uv run pytest --cov=src/flock --cov-branch --cov-report=xml --cov-report=term --cov-fail-under=75
+
+      - name: Extract test metrics
+        id: test-metrics
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+
+          # Count total tests
+          TEST_COUNT=$(uv run pytest --collect-only -q | tail -n 1 | awk '{print $1}')
+          echo "test_count=$TEST_COUNT" >> $GITHUB_OUTPUT
+          echo "📊 Total tests: $TEST_COUNT"
+
+          # Extract coverage percentage from XML
+          COVERAGE=$(python -c "import xml.etree.ElementTree as ET; tree = ET.parse('coverage.xml'); root = tree.getroot(); print(f\"{float(root.attrib['line-rate']) * 100:.0f}\")")
+          echo "coverage=$COVERAGE" >> $GITHUB_OUTPUT
+          echo "📈 Coverage: $COVERAGE%"
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: ./coverage.xml
+          flags: backend
+          name: backend-coverage
+          fail_ci_if_error: false
+
+      - name: Backend build check
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          uv build
+
+  # Frontend quality checks
+  frontend-quality:
+    name: Frontend Quality
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: src/flock/frontend/package-lock.json
+
+      - name: Install dependencies
+        working-directory: src/flock/frontend
+        run: npm ci
+
+      - name: Type check
+        working-directory: src/flock/frontend
+        run: npm run type-check
+
+      - name: Run tests
+        working-directory: src/flock/frontend
+        run: npm test
+
+      # Coverage disabled until vitest.config.ts is properly configured
+      # - name: Upload coverage to Codecov
+      #   uses: codecov/codecov-action@v4
+      #   with:
+      #     file: ./frontend/coverage/coverage-final.json
+      #     flags: frontend
+      #     name: frontend-coverage
+
+      - name: Frontend build check
+        working-directory: src/flock/frontend
+        run: npm run build
+
+  # Security scanning
+  security-scan:
+    name: Security Scan
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install UV
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Install dependencies
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          uv sync --dev --all-groups --all-extras
+
+      - name: Run Bandit security scan
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          uv run bandit -c pyproject.toml -r src/flock/ -ll