Demos and Examples

Read time: 10 minutes

Overview

This guide showcases working demonstrations of Prism patterns and features. Each demo includes:

Working code you can run locally
Performance metrics from real execution
Use case scenarios from production systems
Integration examples with client libraries

Quick Start

# Install dependencies
uv sync

# Run a demo
task demo-multi-namespace

# Run specific pattern demos
python3 clients/python/examples/multicast_registry_demo.py

1. Multicast Registry Demo

Pattern: Multicast Registry (RFC-017) File: clients/python/examples/multicast_registry_demo.py Status: ✅ Complete

What It Demonstrates

1,000 cryptographic agents with Ed25519 key pairs
Identity registration with public keys and fingerprints
Filter-based enumeration by agent type and metadata
High-throughput multicasting (100,000 messages)
Real cryptographic identity validation

Architecture

┌─────────────────────────────────────────────────────────┐
│          Multicast Registry Coordinator                 │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Register → Store in Registry (Redis) + Metadata       │
│                                                         │
│  Enumerate → Query with Filter Expression              │
│                                                         │
│  Multicast → Fan-out to Messaging Backend (NATS)       │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   Registry   │  │  Messaging   │  │  Durability  │ │
│  │   Slot       │  │    Slot      │  │  Slot (Opt)  │ │
│  │  (Redis)     │  │   (NATS)     │  │              │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────┘

Use Cases

Microservices Discovery
- Register service instances with health metadata
- Query by zone, version, or capability
- Multicast configuration updates to filtered services
IoT Device Management
- Register devices with firmware version and capabilities
- Enumerate devices by location or type
- Push firmware updates to specific device cohorts
Agent Coordination
- Register autonomous agents with cryptographic identities
- Discover agents by role or workload
- Broadcast tasks to filtered agent pools
Presence Systems
- Register online users with session metadata
- Query users by room or status
- Fan-out notifications to active users

Agent Types

The demo creates four types of agents with different distributions:

Type	Count	Percentage	Use Case
Remediation	400	40%	Infrastructure repair and patching
Monitoring	300	30%	Health checks and alerting
Validation	200	20%	Compliance and security scanning
Reporting	100	10%	Metrics aggregation and dashboards

Performance Results

From MEMO-044 production readiness assessment:

Operation	Target	Actual	Status
Registration	16,264 ops/sec	16,000+ ops/sec	✅ Met
Enumeration	60,240 ops/sec	60,000+ ops/sec	✅ Met
Multicast (1000 targets)	<100ms	~24ms	✅ Exceeded (4.2x faster)

Cryptographic Identity Integration

The demo integrates with the agf-iac-remediation-poc agent identity system:

# Create agent with Ed25519 key pair
manager = AgentIdentityManager(
    agent_email=f"{agent_name}@prism.local",
    agent_type="remediation"
)
identity = manager.initialize_identity()

# Register with multicast registry
registry.register(
    identity=identity.agent_name,
    metadata={
        "type": agent_type,
        "email": identity.agent_email,
        "fingerprint": identity.fingerprint,  # Ed25519 public key fingerprint
        "public_key": public_key_pem,         # Full PEM-encoded public key
        "node_id": identity.node_id,
        "created_at": identity.created_at
    },
    ttl_seconds=3600
)

Running the Demo

# Prerequisites
# 1. Install agent identity library
git clone git@github.com:your-org/agf-iac-remediation-poc.git ~/dev/agf-iac-remediation-poc

# 2. Install Python dependencies
cd clients/python
uv sync

# 3. Run the demo
python3 examples/multicast_registry_demo.py

Expected output:

======================================================================
  Multicast Registry Demo: 1000 Cryptographic Agents
  Demonstrating high-throughput agent registration and message delivery
======================================================================

Configuration
  Agent count: 1,000
  Messages per agent: 100
  Total messages: 100,000

Phase 1: Registering 1,000 Agents
✓ Registered 1,000 agents in 62.3ms
  Throughput: 16,051 ops/sec
  Performance vs target: 98.7% of 16,264 ops/sec

Phase 2: Enumerating Agents by Type
✓ Found 400 remediation agents in 6.7ms
✓ Found 300 monitoring agents in 5.2ms
✓ Found 200 validation agents in 4.1ms
✓ Found 100 reporting agents in 2.8ms
✓ Enumerated all 1,000 agents in 16.6ms
  Throughput: 60,241 ops/sec
  Performance vs target: 100.0% of 60,240 ops/sec

Phase 3: Multicasting Messages
✓ Multicast to 1,000 agents in 23.8ms
  Delivered: 1,000
  Failed: 0
  Performance vs target: 1.01x faster than 24ms target

Phase 4: High-Throughput Message Delivery (100,000 messages)
✓ Delivered 100,000 messages in 6.18s
  Throughput: 16,181 msg/sec
  Avg latency per message: 0.062ms

Phase 5: Cryptographic Identity Verification
Agent Identity Verification
┌─────────────────────┬──────────────┬─────────────────────────────────────┬────────────┐
│ Agent Name          │ Type         │ Fingerprint                         │ Status     │
├─────────────────────┼──────────────┼─────────────────────────────────────┼────────────┤
│ agent-swift-builder │ remediation  │ a1b2c3d4e5f67890abcdef123456...    │ ✓ Verified │
│ agent-clever-coder  │ monitoring   │ f9e8d7c6b5a4321098765fedcba...    │ ✓ Verified │
│ agent-bright-fixer  │ validation   │ 1234567890abcdef1234567890ab...    │ ✓ Verified │
│ agent-keen-helper   │ reporting    │ fedcba9876543210fedcba987654...    │ ✓ Verified │
│ agent-nimble-maker  │ remediation  │ 9876543210fedcba9876543210fe...    │ ✓ Verified │
└─────────────────────┴──────────────┴─────────────────────────────────────┴────────────┘

Code Highlights

Registration with cryptographic identity:

# Generate Ed25519 key pair and agent identity
agent_name, metadata = create_agent_identity("remediation", temp_dir)

# Register with Prism multicast registry
registry.register(
    identity=agent_name,
    metadata=metadata,
    ttl_seconds=3600  # 1 hour expiration
)

Filter-based enumeration:

# Find all remediation agents
remediation_agents = registry.enumerate(
    filter={"type": "remediation"}
)

# Find agents in specific zone
zone_agents = registry.enumerate(
    filter={"type": "monitoring", "zone": "us-west"}
)

Multicast to filtered targets:

# Send message to all validation agents
result = registry.multicast(
    filter={"type": "validation"},
    payload=json.dumps({
        "command": "scan",
        "target": "infrastructure",
        "priority": "high"
    }).encode()
)

print(f"Delivered to {result.delivered_count}/{result.target_count} agents")

Shared Demo Utilities

The demo uses shared_utils.py for consistent output and timing:

from shared_utils import DemoOutput, Timer, format_duration

output = DemoOutput()  # Rich formatting with plain text fallback

# Formatted sections
output.header("Demo Title", "Subtitle")
output.section("Phase 1")
output.success("Operation completed")
output.metric("Throughput", "16K ops/sec")

# Performance timing
with Timer() as timer:
    # ... perform operation ...
    pass

print(f"Operation took {format_duration(timer.elapsed_ms)}")

2. Multi-Namespace Demo

Pattern: Namespace isolation Command: task demo-multi-namespace Status: ✅ Complete

What It Demonstrates

Multiple namespaces with independent configurations
Concurrent operations across namespaces
Pattern isolation (KeyValue, PubSub, Queue)
Performance monitoring per namespace

Running the Demo

task demo-multi-namespace

Features:

Creates 3 namespaces: cache, events, jobs
Performs 100 operations per namespace concurrently
Shows per-namespace latency and throughput
Validates isolation (no cross-namespace interference)

3. Backend Comparison Demo

Pattern: Backend abstraction File: tests/acceptance/unified_test.go Status: ✅ Complete

What It Demonstrates

Same pattern API works across Redis, NATS, PostgreSQL
Performance comparison between backends
Failure handling (connection loss, timeout)
Automatic retry and circuit breaking

Running the Demo

# Run unified acceptance tests
task test-unified

# Run with specific backend
BACKEND=redis task test-unified
BACKEND=nats task test-unified
BACKEND=postgres task test-unified

Results:

Backend	Latency (p50)	Latency (p99)	Throughput
MemStore	0.5ms	1.2ms	80K ops/sec
Redis	1.2ms	3.8ms	45K ops/sec
NATS	0.8ms	2.1ms	60K ops/sec
PostgreSQL	2.5ms	8.2ms	18K ops/sec

4. Podman Container Demo

Pattern: Scratch-based container optimization Reference: MEMO-007 Status: ✅ Complete

What It Demonstrates

Minimal container images (6MB for Rust, 10MB for Go)
Fast startup times (<100ms)
Resource efficiency (50% less memory)
Production deployment with Podman

Running the Demo

# Build scratch container
task docker-build-scratch

# Run demo
task docker-run-demo

# Check container size
podman images prism-proxy-scratch

See: MEMO-007 (Podman Scratch Container Demo)

5. WAL Pattern Demo

Pattern: Write-Ahead Log (RFC-051) Reference: Netflix production implementation Status: 📝 Planned

What It Will Demonstrate

Durable writes with crash recovery
Ordered replay after failure
Performance characteristics (1-2ms write latency)
Production metrics (billions of mutations/day)

Coming soon: Demo implementation based on Netflix WAL architecture

Demo Infrastructure

Shared Utilities

All Python demos use common infrastructure from shared_utils.py:

DemoOutput class:

Rich library integration for fancy formatting
Plain text fallback (no dependencies required)
Consistent formatting across all demos
Methods: header(), section(), success(), error(), metric(), table()

Timer class:

High-precision timing (time.perf_counter())
Context manager support
Formatted output (µs, ms, s)
Throughput calculation

Example:

output = DemoOutput()

output.header("Performance Test", "Measuring throughput")

with Timer() as timer:
    # ... perform 10,000 operations ...
    pass

output.metric("Duration", format_duration(timer.elapsed_ms))
output.metric("Throughput", format_throughput(10000, timer.elapsed_ms))

Task Automation

Demos are integrated with Taskfile for easy execution:

demo-multi-namespace:
  desc: Multi-Namespace Python Client Demo
  cmds:
    - task: infra:up:all
    - python3 clients/python/examples/multi_namespace_demo.py
    - task: infra:down:all

demo-multicast-registry:
  desc: Multicast Registry with Cryptographic Agents
  cmds:
    - python3 clients/python/examples/multicast_registry_demo.py

Performance Benchmarks

Summary of All Demos

Demo	Pattern	Operations	Duration	Throughput	Notes
Multicast Registry	Multicast Registry	100K messages	6.18s	16K msg/sec	1000 agents
Multi-Namespace	Isolation	300 ops	2.4s	125 ops/sec	3 namespaces
Backend Comparison	All patterns	10K ops each	Varies	See table above	4 backends
Container Demo	Deployment	N/A	Startup <100ms	N/A	6MB image

Next Steps

Run Your First Demo

# 1. Install dependencies
uv sync

# 2. Start infrastructure
task infra:up:all

# 3. Run multicast registry demo
python3 clients/python/examples/multicast_registry_demo.py

# 4. Cleanup
task infra:down:all

Build Your Own Demo

Use the demo infrastructure as a template:

#!/usr/bin/env python3
"""My custom Prism demo."""

from prism_data.sync import Client
from shared_utils import DemoOutput, Timer

output = DemoOutput()

output.header("My Demo", "Demonstrating X pattern")

with Client("localhost:8980") as client:
    # Your demo code here
    pass

output.success("Demo completed!")

Explore More

RFC-017 (Multicast Registry) - Full pattern specification
MEMO-044 (Production Readiness) - Performance analysis
RFC-018 (POC Implementation Strategy) - Development history
User Guide - Getting started with Prism

Feedback

Found issues or have demo suggestions?

GitHub Issues: Report demo issues
Pull Requests: Contribute new demos!

Overview​

Quick Start​

1. Multicast Registry Demo​

What It Demonstrates​

Architecture​

Use Cases​

Agent Types​

Performance Results​

Cryptographic Identity Integration​

Running the Demo​

Code Highlights​

Shared Demo Utilities​

2. Multi-Namespace Demo​

What It Demonstrates​

Running the Demo​

3. Backend Comparison Demo​

What It Demonstrates​

Running the Demo​

4. Podman Container Demo​

What It Demonstrates​

Running the Demo​

5. WAL Pattern Demo​

What It Will Demonstrate​

Demo Infrastructure​

Shared Utilities​

Task Automation​

Performance Benchmarks​

Summary of All Demos​

Next Steps​

Run Your First Demo​

Build Your Own Demo​

Explore More​

Feedback​

Overview

Quick Start

1. Multicast Registry Demo

What It Demonstrates

Architecture

Use Cases

Agent Types

Performance Results

Cryptographic Identity Integration

Running the Demo

Code Highlights

Shared Demo Utilities

2. Multi-Namespace Demo

What It Demonstrates

Running the Demo

3. Backend Comparison Demo

What It Demonstrates

Running the Demo

4. Podman Container Demo

What It Demonstrates

Running the Demo

5. WAL Pattern Demo

What It Will Demonstrate

Demo Infrastructure

Shared Utilities

Task Automation

Performance Benchmarks

Summary of All Demos

Next Steps

Run Your First Demo

Build Your Own Demo

Explore More

Feedback