IRCP Protocol Documentation

┌─────────────────────────────────────────────────────────────────┐
│                      DUAL-RING ARCHITECTURE                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   FORWARD RING (Assistant Messages)                             │
│   ┌─────┐      ┌─────┐      ┌─────┐      ┌─────┐               │
│   │ A₁  │─────▶│ A₂  │─────▶│ A₃  │─────▶│ A₄  │               │
│   │(x,y,z)     │(x,y,z)     │(x,y,z)     │(x,y,z)               │
│   └──┬──┘      └──┬──┘      └──┬──┘      └──┬──┘               │
│      │            │            │            │                    │
│      │ Cross-Ring │            │            │                    │
│      │ Attention  │            │            │                    │
│      ▼            ▼            ▼            ▼                    │
│   ┌──┴──┐      ┌──┴──┐      ┌──┴──┐      ┌──┴──┐               │
│   │ U₁  │─────▶│ U₂  │─────▶│ U₃  │─────▶│ U₄  │               │
│   │(x',y',z')  │(x',y',z')  │(x',y',z')  │(x',y',z')            │
│   └─────┘      └─────┘      └─────┘      └─────┘               │
│   INVERSE RING (User Messages)                                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

def calculate_intent_depth(text: str) -> float:
    """
    Higher values indicate deeper reasoning or more complex intent.

    Factors:
    - Word count (longer messages suggest more depth)
    - Average word length (complex vocabulary)
    - Sentence count (multiple thoughts)
    """
    words = text.split()
    avg_word_length = sum(len(word) for word in words) / max(len(words), 1)
    sentence_count = max(text.count(".") + text.count("?") + text.count("!"), 1)

    # Normalize to [0, 1]
    return min(1.0, (len(words) / 100.0) * (avg_word_length / 10.0) * (sentence_count / 5.0))

def calculate_temporal_consistency(current_text: str, history: List[str]) -> float:
    """
    Higher values indicate more consistency with previous responses.

    Method: Word overlap similarity with recent messages.
    """
    if len(history) < 2:
        return 0.5  # Default mid-range

    current_words = set(current_text.lower().split())
    similarities = []

    for prev_text in history[-3:]:  # Last 3 messages
        prev_words = set(prev_text.lower().split())
        overlap = len(current_words.intersection(prev_words))
        similarity = overlap / max(len(current_words.union(prev_words)), 1)
        similarities.append(similarity)

    return sum(similarities) / len(similarities)

def calculate_behavioral_homogeneity(text: str, history: List[str]) -> float:
    """
    Higher values indicate consistency in response strategy across topics.

    Metrics extracted:
    - Average sentence length
    - Question ratio (questions per sentence)
    - Exclamation ratio
    - Word density (unique words / total words)
    """
    if len(history) < 3:
        return 0.5  # Default

    current_metrics = extract_behavioral_metrics(text)
    past_metrics = [extract_behavioral_metrics(h) for h in history[-5:]]

    # Calculate variance for each metric
    variances = []
    for key in current_metrics.keys():
        values = [m.get(key, 0) for m in past_metrics] + [current_metrics[key]]
        variances.append(np.var(values))

    # Higher homogeneity = lower variance
    avg_variance = sum(variances) / len(variances)
    return 1.0 / (1.0 + avg_variance)

A_F(i,j) = exp(-α|x_i - x_j| - β|y_i - y_j| - γ|z_i - z_j|)

def calculate_forward_attention(node1: ChainNode, node2: ChainNode) -> float:
    """Calculate attention weight between two nodes in forward ring."""
    x_diff = abs(node1.forward_coords[0] - node2.forward_coords[0])
    y_diff = abs(node1.forward_coords[1] - node2.forward_coords[1])
    z_diff = abs(node1.forward_coords[2] - node2.forward_coords[2])

    # Exponential decay based on coordinate distance
    attention = np.exp(-alpha * x_diff - beta * y_diff - gamma * z_diff)
    return float(attention)

A_I(i,j) = exp(-α'|x'_i - x'_j| - β'|y'_i - y'_j| - γ'|z'_i - z'_j|)

def calculate_inverse_attention(node1: ChainNode, node2: ChainNode) -> float:
    """Calculate attention weight between two nodes in inverse ring."""
    x_diff = abs(node1.inverse_coords[0] - node2.inverse_coords[0])
    y_diff = abs(node1.inverse_coords[1] - node2.inverse_coords[1])
    z_diff = abs(node1.inverse_coords[2] - node2.inverse_coords[2])

    attention = np.exp(-alpha_prime * x_diff - beta_prime * y_diff - gamma_prime * z_diff)
    return float(attention)

A_C(i,j) = σ(Σ w_k · [x, y, z, x', y', z']_k)

def calculate_cross_ring_attention(forward_node: ChainNode, inverse_node: ChainNode) -> float:
    """Calculate attention between forward and inverse ring nodes."""
    # Concatenate coordinates from both rings
    combined = np.concatenate([
        forward_node.forward_coords,  # [x, y, z]
        inverse_node.inverse_coords   # [x', y', z']
    ])

    # Weighted sum with configurable weights
    weights = np.array([0.2, 0.2, 0.2, 0.1, 0.1, 0.2])
    weighted_sum = np.sum(combined * weights)

    # Sigmoid activation for smooth [0, 1] output
    cross_attention = 1.0 / (1.0 + np.exp(-weighted_sum))
    return float(cross_attention)

d/dt C = A_F(C) · C

def propagate_forward_ring(self) -> None:
    """Apply forward flow dynamics."""
    forward_ids = list(self.forward_ring.keys())
    forward_coords = np.array([self.forward_ring[id].forward_coords for id in forward_ids])

    # Build attention matrix
    forward_attention = np.zeros((len(forward_ids), len(forward_ids)))
    for i, id1 in enumerate(forward_ids):
        for j, id2 in enumerate(forward_ids):
            forward_attention[i, j] = self.chains_links[id1].get_attention_weight(id1, id2)

    # Normalize rows (stochastic matrix)
    forward_attention = normalize_rows(forward_attention)

    # Apply flow: C_new = A_F · C
    new_forward_coords = forward_attention @ forward_coords

    # Update coordinates
    for i, id in enumerate(forward_ids):
        self.forward_ring[id].forward_coords = new_forward_coords[i]

d/dt C' = A_I(C') · C'

def propagate_inverse_ring(self) -> None:
    """Apply inverse flow dynamics."""
    inverse_ids = list(self.inverse_ring.keys())
    inverse_coords = np.array([self.inverse_ring[id].inverse_coords for id in inverse_ids])

    # Build attention matrix
    inverse_attention = np.zeros((len(inverse_ids), len(inverse_ids)))
    for i, id1 in enumerate(inverse_ids):
        for j, id2 in enumerate(inverse_ids):
            inverse_attention[i, j] = self.chains_links[id1].get_attention_weight(id1, id2)

    # Normalize rows
    inverse_attention = normalize_rows(inverse_attention)

    # Apply flow: C'_new = A_I · C'
    new_inverse_coords = inverse_attention @ inverse_coords

    # Update coordinates
    for i, id in enumerate(inverse_ids):
        self.inverse_ring[id].inverse_coords = new_inverse_coords[i]

||C||² = Σ ||c_i||² = constant

def conserve_forward_ring(self) -> None:
    """Apply conservation law to forward ring coordinates."""
    forward_ids = list(self.forward_ring.keys())
    forward_coords = np.array([self.forward_ring[id].forward_coords for id in forward_ids])

    # Calculate current squared norm
    current_norm_squared = np.sum(np.square(forward_coords))

    if current_norm_squared > 0:
        # Scale factor to preserve squared norm
        scale_factor = np.sqrt(len(forward_ids) / current_norm_squared)

        # Apply scaling
        for id in forward_ids:
            self.forward_ring[id].forward_coords *= scale_factor

1. ANALYZE conversation complexity
2. DETERMINE suggested propagation steps
3. FOR each step until convergence OR max_steps:
   a. STORE current coordinates
   b. PROPAGATE forward ring
   c. PROPAGATE inverse ring
   d. APPLY conservation laws
   e. CALCULATE coordinate change
   f. CHECK for convergence
4. RETURN propagation statistics

def propagate_context(
    self,
    steps: int = None,
    convergence_threshold: float = 1e-4,
    max_steps: int = 10,
    adaptive: bool = True,
    learning_rate: float = 0.1
) -> dict:
    """
    Propagate context through both rings with adaptive step count.

    Parameters:
        steps: Fixed number of steps (overrides adaptive)
        convergence_threshold: Stop when coordinate change < threshold
        max_steps: Maximum steps in adaptive mode
        adaptive: Whether to use adaptive step determination
        learning_rate: Rate of coordinate updates

    Returns:
        Dictionary with propagation statistics
    """

    # Fixed steps mode
    if steps is not None:
        self._propagate_n_steps(steps, learning_rate)
        return {"steps_taken": steps, "adaptive": False}

    if not adaptive:
        self._propagate_n_steps(1, learning_rate)
        return {"steps_taken": 1, "adaptive": False}

    # === ADAPTIVE MODE ===

    # Step 1: Analyze conversation complexity
    conversation_length = len(self.chain_tree.get_chains())
    user_chains = len(self.chain_tree.get_chains_by_type("user"))
    assistant_chains = len(self.chain_tree.get_chains_by_type("assistant"))

    # Step 2: Determine initial step count
    if conversation_length <= 4:
        suggested_steps = 1  # Short conversations
    elif conversation_length <= 10:
        suggested_steps = min(3, max_steps)  # Medium
    else:
        suggested_steps = min(5, max_steps)  # Long

    # Adjust for asymmetric conversations
    user_assistant_ratio = user_chains / max(assistant_chains, 1)
    if user_assistant_ratio < 0.5 or user_assistant_ratio > 2.0:
        suggested_steps = min(suggested_steps + 2, max_steps)

    # Adjust for user intent complexity
    user_patterns = self.chain_tree.analyze_user_patterns()
    if user_patterns.get("average_intent_depth", 0) > 0.7:
        suggested_steps = min(suggested_steps + 1, max_steps)

    # Step 3: Iterative propagation with convergence check
    steps_taken = 0
    max_coordinate_change = float("inf")

    while steps_taken < suggested_steps and max_coordinate_change > convergence_threshold:
        # Store current state
        prev_forward = self._get_current_coordinates(forward=True)
        prev_inverse = self._get_current_coordinates(forward=False)

        # Propagate one step
        self._propagate_one_step(learning_rate)
        steps_taken += 1

        # Calculate changes
        new_forward = self._get_current_coordinates(forward=True)
        new_inverse = self._get_current_coordinates(forward=False)

        change_forward = self._max_coordinate_change(prev_forward, new_forward)
        change_inverse = self._max_coordinate_change(prev_inverse, new_inverse)
        max_coordinate_change = max(change_forward, change_inverse)

        # Adaptive learning rate
        if max_coordinate_change < convergence_threshold / 10:
            learning_rate *= 1.5  # Speed up convergence

    return {
        "steps_taken": steps_taken,
        "adaptive": True,
        "max_coordinate_change": max_coordinate_change,
        "suggested_steps": suggested_steps,
        "convergence_reached": max_coordinate_change <= convergence_threshold
    }

from dlm.response import ReplyChainSystem
from dlm.core.embeddings import IRCPEmbedder

# Initialize embedding provider
embedder = IRCPEmbedder(
    enable_caching=True,
    cache_capacity=512,
    device="cpu"
)

# Create reply chain system with IRCP
system = ReplyChainSystem(
    name="LinearAlgebra",
    verbose=True,
    embedding_provider=embedder
)

# Process conversation
conversation = [
    {"role": "user", "content": "What is topology?"},
    {"role": "assistant", "content": "Topology is the study of geometric properties..."},
    {"role": "user", "content": "Can you give an example?"},
    {"role": "assistant", "content": "Sure! Consider a coffee mug and a donut..."},
]
system.process_conversations(conversation)

# Propagate context with adaptive steps
result = system.propagate_context(
    adaptive=True,
    convergence_threshold=1e-4,
    max_steps=10
)

print(f"Converged in {result['steps_taken']} steps")
print(f"Max coordinate change: {result['max_coordinate_change']}")

from dlm.response.links import ChainTreeLink, ChainNode
from dlm.models import Content, ChainCoordinate

# Initialize chain tree
tree = ChainTreeLink(chain_factory=factory, allow_duplicates=False)

# Add user message (inverse ring)
user_content = Content(role="user", content="What is recursion?")
user_coord = ChainCoordinate(x=0.5, y=0.3, z=0.7, t=0.0, n_parts=1)
tree.add_chain("user", "msg_001", user_content, user_coord)

# Add assistant message (forward ring)
assistant_content = Content(role="assistant", content="Recursion is when...")
assistant_coord = ChainCoordinate(x=0.6, y=0.4, z=0.8, t=0.1, n_parts=2)
tree.add_chain("assistant", "msg_002", assistant_content, assistant_coord, parent="msg_001")

# Propagate with specific parameters
tree.propagate_context_with_params(steps=5, learning_rate=0.1)

# Analyze user patterns
patterns = tree.analyze_user_patterns()
print(f"Average intent depth: {patterns['average_intent_depth']}")
print(f"User categories: {patterns['user_categories']}")

# Optimize context for a specific query
query = "Tell me more about topological invariants"

# This will:
# 1. Restore relevant archived chains
# 2. Archive irrelevant chains
# 3. Reorder remaining chains by relevance
optimized_order = system.chain_tree.optimize_context_for_query(query)

print(f"Optimized context with {len(optimized_order)} chains")

# Get recommendations for response adaptation
recommendations = tree.recommend_content_adaptation()
print(f"Recommended content depth: {recommendations['content_depth']}")
print(f"Recommended tone: {recommendations['tone']}")

# Get attention weights between specific nodes
forward_attention = tree.chains_links["msg_001"].get_attention_weight("msg_001", "msg_002")
print(f"Forward attention (msg_001 -> msg_002): {forward_attention}")

# Calculate average attention across the network
def calculate_average_attention(tree):
    total_attention = 0
    count = 0

    for id1 in tree.forward_ring:
        for id2 in tree.forward_ring:
            if id1 != id2:
                weight = tree.chains_links[id1].get_attention_weight(id1, id2)
                total_attention += weight
                count += 1

    return total_attention / max(count, 1)

avg_attention = calculate_average_attention(tree)
print(f"Average forward ring attention: {avg_attention}")

# Archive chains by age (keep only last 10)
archived_count = tree.archive_chains_by_age(keep_last_n=10)
print(f"Archived {archived_count} old chains")

# Archive by relevance to current topic
archived_count = tree.archive_chains_by_relevance(
    current_focus="machine learning optimization",
    min_relevance=0.5
)
print(f"Archived {archived_count} irrelevant chains")

# Find and restore relevant archived chains
relevant_ids = tree.get_relevant_archived_chains(
    query="neural network training",
    similarity_threshold=0.7,
    max_results=5
)

for chain_id in relevant_ids:
    tree.restore_chain(chain_id, reconnect_relationships=True)

# Get archive statistics
stats = tree.get_archive_statistics()
print(f"Total archived: {stats['total_archived_chains']}")
print(f"Archived user chains: {stats['archived_user_chains']}")

@dataclass
class IRCPConfig:
    """IRCP-specific configuration."""

    # Forward ring attention parameters
    alpha: float = 1.0      # Weight for intent depth (x)
    beta: float = 1.0       # Weight for temporal consistency (y)
    gamma: float = 1.0      # Weight for behavioral homogeneity (z)

    # Inverse ring attention parameters
    alpha_prime: float = 1.0  # Weight for user intent depth (x')
    beta_prime: float = 1.0   # Weight for user temporal consistency (y')
    gamma_prime: float = 1.0  # Weight for user behavioral patterns (z')

    # Propagation settings
    max_propagation_steps: int = 10
    convergence_threshold: float = 1e-4
    learning_rate: float = 0.1
    adaptive_propagation: bool = True

    # Conservation settings
    apply_conservation: bool = True

    # Cross-ring attention weights
    cross_ring_weights: List[float] = field(
        default_factory=lambda: [0.2, 0.2, 0.2, 0.1, 0.1, 0.2]
    )

from dlm.config import DLMConfig

config = DLMConfig.create_default()

# Adjust IRCP settings for short conversations
config.ircp.max_propagation_steps = 5
config.ircp.convergence_threshold = 1e-3

# Adjust for long conversations
config.ircp.max_propagation_steps = 15
config.ircp.learning_rate = 0.05

from dlm.core.embeddings import IRCPEmbedder

# Create embedder with coordinate prediction
embedder = IRCPEmbedder(
    model_path="models/ircp_model.pt",
    enable_caching=True,
    device="cuda"
)

# Get IRCP-specific predictions
results = embedder.predict_all("What is machine learning?")
print(f"Embeddings shape: {results['embeddings'].shape}")
print(f"Coordinates (x,y,z,t): {results['coordinates']}")
print(f"Response patterns: {results['response_patterns'].shape}")
print(f"Confidence: {results['confidence']}")

from dlm.core.coordinates import DLMCoordinate, DLMCoordinateCalculator
from dlm.core.adapters import CoordinateAdapter

# Calculate coordinates
calc = DLMCoordinateCalculator(
    normalize_coordinates=True,
    homogeneity_method="similarity_based"
)

# Convert DLM coordinates to IRCP coordinates
dlm_coord = DLMCoordinate(x=0.5, y=0.3, z=0.7, t=0.2, n_parts=2)
ircp_coord = CoordinateAdapter.dlm_to_ircp(dlm_coord)

# Convert back
dlm_coord_restored = CoordinateAdapter.ircp_to_dlm(ircp_coord)

from dlm.response import ReplyChainSystem

# Full integration example
system = ReplyChainSystem(
    name="Topology",
    verbose=True,
    embedding_provider=embedder
)

# Process and propagate
system.process_conversations(conversation_data)
result = system.propagate_context(adaptive=True)

# Construct reply chain for new input
reply_chain = system.construct_reply_chain(
    user_input="Explain manifolds",
    max_history_length=5
)

# Get metrics
metrics = system.get_conversation_metrics()
print(f"Forward ring size: {metrics['forward_ring_size']}")
print(f"Inverse ring size: {metrics['inverse_ring_size']}")
print(f"Average attention: {metrics['average_attention']}")