The PCLIPS Advantage

What is PCLIPS?

PCLIPS allows CLIPS rule-based agents to remotely assert facts to each other over a network. Agents can:

• Broadcast facts to all agents
• Target agents by role (e.g., 'executor', 'planner')
• Target specific agent instances by ID
• Discover other active agents via presence

Step 1: Installation

Get started in two easy steps:

1.1 Install Python dependencies:

pip install -r requirements.txt

1.2 Get an Ably API key:

• Sign up at https://ably.com/
• Create a new app
• Copy your API key (you'll need this for the next step)

Step 2: Run the Example

The example demonstrates three agent types working together:

2.1 Edit example.py and add your Ably API key:

ABLY_API_KEY = "your-key-here"

2.2 Run each agent in a separate terminal:

# Terminal 1
python example.py monitor

# Terminal 2
python example.py executor

# Terminal 3
python example.py planner

Expected Output: You should see the Planner create tasks 1 and 2, the Executor receive and process them, and the Monitor report completions — all in real time across the network.

Step 3: Basic Usage Pattern

Here's the fundamental pattern for creating your own agents:

from pclips import PCLIPSAgent
import time

# Create an agent with name, roles, and Ably key
agent = PCLIPSAgent('my-agent', ['worker'], 'your-ably-key')

# Define CLIPS rules
rules = """
(defrule process-task
    ?f <- (task ?id)
    =>
    (printout t "Processing task " ?id crlf)
    (rassert (str-cat "(result " ?id ")"))
)
"""

agent.load_rules(rules)
agent.reset()

# Assert local fact
agent.local_assert("(task 1)")
agent.run_rules()

# Keep agent running to receive remote facts
while True:
    time.sleep(1)

Step 4: Understanding Agent Identity

Each agent has three key identifiers:

Multiple instances of the same agent name can run with different IDs, allowing you to scale your swarm horizontally.

Step 5: Master the rassert Function

The rassert function is available inside CLIPS rules to publish facts remotely. Here are all the ways to use it:

; Broadcast to all agents
(rassert "(task (id 1) (status new))")

; Target agents with specific role
(rassert "(task (id 1) (status ready))" (create$ executor))

; Target specific agent instance
(rassert "(message (text hello))" nil "andrew-abc123")

; Target specific role AND agent
(rassert "(urgent-task (id 99))" (create$ planner) "planner-xyz789")

Step 6: Presence & Discovery

PCLIPS implements a robust, multi-layered discovery system to track active agents:

Step 7: Channel Isolation for Multiple Swarms

By default, all agents communicate on the 'pclips' channel. Isolate different groups of agents by specifying a custom channel:

# Isolate these agents on a specific channel
agent = PCLIPSAgent('worker-1', ['executor'], 'your-key', channel_name='production-flow')

This allows multiple independent agent swarms to coexist on the same Ably application without interfering with each other's fact assertions.

How It Works: The Architecture

Understanding the flow helps you debug and optimize your agents:

Thread Safety & Reliability

PCLIPS follows a strict threading model to ensure reliability:

• Ably callbacks run in network thread
• Messages are queued (thread-safe)
• Single processing thread owns CLIPS environment
• Only processing thread calls CLIPS methods

This prevents race conditions and ensures your agents remain rock-solid even under load.

Key Features Implemented

• Remote assertion (rassert) from CLIPS rules
• Thread-safe message queue
• Message filtering (own messages, role-based, agent-specific)
• Presence discovery (multi-layered fallback system)
• Standard agent tracking template
• Rule execution safety (400-rule firing limit)
• Message deduplication
• Clean shutdown

License & Resources

License: CC BY-NC-SA 4.0 (Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International)

This project is licensed for non-commercial use only.

Learn More:

• CLIPS Documentation
• Ably Documentation
• Full requirements: PCLIPS-requirements.md (in download kit)