Grand Diomande Research · Full HTML Reader

IRCP Service

Python-based service providing **Inverse Ring Contextual Propagation (IRCP)** embeddings for topological search in TrajectoryOS. Enables 5D coordinate-based retrieval beyond traditional semantic search.

Agents That Account for Themselves research note experiment writeup candidate score 24 .md

Full Public Reader

IRCP Service

Status: ✅ Live - IRCP embedding and search functionality operational

Python-based service providing Inverse Ring Contextual Propagation (IRCP) embeddings for topological search in TrajectoryOS. Enables 5D coordinate-based retrieval beyond traditional semantic search.

---

Overview

IRCP Service generates topological embeddings for life events, enabling multi-dimensional search that combines:
- Semantic similarity (what events mean)
- Topological distance (where events sit in 5D space)
- Physics-based filtering (life regime awareness)

5D Coordinate Space:
- x: Depth (exploration vs exploitation)
- y: Alternatives (breadth of options considered)
- z: Coherence (alignment of actions)
- t: Time (temporal position)
- n: Complexity (system noise/uncertainty)

---

Quick Start

### Prerequisites
- Python 3.11+
- pip or poetry
- (Optional) GPU for faster embeddings

Installation

bash

# From repository root
cd services/ircp-service

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Or with poetry
poetry install

Development

bash

# Activate environment
source venv/bin/activate

# Start service
python -m src.main

# Server runs at http://localhost:8001

Testing

bash

# Basic health check
curl http://localhost:8001/health

# Get embedding for text
curl -X POST http://localhost:8001/embed \
  -H "Content-Type: application/json" \
  -d '{"text": "Started new Python project for data analysis"}'

# Search for similar events
curl -X POST http://localhost:8001/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "working on machine learning",
    "limit": 5
  }'

---

Architecture

Directory Structure

ircp-service/
├── src/
│   ├── __init__.py
│   ├── main.py              # FastAPI server
│   ├── model.py             # IRCP embedding model
│   └── search.py            # Topological search logic
│
├── requirements.txt         # Python dependencies
├── Dockerfile              # Container definition
└── README.md               # This file

---

Core Concepts

IRCP (Inverse Ring Contextual Propagation)

Traditional embeddings (like Word2Vec, BERT) capture semantic meaning but ignore structural position in a life trajectory. IRCP adds topological awareness.

Example:

Event A: "Started learning Python"
Event B: "Built first Python project"
Event C: "Started learning Java"

Semantic similarity:
- A ↔ C: High (both "learning")
- A ↔ B: Medium

Topological similarity (IRCP):
- A ↔ B: High (sequential, same trajectory branch)
- A ↔ C: Low (divergent paths, different x-coordinate)

5D Coordinate Mapping

python

# Simplified IRCP model
class IRCPModel:
    def embed(self, event_text: str, context: dict) -> np.ndarray:
        # 1. Semantic embedding (768-dim from sentence-transformers)
        semantic = self.base_model.encode(event_text)

        # 2. Topological projection (768 → 5)
        coords_5d = self.topology_head(semantic)

        # 3. Normalize to valid ranges
        x = sigmoid(coords_5d[0])  # 0-1 (depth)
        y = sigmoid(coords_5d[1])  # 0-1 (alternatives)
        z = sigmoid(coords_5d[2])  # 0-1 (coherence)
        t = coords_5d[3]           # continuous (time)
        n = softplus(coords_5d[4]) # 0+ (complexity)

        return np.array([x, y, z, t, n])

---

API Reference

Base URL

http://localhost:8001

Endpoints

Health Check

GET `/health`
- Check service status
- Response: `{ "status": "healthy", "model_loaded": true }`

---

Embedding Generation

POST `/embed`
- Generate IRCP embedding for text
- Request:

json

  {
    "text": "Started new Python project",
    "context": {
      "userId": "user_123",
      "timestamp": "2025-12-21T10:00:00Z"
    }
  }

- Response:

json

  {
    "coords": {
      "x": 0.65,  // Depth
      "y": 0.42,  // Alternatives
      "z": 0.78,  // Coherence
      "t": 0.85,  // Time
      "n": 1.23   // Complexity
    },
    "semantic_embedding": [0.123, -0.456, ...],  // 768-dim vector
    "processing_time_ms": 45
  }

---

Topological Search

POST `/search`
- Find events near a query point in 5D space
- Request:

json

  {
    "query": "machine learning project",
    "limit": 10,
    "filters": {
      "userId": "user_123",
      "regime": "escaping",
      "time_window": {
        "start": "2025-01-01",
        "end": "2025-12-31"
      }
    }
  }

- Response:

json

  {
    "results": [
      {
        "event_id": "evt_789",
        "text": "Built neural network for...",
        "coords": { "x": 0.67, "y": 0.43, "z": 0.80, "t": 0.86, "n": 1.25 },
        "distance_5d": 0.08,
        "semantic_score": 0.92,
        "combined_score": 0.88
      },
      ...
    ],
    "query_coords": { "x": 0.65, "y": 0.42, "z": 0.78, "t": 0.85, "n": 1.23 },
    "total_results": 10
  }

Distance Calculation:

python

# Euclidean distance in 5D space
def distance_5d(coords_a, coords_b):
    return np.linalg.norm(coords_a - coords_b)

# Combined score (semantic + topological)
combined = (0.5 * semantic_similarity) + (0.5 * (1 - distance_5d))

---

Batch Embedding

POST `/embed/batch`
- Generate embeddings for multiple events
- Request:

json

  {
    "events": [
      {"text": "Event 1", "context": {...}},
      {"text": "Event 2", "context": {...}}
    ]
  }

- Response: Array of embedding results

---

Configuration

Environment Variables

bash

# Model settings
MODEL_NAME=sentence-transformers/all-MiniLM-L6-v2  # Base semantic model
IRCP_MODEL_PATH=./models/ircp_trained.pt           # Trained IRCP head (if exists)
DEVICE=cuda  # or 'cpu', 'mps' (Mac M1/M2)

# Server
PORT=8001
HOST=[ip]
WORKERS=4  # Gunicorn workers

# Performance
BATCH_SIZE=32
MAX_SEQ_LENGTH=512

# Database (for caching)
REDIS_URL=redis://localhost:6379
CACHE_TTL=3600  # seconds

---

Model Training (Optional)

The service can use a pre-trained IRCP head or run with the base semantic model only.

Training IRCP Head

python

# Training script (simplified)
from src.model import IRCPModel

# Load training data (life events with ground-truth 5D coords)
train_data = load_trajectory_events()

# Initialize model
model = IRCPModel(base_model='all-MiniLM-L6-v2')

# Train topological projection head
model.train(
    events=train_data,
    epochs=50,
    lr=0.001,
    loss='mse'  # Mean squared error on coords
)

# Save trained head
model.save('models/ircp_trained.pt')

Training Data Format

json

{
  "event_id": "evt_123",
  "text": "Started learning Python",
  "ground_truth_coords": {
    "x": 0.2,  // Low depth (beginner exploration)
    "y": 0.8,  // High alternatives (many options)
    "z": 0.5,  // Medium coherence
    "t": 0.1,  // Early in trajectory
    "n": 1.5   // Moderate complexity
  }
}

---

Performance

Benchmarks

Embedding generation: ~10-50ms per event (CPU), ~5-15ms (GPU)
Batch processing: ~500 events/sec (batch size 32, GPU)
Search latency: ~20-100ms for 10k event corpus
Memory usage: ~500MB (model loaded)

Optimization Tips

1. Use GPU for 3-5x speedup
2. Enable Redis caching for repeated queries
3. Batch requests when possible
4. Precompute embeddings for static event history

---

Docker Deployment

Build Image

bash

docker build -t trajectoryos-ircp .

Run Container

bash

docker run -p 8001:8001 \
  -e DEVICE=cpu \
  -e MODEL_NAME=sentence-transformers/all-MiniLM-L6-v2 \
  trajectoryos-ircp

Docker Compose (with Trajectory Core)

yaml

version: '3.8'
services:
  trajectory-core:
    build: ../trajectory-core
    ports:
      - "3003:3003"
    environment:
      IRCP_SERVICE_URL: http://ircp-service:8001

  ircp-service:
    build: .
    ports:
      - "8001:8001"
    environment:
      DEVICE: cuda
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

---

Integration with Trajectory Core

Usage in UnifiedSearchService

typescript

// trajectory-core/src/services/UnifiedSearchService.ts

async function searchEvents(query: string, userId: string) {
  // 1. Get IRCP embedding for query
  const embeddingResponse = await fetch('http://ircp-service:8001/embed', {
    method: 'POST',
    body: JSON.stringify({ text: query, context: { userId } })
  });
  const { coords } = await embeddingResponse.json();

  // 2. Search with 5D coordinates
  const searchResponse = await fetch('http://ircp-service:8001/search', {
    method: 'POST',
    body: JSON.stringify({
      query_coords: coords,
      limit: 20,
      filters: { userId }
    })
  });

  const { results } = await searchResponse.json();
  return results;
}

---

Troubleshooting

Common Issues

Issue: ModuleNotFoundError for sentence-transformers
- Solution: `pip install sentence-transformers`

Issue: CUDA out of memory
- Solution: Reduce BATCH_SIZE or switch to CPU with `DEVICE=cpu`

Issue: Slow embedding generation
- Solution: Use GPU if available, or try smaller model:

bash

  MODEL_NAME=sentence-transformers/all-MiniLM-L12-v2  # Larger, slower
  MODEL_NAME=sentence-transformers/all-MiniLM-L6-v2   # ✅ Smaller, faster (default)

Issue: Service crashes on startup
- Solution: Check model downloads completed:

bash

  python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"

---

Development

Adding New Features

1. New coordinate dimension:
- Update `model.py` topology head output size
- Modify distance calculation in `search.py`
- Retrain IRCP head

2. Custom distance metric:
- Edit `search.py` `distance_5d()` function
- Options: Manhattan, Mahalanobis, weighted Euclidean

3. Alternative base model:
- Change MODEL_NAME environment variable
- Supported: any sentence-transformers model

---

Research Background

IRCP is inspired by:
- Ring Contextual Propagation (RCP): Circular attention patterns in conversations
- Topological Data Analysis (TDA): Persistent homology for shape analysis
- Manifold Learning: t-SNE, UMAP for high-dimensional projection

Key Innovation: Combining semantic embeddings with learned topological structure to capture life trajectory geometry, not just event content.

---

License

MIT

---

Maintained by: TrajectoryOS Core Team
Last Updated: December 21, 2025
Service Status: ✅ Live and operational
Model Version: IRCP v1.0 (base semantic only, topological head training in progress)

Promotion Decision

Attach run IDs, datasets, metrics, and reproduction commands.

Source Anchor

Comp-Core/backend/cc-trajectory/services/ircp-service/README.md

Detected Structure

Method · Evaluation · Code Anchors · Architecture

Full Public Reader

IRCP Service

Overview

Quick Start

Installation

Development

Testing

Architecture

Directory Structure

Core Concepts

IRCP (Inverse Ring Contextual Propagation)

5D Coordinate Mapping

API Reference

Base URL

Endpoints

Health Check

Embedding Generation

Topological Search

Batch Embedding

Configuration

Environment Variables

Model Training (Optional)

Training IRCP Head

Training Data Format

Performance

Benchmarks

Optimization Tips

Docker Deployment

Build Image

Run Container

Docker Compose (with Trajectory Core)

Integration with Trajectory Core

Usage in UnifiedSearchService

Troubleshooting

Common Issues

Development

Adding New Features

Related Documentation

Research Background

License

Promotion Decision

Source Anchor

Detected Structure