flock-core 0.5.8__tar.gz → 0.5.10__tar.gz

{flock_core-0.5.8 → flock_core-0.5.10}/.github/workflows/quality.yml

@@ -51,12 +51,29 @@ jobs:
           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: true
 
       - name: Backend build check
         run: |

{flock_core-0.5.8 → flock_core-0.5.10}/AGENTS.md

@@ -53,7 +53,7 @@ A blackboard architecture framework where specialized AI agents collaborate thro
 
 ### Prerequisites
 
-- **Python 3.10+** (we use modern async features)
+- **Python 3.12+** (we use modern async features)
 - **UV package manager** (faster than pip, handles virtual envs)
 - **Node.js 18+** (22+ recommended) for dashboard frontend
 - **OpenAI API key** (for running examples)
@@ -107,6 +107,7 @@ For deep dives into specific topics, see:
 **Core Architecture:**
 - **[Architecture & Blackboard](docs/guides/blackboard.md)** - Core pattern, structure, and behavior
 - **[Agent Guide](docs/guides/agents.md)** - Complete agent development reference
+- **[Context Providers](docs/guides/context-providers.md)** - Smart filtering & security boundaries for agent context ⭐ **NEW in 0.5**
 
 **Components & Extensibility:**
 - **[Agent Components](docs/guides/components.md)** - Extend agent behavior with lifecycle hooks
@@ -296,6 +297,288 @@ Kick the tyres with `examples/02-the-blackboard/01_persistent_pizza.py`, then la
 
 ---
 
+### 🔐 Context Providers - Smart Filtering & Security Boundaries
+
+**Context Providers are the intelligent filter layer between agents and the blackboard—controlling what each agent sees, reducing token costs by 90%+, and automatically redacting sensitive data.**
+
+#### Why Context Providers Matter
+
+**The Problem:**
+- Agents seeing ALL artifacts wastes tokens (costs)
+- No way to filter sensitive data before agents see it
+- Performance degrades as blackboard grows
+- Security vulnerabilities if agents bypass visibility
+
+**The Solution:**
+Context Providers enforce a security boundary that:
+- ✅ **Reduces token costs** - Agents see only relevant artifacts (90%+ savings)
+- ✅ **Protects sensitive data** - Auto-redact passwords, API keys, credit cards
+- ✅ **Improves performance** - Less context = faster agent execution
+- ✅ **Enforces security** - Agents cannot bypass provider filtering
+
+**Understanding the Three-Layer Model:**
+
+Flock uses three complementary filtering layers:
+
+1. **Visibility** (security boundary) - Controls BOTH which agents trigger AND which artifacts they see in context
+2. **Subscription Filters** (routing logic) - Controls WHEN agents trigger (e.g., `.consumes(Task, tags={"urgent"})`)
+3. **Context Providers** (context shaping) - Controls WHAT agents see in their historical context
+
+These layers work together to provide fine-grained control over agent execution and data access. Context Providers are the third layer—they filter what agents see in context but do NOT control triggering.
+
+#### Quick Start: Global Filtering
+
+**Filter all agents to see only urgent items:**
+
+```python
+from flock import Flock
+from flock.context_provider import FilteredContextProvider
+from flock.store import FilterConfig
+
+# Create provider that filters by tags
+urgent_only = FilteredContextProvider(
+    FilterConfig(tags={"urgent", "high"}),
+    limit=50  # Max 50 artifacts
+)
+
+# Apply to ALL agents
+flock = Flock("openai/gpt-4.1", context_provider=urgent_only)
+
+# Publish with tags
+await flock.publish(Task(...), tags={"urgent"})  # ✅ Agents see this
+await flock.publish(Task(...), tags={"low"})     # ❌ Agents don't see this
+```
+
+#### Per-Agent Filtering (Role-Based)
+
+**Different agents see different context:**
+
+```python
+# Global: Errors only
+error_provider = FilteredContextProvider(FilterConfig(tags={"ERROR"}))
+flock = Flock("openai/gpt-4.1", context_provider=error_provider)
+
+# Junior engineer: Errors only (uses global)
+junior = flock.agent("junior").consumes(LogEntry).publishes(Report).agent
+
+# Senior engineer: Errors + Warnings (override global)
+warn_provider = FilteredContextProvider(FilterConfig(tags={"ERROR", "WARN"}))
+senior = flock.agent("senior").consumes(LogEntry).publishes(Analysis).agent
+senior.context_provider = warn_provider  # 🎯 Per-agent override!
+
+# Platform team: Everything (override global)
+all_provider = FilteredContextProvider(FilterConfig(tags={"DEBUG", "INFO", "WARN", "ERROR"}))
+platform = flock.agent("platform").consumes(LogEntry).publishes(Report).agent
+platform.context_provider = all_provider
+```
+
+**Provider Priority:**
+```
+Per-Agent Provider  >  Global Provider  >  DefaultContextProvider
+     (highest)            (medium)              (fallback)
+```
+
+#### Production-Ready: Password Redaction
+
+**Automatically redact sensitive data from agent context:**
+
+```python
+from examples.context_provider import PasswordRedactorProvider
+
+# Create provider with built-in patterns
+provider = PasswordRedactorProvider(
+    redaction_text="[REDACTED]",
+    redact_emails=True,
+    log_redactions=True  # Audit trail
+)
+
+flock = Flock("openai/gpt-4.1", context_provider=provider)
+
+# Publish data with secrets
+await flock.publish(UserData(
+    password="MySecret123",           # → [REDACTED]
+    api_key="sk-1234567890abcdef",    # → [REDACTED]
+    email="user@example.com"          # → [REDACTED]
+))
+
+# Agents see redacted version automatically!
+```
+
+**What gets redacted:**
+- 🔒 Passwords and secrets
+- 🔑 API keys (OpenAI, AWS, GitHub, GitLab, Stripe, Google)
+- 🎫 Bearer tokens and JWT
+- 💳 Credit card numbers (Visa, MC, Amex, Discover)
+- 🆔 Social Security Numbers
+- 🔐 Private keys (RSA, EC, OpenSSH)
+- 📧 Email addresses (optional)
+
+#### FilterConfig API Reference
+
+**Declarative filtering with multiple criteria:**
+
+```python
+from flock.store import FilterConfig
+
+# Combine multiple filters (AND logic)
+config = FilterConfig(
+    tags={"ERROR", "CRITICAL"},           # OR logic: any of these tags
+    type_names={"SystemEvent", "Alert"},  # OR logic: any of these types
+    produced_by=["monitor", "watchdog"],  # OR logic: from any of these agents
+    correlation_id="incident-123"         # Exact match
+)
+
+provider = FilteredContextProvider(config, limit=100)
+```
+
+**Criteria are combined with AND logic:**
+- Must have (ERROR OR CRITICAL) tag
+- AND must be (SystemEvent OR Alert) type
+- AND must be from (monitor OR watchdog) agent
+- AND must have correlation_id "incident-123"
+
+#### Custom Context Providers
+
+**Build your own filtering logic:**
+
+```python
+from flock.context_provider import BaseContextProvider, ContextRequest
+from flock.artifacts import Artifact
+
+class TimeBoundProvider(BaseContextProvider):
+    """Only show artifacts from last 1 hour.
+
+    Security is enforced automatically by BaseContextProvider!
+    """
+
+    async def get_artifacts(self, request: ContextRequest) -> list[Artifact]:
+        cutoff = datetime.now() - timedelta(hours=1)
+
+        # Query all artifacts
+        artifacts, _ = await request.store.query_artifacts(limit=1000)
+
+        # Apply time-based filtering
+        recent = [a for a in artifacts if a.created_at >= cutoff]
+
+        return recent
+
+        # ✨ BaseContextProvider automatically:
+        # - Filters by visibility (MANDATORY, cannot bypass!)
+        # - Excludes requested IDs
+        # - Serializes to standard format
+
+# Usage
+provider = TimeBoundProvider()
+flock = Flock("openai/gpt-4.1", context_provider=provider)
+```
+
+**Why this is better:**
+- ✅ **75% less code** - 5 lines vs 20+ lines
+- ✅ **Impossible to bypass security** - visibility enforced by base class
+- ✅ **Consistent serialization** - automatic standard format
+- ✅ **Focus on business logic** - not infrastructure
+
+#### Real-World Use Cases
+
+**Healthcare (HIPAA Compliance):**
+```python
+# Redact PHI (Protected Health Information)
+from examples.context_provider import PasswordRedactorProvider
+
+phi_provider = PasswordRedactorProvider(
+    custom_patterns={
+        "ssn": r"\b\d{3}-\d{2}-\d{4}\b",
+        "mrn": r"MRN[:\s]*\d{6,10}",
+        "dob": r"\b\d{2}/\d{2}/\d{4}\b",
+    }
+)
+
+flock = Flock("openai/gpt-4.1", context_provider=phi_provider)
+```
+
+**DevOps (Log Filtering):**
+```python
+# Error engineers see only errors
+error_provider = FilteredContextProvider(FilterConfig(tags={"ERROR", "CRITICAL"}))
+error_agent.context_provider = error_provider
+
+# Platform team sees everything
+all_provider = FilteredContextProvider(FilterConfig(tags={"DEBUG", "INFO", "WARN", "ERROR"}))
+platform_agent.context_provider = all_provider
+```
+
+**Multi-Tenant SaaS (Customer Isolation):**
+```python
+# Each tenant gets isolated context
+tenant_a_provider = FilteredContextProvider(FilterConfig(correlation_id=f"tenant_{customer_a.id}"))
+tenant_a_agent.context_provider = tenant_a_provider
+
+tenant_b_provider = FilteredContextProvider(FilterConfig(correlation_id=f"tenant_{customer_b.id}"))
+tenant_b_agent.context_provider = tenant_b_provider
+```
+
+#### Performance Impact
+
+**Token Cost Reduction:**
+
+```python
+# ❌ Before (no filtering): Agent sees 1000 artifacts = 200,000 tokens
+# Cost: $0.006 per agent call
+
+# ✅ After (smart filtering): Agent sees 10 relevant artifacts = 2,000 tokens
+# Cost: $0.00006 per agent call
+
+# 💰 99% cost reduction!
+
+provider = FilteredContextProvider(FilterConfig(tags={"urgent"}), limit=10)
+```
+
+#### Security Best Practices
+
+**✅ DO:**
+- Always enforce visibility (NEVER skip)
+- Use `FilteredContextProvider` for common patterns
+- Test redaction patterns with real data
+- Log security events for audit trails
+- Limit by default (start restrictive)
+
+**❌ DON'T:**
+- Don't skip visibility filtering (security boundary!)
+- Don't leak sensitive data in nested objects
+- Don't cache redacted data without re-applying redaction
+- Don't trust agent input (agents are untrusted)
+- Don't expose infrastructure details
+
+#### Learn More
+
+**📚 Complete Guide:** [docs/guides/context-providers.md](docs/guides/context-providers.md) - Architecture, security model, advanced patterns
+
+**💡 Examples:** [examples/08-context-provider/](examples/08-context-provider/) - 5 progressive examples from beginner to expert
+
+**🎁 Production Code:** [examples/08-context-provider/05_password_redactor.py](examples/08-context-provider/05_password_redactor.py) - Copy-paste ready password filtering
+
+#### Quick Reference
+
+```python
+# Global filtering
+flock = Flock("openai/gpt-4.1", context_provider=FilteredContextProvider(FilterConfig(tags={"urgent"})))
+
+# Per-agent override
+agent.context_provider = FilteredContextProvider(FilterConfig(tags={"ERROR", "WARN"}))
+
+# Password redaction
+from examples.context_provider import PasswordRedactorProvider
+flock = Flock("openai/gpt-4.1", context_provider=PasswordRedactorProvider())
+
+# Custom provider
+class MyProvider(ContextProvider):
+    async def __call__(self, request: ContextRequest) -> list[dict[str, Any]]:
+        # Query + filter by visibility (MANDATORY) + your logic
+        pass
+```
+
+---
+
 ### 🔒 Test Isolation and Mock Cleanup - The Contamination Trap
 
 **We fixed 32 failing tests caused by test contamination - here's what we learned:**
@@ -1335,7 +1618,7 @@ Add to existing test file if relevant, or create new file following naming conve
 
 ### Q: What Python version features can I use?
 
-Python 3.10+, so you can use:
+Python 3.12+, so you can use:
 - `match`/`case` statements
 - `TaskGroup` for parallel execution
 - Improved type hints (`list[str]` not `List[str]`)

{flock_core-0.5.8 → flock_core-0.5.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.8
+Version: 0.5.10
 Summary: Flock: A declrative framework for building and orchestrating AI agents.
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License: MIT
@@ -37,11 +37,11 @@ Description-Content-Type: text/markdown
 <p align="center">
   <a href="https://whiteducksoftware.github.io/flock/" target="_blank"><img alt="Documentation" src="https://img.shields.io/badge/docs-online-blue?style=for-the-badge&logo=readthedocs"></a>
   <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>
-  <img alt="Python Version" src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python">
+  <img alt="Python Version" src="https://img.shields.io/badge/python-3.12%2B-blue?style=for-the-badge&logo=python">
   <a href="LICENSE" target="_blank"><img alt="License" src="https://img.shields.io/github/license/whiteducksoftware/flock?style=for-the-badge"></a>
   <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>
-  <img alt="Test Coverage" src="https://img.shields.io/badge/coverage-77%25-green?style=for-the-badge">
-  <img alt="Tests" src="https://img.shields.io/badge/tests-743%20passing-brightgreen?style=for-the-badge">
+  <a href="https://codecov.io/gh/whiteducksoftware/flock" target="_blank"><img alt="Test Coverage" src="https://codecov.io/gh/whiteducksoftware/flock/branch/main/graph/badge.svg?token=YOUR_TOKEN_HERE&style=for-the-badge"></a>
+  <img alt="Tests" src="https://img.shields.io/badge/tests-1300+-brightgreen?style=for-the-badge">
 </p>
 
 ---
@@ -287,6 +287,39 @@ asyncio.run(main())
 
 ---
 
+## Context Provider Primer (Security + Cost)
+
+Context Providers are the security and efficiency layer between agents and the blackboard. They decide what each agent sees in its historical context and always enforce visibility rules.
+
+Why use them
+- Enforce access control (visibility is applied before engines see data)
+- Cut context size (often 90%+) by filtering to what matters
+- Specialize per agent or set a global default
+
+Copy/paste examples
+```python
+from flock import Flock
+from flock.context_provider import FilteredContextProvider
+from flock.store import FilterConfig
+
+# Global: show only urgent items (limit context size)
+flock = Flock(
+    "openai/gpt-4.1",
+    context_provider=FilteredContextProvider(FilterConfig(tags={"urgent"}), limit=50)
+)
+
+# Per-agent: override global for a specific role
+senior = flock.agent("senior").consumes(LogEntry).publishes(Analysis)
+senior.context_provider = FilteredContextProvider(
+    FilterConfig(tags={"ERROR", "WARN"}),
+    limit=200
+)
+```
+
+Learn more: docs/guides/context-providers.md
+
+---
+
 ## Persistent Blackboard History
 
 The in-memory store is still great for local tinkering, but production teams now have a durable option. Plugging in `SQLiteBlackboardStore` turns the blackboard into a persistent event log with first-class ergonomics:
@@ -541,8 +574,105 @@ artifact.visibility = AfterVisibility(ttl=timedelta(hours=24), then=PublicVisibi
 agent.publishes(PublicReport, visibility=PublicVisibility())
 ```
 
+**Visibility has a dual purpose:** It controls both which agents can be **triggered** by an artifact AND which artifacts agents can **see** in their context. This ensures consistent security across agent execution and data access—agents cannot bypass visibility controls through subscription filters or context providers.
+
 **Why this matters:** Financial services, healthcare, defense, SaaS platforms all need this for compliance. Other frameworks make you build it yourself.
 
+---
+
+### 🔒 Architecturally Impossible to Bypass Security
+
+**Here's what makes Flock different:** In most frameworks, security is something you remember to add. In Flock, **it's architecturally impossible to forget.**
+
+Every context provider in Flock inherits from `BaseContextProvider`, which enforces visibility filtering **automatically**. You literally cannot create a provider that forgets to check permissions—the security logic is baked into the base class and executes before your custom code even runs.
+
+**What this means in practice:**
+
+```python
+# ❌ Other frameworks: Security is your responsibility (easy to forget!)
+class MyProvider:
+    async def get_context(self, agent):
+        artifacts = store.get_all()  # OOPS! Forgot to check visibility!
+        return artifacts  # 🔥 Security vulnerability
+
+# ✅ Flock: Security is enforced automatically (impossible to bypass!)
+class MyProvider(BaseContextProvider):
+    async def get_artifacts(self, request):
+        artifacts = await store.query_artifacts(...)
+        return artifacts  # ✨ Visibility filtering happens automatically!
+        # BaseContextProvider calls .visibility.allows() for you
+        # You CANNOT bypass this - it's enforced by the architecture
+```
+
+**Built-in providers (all inherit BaseContextProvider):**
+- `DefaultContextProvider` - Full blackboard access (visibility-filtered)
+- `CorrelatedContextProvider` - Workflow isolation (visibility-filtered)
+- `RecentContextProvider` - Token cost control (visibility-filtered)
+- `TimeWindowContextProvider` - Time-based filtering (visibility-filtered)
+- `EmptyContextProvider` - Stateless agents (zero context)
+- `FilteredContextProvider` - Custom filtering (visibility-filtered)
+
+**Every single one enforces visibility automatically. Zero chance of accidentally leaking data.**
+
+This isn't just convenient—it's **security by design**. When you're building HIPAA-compliant healthcare systems or SOC2-certified SaaS platforms, "impossible to bypass even by accident" is the only acceptable standard.
+
+---
+
+### Context Providers (The Smart Filter)
+
+**Control what agents see with custom Context Providers:**
+
+```python
+from flock.context_provider import FilteredContextProvider, PasswordRedactorProvider
+from flock.store import FilterConfig
+
+# Global filtering - all agents see only urgent items
+flock = Flock(
+    "openai/gpt-4.1",
+    context_provider=FilteredContextProvider(FilterConfig(tags={"urgent"}))
+)
+
+# Per-agent overrides - specialized context per agent
+error_agent = flock.agent("errors").consumes(Log).publishes(Alert)
+error_agent.context_provider = FilteredContextProvider(FilterConfig(tags={"ERROR"}))
+
+# Production-ready password filtering
+from examples.context_provider import PasswordRedactorProvider
+flock = Flock(
+    "openai/gpt-4.1",
+    context_provider=PasswordRedactorProvider()  # Auto-redacts sensitive data!
+)
+```
+
+**What just happened:**
+- ✅ **Filtered context** - Agents see only relevant artifacts (save tokens, improve performance)
+- ✅ **Security boundary** - Visibility enforcement + custom filtering (mandatory, cannot bypass)
+- ✅ **Sensitive data protection** - Auto-redact passwords, API keys, credit cards, SSN, JWT tokens
+- ✅ **Per-agent specialization** - Different agents, different context rules
+
+**Production patterns:**
+```python
+# Password/secret redaction (copy-paste ready!)
+provider = PasswordRedactorProvider(
+    custom_patterns={"internal_id": r"ID-\d{6}"},
+    redaction_text="[REDACTED]"
+)
+
+# Role-based access control
+junior_agent.context_provider = FilteredContextProvider(FilterConfig(tags={"ERROR"}))
+senior_agent.context_provider = FilteredContextProvider(FilterConfig(tags={"ERROR", "WARN"}))
+admin_agent.context_provider = None  # See everything (uses default)
+
+# Multi-tenant isolation
+agent.context_provider = FilteredContextProvider(
+    FilterConfig(tags={"tenant:customer_123"})
+)
+```
+
+**Why this matters:** Reduce token costs (90%+ with smart filtering), protect sensitive data (auto-redact secrets), improve performance (agents see only what they need).
+
+**📖 [Learn more: Context Providers Guide](https://whiteducksoftware.github.io/flock/guides/context-providers/) | [Steal production code →](examples/08-context-provider/)**
+
 ### Batching Pattern: Parallel Execution Control
 
 **A key differentiator:** The separation of `publish()` and `run_until_idle()` enables parallel execution.

{flock_core-0.5.8 → flock_core-0.5.10}/README.md

@@ -4,11 +4,11 @@
 <p align="center">
   <a href="https://whiteducksoftware.github.io/flock/" target="_blank"><img alt="Documentation" src="https://img.shields.io/badge/docs-online-blue?style=for-the-badge&logo=readthedocs"></a>
   <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>
-  <img alt="Python Version" src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python">
+  <img alt="Python Version" src="https://img.shields.io/badge/python-3.12%2B-blue?style=for-the-badge&logo=python">
   <a href="LICENSE" target="_blank"><img alt="License" src="https://img.shields.io/github/license/whiteducksoftware/flock?style=for-the-badge"></a>
   <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>
-  <img alt="Test Coverage" src="https://img.shields.io/badge/coverage-77%25-green?style=for-the-badge">
-  <img alt="Tests" src="https://img.shields.io/badge/tests-743%20passing-brightgreen?style=for-the-badge">
+  <a href="https://codecov.io/gh/whiteducksoftware/flock" target="_blank"><img alt="Test Coverage" src="https://codecov.io/gh/whiteducksoftware/flock/branch/main/graph/badge.svg?token=YOUR_TOKEN_HERE&style=for-the-badge"></a>
+  <img alt="Tests" src="https://img.shields.io/badge/tests-1300+-brightgreen?style=for-the-badge">
 </p>
 
 ---
@@ -254,6 +254,39 @@ asyncio.run(main())
 
 ---
 
+## Context Provider Primer (Security + Cost)
+
+Context Providers are the security and efficiency layer between agents and the blackboard. They decide what each agent sees in its historical context and always enforce visibility rules.
+
+Why use them
+- Enforce access control (visibility is applied before engines see data)
+- Cut context size (often 90%+) by filtering to what matters
+- Specialize per agent or set a global default
+
+Copy/paste examples
+```python
+from flock import Flock
+from flock.context_provider import FilteredContextProvider
+from flock.store import FilterConfig
+
+# Global: show only urgent items (limit context size)
+flock = Flock(
+    "openai/gpt-4.1",
+    context_provider=FilteredContextProvider(FilterConfig(tags={"urgent"}), limit=50)
+)
+
+# Per-agent: override global for a specific role
+senior = flock.agent("senior").consumes(LogEntry).publishes(Analysis)
+senior.context_provider = FilteredContextProvider(
+    FilterConfig(tags={"ERROR", "WARN"}),
+    limit=200
+)
+```
+
+Learn more: docs/guides/context-providers.md
+
+---
+
 ## Persistent Blackboard History
 
 The in-memory store is still great for local tinkering, but production teams now have a durable option. Plugging in `SQLiteBlackboardStore` turns the blackboard into a persistent event log with first-class ergonomics:
@@ -508,8 +541,105 @@ artifact.visibility = AfterVisibility(ttl=timedelta(hours=24), then=PublicVisibi
 agent.publishes(PublicReport, visibility=PublicVisibility())
 ```
 
+**Visibility has a dual purpose:** It controls both which agents can be **triggered** by an artifact AND which artifacts agents can **see** in their context. This ensures consistent security across agent execution and data access—agents cannot bypass visibility controls through subscription filters or context providers.
+
 **Why this matters:** Financial services, healthcare, defense, SaaS platforms all need this for compliance. Other frameworks make you build it yourself.
 
+---
+
+### 🔒 Architecturally Impossible to Bypass Security
+
+**Here's what makes Flock different:** In most frameworks, security is something you remember to add. In Flock, **it's architecturally impossible to forget.**
+
+Every context provider in Flock inherits from `BaseContextProvider`, which enforces visibility filtering **automatically**. You literally cannot create a provider that forgets to check permissions—the security logic is baked into the base class and executes before your custom code even runs.
+
+**What this means in practice:**
+
+```python
+# ❌ Other frameworks: Security is your responsibility (easy to forget!)
+class MyProvider:
+    async def get_context(self, agent):
+        artifacts = store.get_all()  # OOPS! Forgot to check visibility!
+        return artifacts  # 🔥 Security vulnerability
+
+# ✅ Flock: Security is enforced automatically (impossible to bypass!)
+class MyProvider(BaseContextProvider):
+    async def get_artifacts(self, request):
+        artifacts = await store.query_artifacts(...)
+        return artifacts  # ✨ Visibility filtering happens automatically!
+        # BaseContextProvider calls .visibility.allows() for you
+        # You CANNOT bypass this - it's enforced by the architecture
+```
+
+**Built-in providers (all inherit BaseContextProvider):**
+- `DefaultContextProvider` - Full blackboard access (visibility-filtered)
+- `CorrelatedContextProvider` - Workflow isolation (visibility-filtered)
+- `RecentContextProvider` - Token cost control (visibility-filtered)
+- `TimeWindowContextProvider` - Time-based filtering (visibility-filtered)
+- `EmptyContextProvider` - Stateless agents (zero context)
+- `FilteredContextProvider` - Custom filtering (visibility-filtered)
+
+**Every single one enforces visibility automatically. Zero chance of accidentally leaking data.**
+
+This isn't just convenient—it's **security by design**. When you're building HIPAA-compliant healthcare systems or SOC2-certified SaaS platforms, "impossible to bypass even by accident" is the only acceptable standard.
+
+---
+
+### Context Providers (The Smart Filter)
+
+**Control what agents see with custom Context Providers:**
+
+```python
+from flock.context_provider import FilteredContextProvider, PasswordRedactorProvider
+from flock.store import FilterConfig
+
+# Global filtering - all agents see only urgent items
+flock = Flock(
+    "openai/gpt-4.1",
+    context_provider=FilteredContextProvider(FilterConfig(tags={"urgent"}))
+)
+
+# Per-agent overrides - specialized context per agent
+error_agent = flock.agent("errors").consumes(Log).publishes(Alert)
+error_agent.context_provider = FilteredContextProvider(FilterConfig(tags={"ERROR"}))
+
+# Production-ready password filtering
+from examples.context_provider import PasswordRedactorProvider
+flock = Flock(
+    "openai/gpt-4.1",
+    context_provider=PasswordRedactorProvider()  # Auto-redacts sensitive data!
+)
+```
+
+**What just happened:**
+- ✅ **Filtered context** - Agents see only relevant artifacts (save tokens, improve performance)
+- ✅ **Security boundary** - Visibility enforcement + custom filtering (mandatory, cannot bypass)
+- ✅ **Sensitive data protection** - Auto-redact passwords, API keys, credit cards, SSN, JWT tokens
+- ✅ **Per-agent specialization** - Different agents, different context rules
+
+**Production patterns:**
+```python
+# Password/secret redaction (copy-paste ready!)
+provider = PasswordRedactorProvider(
+    custom_patterns={"internal_id": r"ID-\d{6}"},
+    redaction_text="[REDACTED]"
+)
+
+# Role-based access control
+junior_agent.context_provider = FilteredContextProvider(FilterConfig(tags={"ERROR"}))
+senior_agent.context_provider = FilteredContextProvider(FilterConfig(tags={"ERROR", "WARN"}))
+admin_agent.context_provider = None  # See everything (uses default)
+
+# Multi-tenant isolation
+agent.context_provider = FilteredContextProvider(
+    FilterConfig(tags={"tenant:customer_123"})
+)
+```
+
+**Why this matters:** Reduce token costs (90%+ with smart filtering), protect sensitive data (auto-redact secrets), improve performance (agents see only what they need).
+
+**📖 [Learn more: Context Providers Guide](https://whiteducksoftware.github.io/flock/guides/context-providers/) | [Steal production code →](examples/08-context-provider/)**
+
 ### Batching Pattern: Parallel Execution Control
 
 **A key differentiator:** The separation of `publish()` and `run_until_idle()` enables parallel execution.