TrajectoryOS Quick Start Guide

TrajectoryOS Quick Start Guide

What is TrajectoryOS?

TrajectoryOS is a life physics engine that models your career trajectory using computational physics. It treats your life as a dynamical system with:

• T (Thrust): Your skill capacity × utilization × alignment
• A (Alignment): How well your projects match your skills
• G (Gravity): Constraints pulling you back
• M (Mass): Inertia from existing projects/dependencies
• η (Escape Index): T×A / G×M - your trajectory toward goals

Architecture

┌─────────────────────────────────────────────┐
│         TypeScript Services                 │
│      (trajectory-core on :3003)             │
│                                              │
│  SkillGraphService → PlannerService          │
│  LifeStateService                            │
│         ↓                                    │
│    Python Client (HTTP)                      │
└─────────────┬───────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────┐
│        Python FastAPI Server                │
│             (on :8001)                      │
│                                              │
│  • Bayesian Skill Graph                     │
│  • Alignment Scorer                         │
│  • Gravity/Mass Estimator                   │
│  • Life State Dynamics                      │
│  • Scenario Generator                       │
└─────────────────────────────────────────────┘

Prerequisites

• Python 3.9+ with pip
• Node.js 18+ with npm
• SQLite (included with Python)

Installation & Startup

Option 1: Quick Start (Recommended)

# Make startup script executable
chmod +x scripts/dev.sh

# Start all services
./scripts/dev.sh

That's it! Both services will start and wait for each other to be ready.

Option 2: Manual Startup

Terminal 1 - Python API Server:

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

Terminal 2 - Trajectory Core:

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

Testing the Integration

Once services are running, try these examples:

1. Health Check

curl http://localhost:8001/health  # Python API
curl http://localhost:3003/health  # Trajectory Core

2. Submit Skill Evidence

This will trigger the Bayesian skill inference model:

curl -X POST http://localhost:3003/api/skills/evidence \
  -H "Content-Type: application/json" \
  -H "x-user-id: user-123" \
  -d '{
    "userId": "user-123",
    "evidence": [{
      "skillId": "ml-engineering",
      "levelEstimate": 8.0,
      "confidence": 0.85,
      "utilization": 0.7,
      "source": "interview",
      "rawText": "Built production ML pipeline handling 1M requests/day"
    }]
  }'

What happens:
1. Evidence stored in SQLite
2. Python Bayesian model updates belief (posterior mean & std)
3. Belief propagates through skill graph
4. Updated beliefs returned with uncertainty estimates

3. Get Skill Beliefs

curl http://localhost:3003/api/skills/user/user-123 \
  -H "x-user-id: user-123"

Returns all skill beliefs with Bayesian posteriors (mean, uncertainty).

4. Generate & Evaluate Scenarios

Generate multiple action plans and rank them by projected outcome:

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

What happens:
1. Python scenario generator creates 10 different action plans
2. Each scenario is simulated using life state dynamics model
3. Scenarios are evaluated by final escape index (η) and escape probability
4. Results ranked by best outcome

5. Forecast Trajectory

See how your trajectory evolves over time with a given action plan:

curl -X POST http://localhost:3003/api/state/user-123/forecast \
  -H "Content-Type: application/json" \
  -H "x-user-id: user-123" \
  -d '{
    "actionPlan": [
      [{"action_type": "skill_practice", "skill_id": "ml-engineering", "intensity": 0.8, "duration_hours": 6}],
      [{"action_type": "project_work", "project_id": "main-project", "intensity": 0.7, "duration_hours": 8}]
    ],
    "horizon": 90
  }'

Returns day-by-day forecast of T, A, G, M, η.

6. Estimate Escape Time

When will you reach your goal?

curl -X POST http://localhost:3003/api/state/user-123/escape-time \
  -H "Content-Type: application/json" \
  -H "x-user-id: user-123" \
  -d '{
    "actionPlan": [
      [{"action_type": "skill_practice", "skill_id": "ml-engineering", "intensity": 0.8, "duration_hours": 6}]
    ],
    "nSamples": 100
  }'

Returns mean escape time, standard deviation, and probability of escape within horizon.

Key Endpoints

### Skills
- `POST /api/skills/evidence` - Submit skill evidence (triggers Bayesian update)
- `GET /api/skills/user/:userId` - Get all skill beliefs

### Life State
- `GET /api/state/:userId` - Get latest life state (T, A, G, M, η)
- `GET /api/state/:userId/history` - Get state history
- `POST /api/state/:userId/forecast` - Forecast trajectory
- `POST /api/state/:userId/escape-time` - Estimate escape time
- `POST /api/state/:userId/recompute` - Recompute state using Python models

### 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` - Both in one call
- `POST /api/planner/:userId/scenarios/generate-and-save` - Generate and save best plan

Logs

When using `scripts/dev.sh`, logs are written to:
- `logs/python-api.log` - Python FastAPI server logs
- `logs/trajectory-core.log` - Trajectory Core service logs

Next Steps

1. Test the integration - Use the curl examples above
2. Read the models - Check `/models/README.md` for model documentation
3. Explore the architecture - See `/docs/architecture/` for system design
4. Build the frontend - See `/apps/web-dashboard/` for the Next.js dashboard

Troubleshooting

Port already in use:

# Find process using port 8001 or 3003
lsof -ti:8001 -sTCP:LISTEN
lsof -ti:3003 -sTCP:LISTEN

# Kill the process
kill -9 <PID>

Python API not starting:
- Check `logs/python-api.log`
- Ensure Python 3.9+ is installed
- Verify all dependencies installed: `pip list`

Trajectory Core not starting:
- Check `logs/trajectory-core.log`
- Run migrations: `cd services/trajectory-core && npx prisma migrate dev`
- Regenerate Prisma client: `npx prisma generate`

Services can't communicate:
- Ensure both are running on expected ports (8001, 3003)
- Check firewall settings
- Verify no proxy interfering with localhost

More Documentation

• Integration Guide: [INTEGRATION_GUIDE.md](./INTEGRATION_GUIDE.md) - Complete Python-TypeScript integration details
• Models Documentation: [models/README.md](./models/README.md) - Deep dive into the 6 Python models
• Architecture: [docs/architecture/](./docs/architecture/) - System design documents
• Project Status: [PROJECT_STATUS.md](./PROJECT_STATUS.md) - Overall project state

---

Status: Core integration complete (95