Grand Diomande Research · Full HTML Reader

Python ↔ TypeScript Integration Guide

A single FastAPI server exposing all 6 model subsystems: - Skill Graph (Bayesian inference + message passing) - Alignment Scorer - Gravity/Mass Estimator - Life State Dynamics - Echelon Fusion - Scenario Generator & Evaluator

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

Full Public Reader

Python ↔ TypeScript Integration Guide

✅ What's Been Completed

### 1. Python FastAPI Server (`models/api/server.py`)
Status: ✅ Complete - Ready to run

A single FastAPI server exposing all 6 model subsystems:
- Skill Graph (Bayesian inference + message passing)
- Alignment Scorer
- Gravity/Mass Estimator
- Life State Dynamics
- Echelon Fusion
- Scenario Generator & Evaluator

Location: `/models/api/server.py` (770 lines)

Endpoints:

GET  /health
POST /skill_graph/update_belief
POST /skill_graph/propagate
GET  /skill_graph/beliefs/{user_id}
POST /alignment/score
POST /alignment/simulate_removal
POST /gravity_mass/estimate
POST /gravity_mass/simulate_intervention
POST /dynamics/forecast
POST /dynamics/escape_time
POST /echelon/process_session
POST /scenarios/generate
POST /scenarios/evaluate

To run:

bash

cd models
pip install -r requirements.txt
python -m api.server
# Or: uvicorn api.server:app --reload --port 8001

### 2. TypeScript Python Client (`services/trajectory-core/src/python/`)
Status: ✅ Complete

Type-safe HTTP client for calling Python APIs.

Files:
- `client.ts` - Main HTTP client class
- `types.ts` - TypeScript types matching Python models
- `index.ts` - Exports

Usage:

typescript

import { pythonClient } from '../python';

// Update skill belief
const result = await pythonClient.updateSkillBelief(userId, skillId, evidence);

// Score alignment
const alignment = await pythonClient.scoreAlignment(userId, projects, skillBeliefs);

// Forecast trajectory
const forecast = await pythonClient.forecastTrajectory(userId, state, actionPlan);

### 3. SkillGraphService Integration
Status: ✅ Complete

Updated to use Python Bayesian model instead of simple averaging.

Changes:
- Calls `pythonClient.updateSkillBelief()` for each piece of evidence
- Calls `pythonClient.propagateBeliefUpdate()` to propagate through graph
- Stores Bayesian posterior (mean, std) in database
- Fallback to simple averaging if Python API unavailable

Location: `/services/trajectory-core/src/services/SkillGraphService.ts`

### 4. Database Schema Update
Status: ✅ Complete

Added `SkillBelief` table to store Bayesian posteriors.

prisma

model SkillBelief {
  id          String   @id @default(uuid())
  userId      String
  skillId     String
  level       Float    // Posterior mean (0-10)
  uncertainty Float    // Posterior std deviation
  lastUpdated DateTime @default(now())

  @@unique([userId, skillId])
  @@index([userId])
}

Migration: Already applied (`20251127150632_add_skill_belief_table`)

---

### 5. LifeStateService
Status: ✅ Complete

Enhanced service to manage life state and call Python dynamics models.

New Methods Added:
- `forecastTrajectory()` - Forecast trajectory using Python dynamics
- `estimateEscapeTime()` - Estimate escape time with Monte Carlo sampling
- `computePhysicsWithPython()` - Compute A, G, M using Python models
- `recomputeStateWithPython()` - Recompute and persist state using Python

Features:
- Calls Python alignment, gravity/mass, and dynamics models
- Fallback to simple estimates if Python unavailable
- Persists computed states to database
- Error handling with graceful degradation

Location: `/services/trajectory-core/src/services/LifeStateService.ts` (558 lines)

### 6. PlannerService
Status: ✅ Complete

Enhanced service for scenario generation and planning with Python integration.

New Methods Added:
- `generateScenarios()` - Generate multiple scenarios using Python
- `evaluateScenarios()` - Evaluate scenarios using Python dynamics
- `generateAndEvaluate()` - Generate and evaluate in one call, ranked by outcome
- `generateAndSaveBestPlan()` - Generate, evaluate, and save best plan

Features:
- Calls Python scenario generator and evaluator
- Fallback to simple baseline scenarios if Python unavailable
- Ranks scenarios by mean η and escape probability
- Saves plans to database with action steps

Location: `/services/trajectory-core/src/services/PlannerService.ts` (578 lines)

### 7. API Endpoints
Status: ✅ Complete

Added REST endpoints to `trajectory-core` for Python-integrated features.

New Endpoints:

// Scenario Generation & Planning
POST /api/planner/:userId/scenarios/generate              # Generate scenarios
POST /api/planner/:userId/scenarios/evaluate              # Evaluate scenarios
POST /api/planner/:userId/scenarios/generate-and-evaluate # Generate + evaluate
POST /api/planner/:userId/scenarios/generate-and-save     # Generate + save best

// Trajectory Forecasting
POST /api/state/:userId/forecast      # Forecast trajectory
POST /api/state/:userId/escape-time   # Estimate escape time
POST /api/state/:userId/recompute     # Recompute state with Python

// Existing Endpoints (already implemented)
POST /api/skills/evidence             # Ingest skill evidence
GET  /api/skills/user/:userId         # Get all skill beliefs
GET  /api/state/:userId               # Get latest state
GET  /api/state/:userId/history       # Get state history

File: `/services/trajectory-core/src/routes/planner.ts` (enhanced with 7 new endpoints)

### 8. Startup Scripts
Status: ✅ Complete

Development script to easily start all services.

Script: `scripts/dev.sh`

Features:
- Automatically starts Python API server and trajectory-core
- Checks if ports 8001 and 3003 are available
- Creates Python venv and installs dependencies if needed
- Runs Prisma migrations
- Waits for services to be ready before showing success message
- Captures logs to `logs/python-api.log` and `logs/trajectory-core.log`
- Graceful shutdown with Ctrl+C (cleans up all processes)

Usage:

bash

# Make executable (first time only)
chmod +x scripts/dev.sh

# Start all services
./scripts/dev.sh

Output:

========================================
  TrajectoryOS Development Environment
========================================

Starting Python API server...
Python API server is ready at http://localhost:8001

Starting Trajectory Core service...
Trajectory Core is ready at http://localhost:3003

========================================
  All services are running!
========================================

Services:
  ✓ Python API:       http://localhost:8001
  ✓ Trajectory Core:  http://localhost:3003

Logs:
  Python API:       logs/python-api.log
  Trajectory Core:  logs/trajectory-core.log

Press Ctrl+C to stop all services

### 9. Testing
Status: ⚠️ Pending

End-to-end testing is next priority.

Recommended Test Flow:
1. Start services with `./scripts/dev.sh`
2. Test Python API health: `curl http://localhost:8001/health`
3. Test trajectory-core health: `curl http://localhost:3003/health`
4. Create test user
5. Submit skill evidence via `/api/skills/evidence`
6. Verify Bayesian update in database
7. Generate scenarios via `/api/planner/:userId/scenarios/generate-and-evaluate`
8. Forecast trajectory via `/api/state/:userId/forecast`
9. Check escape time estimation via `/api/state/:userId/escape-time`

Manual Testing Script: See "Quick Test" section below

---

🚀 Quick Start

Option 1: Use Development Script (Recommended)

bash

# Make script executable (first time only)
chmod +x scripts/dev.sh

# Start all services
./scripts/dev.sh

This will:
- Start Python API server on port 8001
- Start Trajectory Core on port 3003
- Set up logs in `logs/` directory
- Wait for both services to be ready

Option 2: Manual Startup

Terminal 1 - Python API:

bash

cd models
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m api.server

Terminal 2 - Trajectory Core:

bash

cd services/trajectory-core
npm install
npx prisma migrate dev
npx prisma generate
npm run dev

Quick Test

Once services are running, test the integration:

bash

# Test health endpoints
curl http://localhost:8001/health
curl http://localhost:3003/health

# Submit skill evidence (with Bayesian update)
curl -X POST http://localhost:3003/api/skills/evidence \
  -H "Content-Type: application/json" \
  -H "x-user-id: test-user-123" \
  -d '{
    "userId": "test-user-123",
    "evidence": [{
      "skillId": "ml-systems",
      "levelEstimate": 8.5,
      "confidence": 0.9,
      "utilization": 0.7,
      "source": "interview",
      "rawText": "Built production ML pipeline with real-time inference"
    }]
  }'

# Get skill beliefs
curl http://localhost:3003/api/skills/user/test-user-123 \
  -H "x-user-id: test-user-123"

# Generate and evaluate scenarios
curl -X POST http://localhost:3003/api/planner/test-user-123/scenarios/generate-and-evaluate \
  -H "Content-Type: application/json" \
  -H "x-user-id: test-user-123" \
  -d '{
    "goal": "Become a senior ML engineer",
    "nScenarios": 5,
    "horizon": 180
  }'

What Happens:
1. Evidence is stored in SQLite
2. Python Bayesian model updates skill belief
3. Belief propagates through skill graph
4. Updated belief (mean + uncertainty) stored in DB
5. Scenarios generated using Python scenario generator
6. Each scenario evaluated using Python dynamics model
7. Results ranked by escape index and probability

---

📊 Current System Diagram

┌─────────────────────────────────────────────────┐
│             TypeScript Services                 │
│    (trajectory-core on :3003)                   │
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │  SkillGraphService  ✅                   │   │
│  │  - ingestEvidence()                       │   │
│  │  - getUserSkills()                        │   │
│  └────────────┬─────────────────────────────┘   │
│               │                                  │
│  ┌────────────▼─────────────────────────────┐   │
│  │  Python Client                            │   │
│  │  - updateSkillBelief()   ✅              │   │
│  │  - propagateBeliefUpdate() ✅            │   │
│  │  - scoreAlignment()                       │   │
│  │  - estimateGravityMass()                  │   │
│  │  - forecastTrajectory()                   │   │
│  │  - generateScenarios()                    │   │
│  └────────────┬─────────────────────────────┘   │
└───────────────┼──────────────────────────────────┘
                │  HTTP
                ▼
┌─────────────────────────────────────────────────┐
│           Python FastAPI Server                 │
│              (on :8001)  ✅                     │
│                                                  │
│  ┌──────────────────┐  ┌───────────────────┐   │
│  │ Skill Graph      │  │ Alignment         │   │
│  │ BayesianModel    │  │ ProjectEmbedder   │   │
│  │ MessagePasser    │  │ AlignmentScorer   │   │
│  └──────────────────┘  └───────────────────┘   │
│                                                  │
│  ┌──────────────────┐  ┌───────────────────┐   │
│  │ Gravity/Mass     │  │ Life State        │   │
│  │ GravityEstimator │  │ LifeStateDynamics │   │
│  │ MassEstimator    │  │ TransitionModel   │   │
│  └──────────────────┘  └───────────────────┘   │
│                                                  │
│  ┌──────────────────┐  ┌───────────────────┐   │
│  │ Echelon Fusion   │  │ Scenarios         │   │
│  │ EchelonFusion    │  │ Generator         │   │
│  │ Model            │  │ Evaluator         │   │
│  └──────────────────┘  └───────────────────┘   │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│              Database (SQLite)                   │
│                                                  │
│  SkillEvidence  ✅                              │
│  SkillBelief    ✅  (newly added)               │
│  LifeState                                       │
│  Project                                         │
│  Constraint                                      │
│  ActionPlan                                      │
└─────────────────────────────────────────────────┘

---

📝 Next Steps (Priority Order)

This Week

1. Create LifeStateService (2-3 hours)
- Copy pattern from SkillGraphService
- Add methods for forecast, escape time
- ~200 lines

2. Create PlannerService (2-3 hours)
- Add scenario generation methods
- Store plans in DB
- ~150 lines

3. Add API Routes (2 hours)
- Create `/routes` folder
- Add skill, state, planning endpoints
- Wire up to Express app

4. Create Startup Script (30 min)
- `scripts/dev.sh` to start both servers
- Add to package.json

5. End-to-End Test (2 hours)
- Test full flow: evidence → Bayesian → forecast → scenarios
- Document any issues

Next Week

6. Build Frontend API Client
- React Query hooks
- API methods matching backend

7. Build Dashboard Pages
- Skills page (show beliefs with uncertainty)
- Physics page (T, A, G, M, η)
- Planner page (scenario comparison)

8. Simple Interview Flow
- Text input form
- Submit skill evidence
- See Bayesian update in real-time

---

🐛 Known Issues / TODOs

1. No error boundary in Python client
- Need better error handling and retry logic
- Add circuit breaker pattern

2. No caching
- Expensive operations (embeddings, forecasts) not cached
- Add Redis layer later

3. No auth between services
- TypeScript → Python calls have no authentication
- Add API keys for production

4. Skill graph structure not persisted
- Skill transfer edges need to be stored/loaded
- Currently Python server starts with empty graph

5. No user skill graph initialization
- Need to seed common skills and transfers
- Add migration or seed script

---

💡 Tips for Continuing Development

When adding a new Python model method:

1. Add method to appropriate model class (e.g., `BayesianSkillModel`)
2. Add endpoint in `models/api/server.py`
3. Add method to `PythonModelsClient` in `client.ts`
4. Add types to `types.ts` if needed
5. Use in service layer

When adding a new TypeScript service:

1. Create service class in `/services`
2. Inject `PrismaClient` and `pythonClient`
3. Add public methods that:
- Fetch from DB
- Call Python if needed
- Store results
- Return to caller
4. Add API routes that call service
5. Export from `/services/index.ts`

Testing locally:

1. Start Python server: `cd models && python -m api.server`
2. Start trajectory-core: `cd services/trajectory-core && npm run dev`
3. Test with curl or Postman
4. Check logs in both terminals

---

📚 Additional Resources

Python Models README: `/models/README.md` - Comprehensive model documentation
Architecture Docs: `/docs/architecture/` - System design
Project Status: `/PROJECT_STATUS.md` - Overall project state
API Server Code: `/models/api/server.py` - Reference for all endpoints

---

Current Integration Status: 40

✅ Python models (100
✅ Python API server (100
✅ TypeScript client (100
✅ SkillGraphService (100
✅ LifeStateService (100
✅ PlannerService (100
✅ API endpoints (100
✅ Startup scripts (100
⚠️ Testing (Manual tests ready, automated tests pending)

Remaining Work:
- End-to-end automated tests
- Docker Compose setup (optional for development)
- Production deployment configuration

Time to MVP: Ready for testing! All core integration complete.

---

Last Updated: November 28, 2025

Promotion Decision

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

Source Anchor

Comp-Core/backend/cc-trajectory/docs/guides/INTEGRATION_GUIDE.md

Detected Structure

Method · Evaluation · Code Anchors · Architecture