CC-TPO - Computational Choreography Temporal Positional Optimization

CC-TPO - Computational Choreography Temporal Positional Optimization

A comprehensive framework for semantic search and conversation analysis using Inverse Ring Contextual Propagation (IRCP) and Dynamic Liquid Motion (DLM) coordinates.

> 📚 Documentation: All documentation has been organized in [`docs/`](docs/). See [`docs/README.md`](docs/README.md) for the full index.

📖 Quick Links

• Getting Started: [`docs/guides/GETTING_STARTED.md`](docs/guides/GETTING_STARTED.md) or [`START_HERE.md`](START_HERE.md)
• Architecture: [`docs/architecture/`](docs/architecture/)
• Main CLI: `python scripts/cc_ai.py --help`
• Latest Progress: [`docs/progress/WEEK_3_PROGRESS_SUMMARY.md`](docs/progress/WEEK_3_PROGRESS_SUMMARY.md)

🚀 Quick Start

Applications

# Liquid Chat UI (Next.js + OpenAI GPT-4o)
cd apps/liquid-chat-ui
npm install && npm run dev

# IRCP Search App (Next.js + GPT-4o-mini)
cd apps/ircp-search-app
npm install && npm run dev

# Liquid Chat Backend (FastAPI + Custom IRCP)
cd apps/liquid-chat-backend
python main.py

Training

# Train IRCP model
python scripts/training/train_ircp_full_dataset.py

# Test trained model
python scripts/testing/test_trained_ircp_model.py

---

📂 Project Structure

cc-tpo/
├── apps/              # Applications (3 apps)
├── services/          # Backend services (9 search APIs)
├── packages/          # Core Python packages (ircp, tpo, rcp, ctsc, dlm)
├── training/          # ML training artifacts and models
├── data/              # Databases and datasets
├── docs/              # Documentation (42+ files)
├── scripts/           # Utility scripts (training, testing, demo, setup)
├── evaluation_results/# Evaluation outputs
├── integration/       # Integration tests
├── logs/              # Log files
└── [config files]     # Root-level configuration

See [project_structure_final.md](.gemini/antigravity/brain/2cabc4fb-d307-4040-a5fa-bf170f888e05/project_structure_final.md) for complete structure.

---

🎯 Key Components

### IRCP (Inverse Ring Contextual Propagation)
- Location: `packages/ircp/`
- Purpose: Semantic embedding and ring topology-based conversation analysis
- Model: Custom SentenceTransformer (384-dim embeddings)
- Training Data: 277 conversations

### DLM Coordinates (x, y, z, t, n)
- Location: `packages/tpo/`
- x: Hierarchy depth
- y: Sibling position
- z: Semantic homogeneity
- t: Temporal position
- n: Structural complexity

### Applications
- liquid-chat-ui: Chat interface with liquid ring visualization
- ircp-search-app: Semantic search with ring topology context
- liquid-chat-backend: FastAPI backend with IRCP processing

---

📖 Documentation

• IRCP Theory: `docs/ircp/IRCP_THEOREM_AND_PROOF.md`
• Architecture: `docs/architecture/`
• Research Paper: `docs/research/` (11 chapters)
• API Docs: See individual app READMEs

Quick Links:
- [Apps README](apps/README.md)
- [Packages README](packages/README.md)
- [Scripts README](scripts/README.md)
- [Training README](training/README.md)
- [Data README](data/README.md)
- [Docs README](docs/README.md)

---

🛠️ Development

### Prerequisites
- Python 3.8+
- Node.js 18+
- SQLite 3

Install Dependencies

Python:

pip install -r requirements-ircp.txt

Node.js (per app):

cd apps/liquid-chat-ui && npm install
cd apps/ircp-search-app && npm install

Environment Setup

Create `.env` files in each app directory:

apps/liquid-chat-ui/.env:

OPENAI_API_KEY=your_key_here
DATABASE_URL="file:../../data/databases/liquid-chat.db"

apps/ircp-search-app/.env.local:

OPENAI_API_KEY=your_key_here

---

🧪 Testing

# Test IRCP implementation
python scripts/testing/test_complete_ircp_implementation.py

# Test trained model
python scripts/testing/test_trained_ircp_model.py

# Run demos
python scripts/demo/create_search_demo.py
python scripts/demo/real_world_examples.py

---

📊 Model Backend Reference

IRCP Model Location: `training/ircp/full_dataset/best_model.pt`

---

🗃️ Databases

Location: `data/databases/`

• `conversations_fixed.db` - Conversation history (277 conversations)
• `claude_full_embeddings_dlm_fixed.db` - IRCP embeddings with DLM coordinates

---

📦 Packages

Core packages in `packages/`:

• ircp - Inverse Ring Contextual Propagation
• tpo - Temporal Positional Optimization (DLM coordinates)
• rcp - Ring Contextual Propagation
• ctsc - Computational Topology Search Coordinates
• dlm - Dynamic Liquid Motion

---

🎓 Research

Academic research paper in `docs/research/`:
- Introduction & Mathematical Framework
- Algorithm Implementation
- Experimental Setup & Results
- Applications & Conclusions

---

🤝 Contributing

1. Follow the organized structure (apps, services, packages, etc.)
2. Update relevant README files
3. Add tests for new features
4. Document in `docs/` as appropriate

---

📝 License

[Add your license here]

---

🙏 Acknowledgments

• Original IRCP research and implementation
• 277-conversation training dataset from Claude AI
• OpenAI GPT models for chat interfaces

---

📧 Contact

[Add contact information]

---

Project Status: Production-ready, fully reorganized structure (4/4 phases complete)
Last Updated: December 2025