Packages

Packages

This directory contains all core Python packages and libraries for the CC-TPO project.

Packages Overview

packages/
├── ircp/       # Inverse Ring Contextual Propagation
├── tpo/        # Temporal Positional Optimization
├── rcp/        # Ring Contextual Propagation
├── ctsc/       # Computational Topology Search Coordinates
└── dlm/        # Dynamic Liquid Motion

---

IRCP (Inverse Ring Contextual Propagation)

Location: `packages/ircp/`

### Description
Core implementation of the IRCP algorithm for semantic embedding and conversation analysis using ring topology.

### Key Components
- Models: Custom SentenceTransformer implementation
- Algorithms: Ring topology algorithms
- Utilities: Embedding generation and similarity search

Usage

import sys
from pathlib import Path

# Add to path
sys.path.append(str(Path.cwd() / "packages" / "ircp"))

from ircp.models.sentence_transformer_icp import SentenceTransformerICP

# Initialize model
config = {
    "model_name": "sentence-transformers/all-MiniLM-L6-v2",
    "embedding_dim": 384,
    "coordinate_dim": 4,
    "hidden_dim": 512,
    "dropout": 0.1
}
model = SentenceTransformerICP(config)

### Used By
- `apps/liquid-chat-backend/` - Main embedding service
- `services/search-api/` - All search services
- Training scripts

---

TPO (Temporal Positional Optimization)

Location: `packages/tpo/`

### Description
Temporal and positional optimization framework for DLM (Dynamic Liquid Motion) coordinates.

### Key Components
- DLM Coordinates: Dynamic coordinate system (x, y, z, t, n)
- Calculators: Coordinate calculation algorithms
- Optimizers: Position optimization

### Coordinate System
- x: Hierarchy depth (conversation tree depth)
- y: Sibling position (lateral position in tree)
- z: Semantic homogeneity (0-1, topic coherence)
- t: Temporal position (normalized timestamp)
- n: Structural complexity (paragraph count/complexity)

Usage

from tpo.core.dlm_coordinates import DLMCalculator, DLMCoordinates

calculator = DLMCalculator()
coordinates = calculator.calculate_coordinates(
    message_id,
    messages_dict,
    parent_child_map
)

### Used By
- `apps/liquid-chat-backend/` - Coordinate calculation
- IRCP training pipeline

---

RCP (Ring Contextual Propagation)

Location: `packages/rcp/`

### Description
Ring-based contextual propagation framework for conversation flow analysis.

### Key Features
- Ring topology construction
- Context propagation algorithms
- Message relationship mapping

---

CTSC (Computational Topology Search Coordinates)

Location: `packages/ctsc/`

### Description
Computational topology and search coordinate algorithms.

### Key Features
- Topological search algorithms
- Coordinate space transformations
- Distance metrics

---

DLM (Dynamic Liquid Motion)

Location: `packages/dlm/`

### Description
Dynamic liquid motion visualization and coordinate system.

### Key Features
- Liquid motion algorithms
- Visualization helpers
- Animation frameworks

---

Importing Packages

From Applications

In Python files within `/apps/` or `/services/`:

import sys
from pathlib import Path

# Calculate path to project root
PROJECT_ROOT = Path(__file__).parent.parent.parent  # Adjust based on nesting

# Add package paths
sys.path.append(str(PROJECT_ROOT / "packages" / "ircp"))
sys.path.append(str(PROJECT_ROOT / "packages" / "tpo"))

# Import
from ircp.models.sentence_transformer_icp import SentenceTransformerICP
from tpo.core.dlm_coordinates import DLMCalculator

Path Configuration

Directory Structure:

cc-tpo/
├── apps/
│   └── liquid-chat-backend/
│       └── main.py              # Needs: ../../../packages/ircp
├── services/
│   └── search-api/
│       └── search_api.py        # Needs: ../../packages/ircp
└── packages/
    ├── ircp/
    └── tpo/

---

Development

Adding New Packages

1. Create package directory under `packages/`
2. Add `__init__.py` to make it a Python package
3. Update relevant `sys.path` entries in applications
4. Document in this README

Package Structure

Recommended structure for each package:

packages/your_package/
├── __init__.py
├── models/
│   └── __init__.py
├── core/
│   └── __init__.py
├── utils/
│   └── __init__.py
└── tests/
    └── __init__.py

---

Testing

Running Package Tests

# Test IRCP
cd packages/ircp
python -m pytest tests/

# Test TPO
cd packages/tpo
python -m pytest tests/

Integration Tests

Integration tests that use multiple packages should be placed in the top-level `integration/` directory.

---

Dependencies

### IRCP Dependencies
- PyTorch
- sentence-transformers
- numpy
- transformers

### TPO Dependencies
- numpy
- scipy (for optimization)

Installing All Dependencies

pip install -r requirements.txt

Or for development:

pip install -r requirements-dev.txt

---

Migration Notes

> [!IMPORTANT]
> Post-Phase 4 Migration
>
> All packages have been moved from project root to `packages/` directory.
> If you encounter import errors, ensure your `sys.path` is correctly configured.

Before (Phase 1-3):

sys.path.append(str(PROJECT_ROOT / "ircp"))
from ircp.models.sentence_transformer_icp import SentenceTransformerICP

After (Phase 4):

sys.path.append(str(PROJECT_ROOT / "packages" / "ircp"))
from ircp.models.sentence_transformer_icp import SentenceTransformerICP

---

Documentation

• IRCP Documentation: `../docs/ircp/`
• Architecture: `../docs/architecture/`
• Research Papers: `../docs/research/`

---

Contributing

When modifying packages:

1. Maintain backward compatibility when possible
2. Update tests for any changes
3. Document new features or breaking changes
4. Update this README with new package information