08-semantic

08-semantic: Semantic Subscriptions Examples

This directory contains examples demonstrating Flock's semantic subscription features, which enable intelligent agent routing and context-aware processing based on meaning rather than just keywords.

📚 Prerequisites

Install the semantic extras:

uv add flock-core[semantic]
# or
pip install flock-core[semantic]

This installs sentence-transformers with the all-MiniLM-L6-v2 model (~90MB).

📖 Examples

01_intelligent_ticket_routing.py

Smart ticket routing based on semantic similarity

Demonstrates how support tickets automatically route to specialized teams (Security, Billing, Tech Support) based on the meaning of their content, not just keywords.

Key Concepts:

• Semantic semantic matching (semantic_match="security vulnerability")
• Multi-agent routing patterns
• Automatic team assignment

Run:

uv run examples/08-semantic/01_intelligent_ticket_routing.py

What You'll See:

• Security issues → Security Team
• Billing issues → Billing Team
• Technical problems → Tech Support
• General questions → General Support

All routing happens automatically based on semantic similarity!

---

02_multi_criteria_filtering.py

Advanced semantic filtering with multiple criteria

Demonstrates sophisticated filtering combining:

• Multiple semantic predicates (AND logic)
• Field-specific matching
• Custom similarity thresholds
• Structural filters (where clauses)

Key Concepts:

• Multiple semantic matching: text=["topic1", "topic2"] (both must match)
• Field extraction: text={"field": "abstract", "query": "..."}
• Custom thresholds: text={"threshold": 0.7} (0.3=loose, 0.7=strict)
• Hybrid filtering: semantic + structural

Run:

uv run examples/08-semantic/02_multi_criteria_filtering.py

What You'll See:

• Documents filtered by multiple semantic topics
• Field-specific semantic matching (abstract vs content)
• Threshold effects (strict vs loose matching)
• Combination of semantic + structural filters

---

🎯 Core Concepts

Semantic Text Predicates

# Basic semantic matching
.consumes(Ticket, semantic_match="security vulnerability")

# Multiple topics (ALL must match - AND logic)
.consumes(Doc, text=["security", "compliance"])

# Advanced configuration
.consumes(Doc, text={
    "query": "privacy data protection",
    "threshold": 0.7,     # Strictness (0.0-1.0)
    "field": "abstract"   # Specific field
})

SemanticContextProvider

from flock.semantic import SemanticContextProvider

# Find similar historical artifacts
provider = SemanticContextProvider(
    query_semantic_match="database connection timeout",
    threshold=0.4,        # Similarity threshold
    limit=5,              # Max results
    artifact_type=Incident,
    where=lambda a: a.payload["resolved"] is True
)

similar = await provider.get_context(store)

Threshold Guide

• 0.8-1.0: Very strict (nearly identical)
• 0.6-0.7: Strict (strongly similar)
• 0.4-0.5: Moderate (default, related concepts)
• 0.2-0.3: Loose (broadly related)

🎛️ CLI vs Dashboard Mode

Each example supports both modes:

CLI Mode (default):

USE_DASHBOARD = False

Runs agents and displays results in terminal.

Dashboard Mode:

USE_DASHBOARD = True

Launches interactive web interface at http://localhost:8344.

💡 Tips

1. Start with default threshold (0.4) - Works well for most cases
2. Use multiple predicates for precision - text=["topic1", "topic2"]
3. Combine semantic + structural - Add where= clauses for hybrid filtering
4. Extract specific fields - Use field="abstract" for targeted matching
5. Test with CLI first - Easier debugging before dashboard mode

📊 Performance

• Single embedding: ~15ms (CPU)
• Batch 10 texts: ~45ms (~4.5ms per text)
• Cache hit: <1ms
• Memory: ~150MB model + ~6MB per 10k cached embeddings

🔗 Additional Resources

• Main Documentation: docs/semantic-subscriptions.md
• API Reference: Full API details in main docs
• Test Suite: tests/semantic/ (38 comprehensive tests)

🐛 Troubleshooting

No matches despite relevant content?

• Lower threshold: text={"query": "...", "threshold": 0.3}
• Check if field extraction needed: field="abstract"
• Verify semantic extras installed: uv add flock-core[semantic]

Import errors?

# Ensure semantic extras installed
uv add flock-core[semantic]

---

🚀 Ready to explore semantic subscriptions? Start with example 01!