Alters Lab

Your future is not a single path. It's a branching tree of possibilities.

Alters Lab is a personal future path simulation and calibration system. It helps you explore structurally different life branches, engage in dialogue with hypothetical versions of yourself, and calibrate which paths actually align with your values through your own weekly reviews, behavior signals, and explicitly recorded real-world evidence.

Who is this for? People facing major life decisions (career change, relocation, relationship) who want to think it through rigorously — not with spreadsheets or pro/con lists, but by simulating entire versions of themselves and checking predictions against reality over time.

Boundary: Alters Lab is a reflection and calibration tool. Optional external reference material may be used as background context only. It is not an individual destiny predictor, clinical tool, financial advisor, or source of exact personal probabilities.

Quick Start

git clone https://github.com/Igzela/alters-lab.git
cd alters-lab
docker compose up -d
# Open http://localhost:18790

Load sample data to explore immediately:

docker compose exec alters-lab alters-lab load-sample

Manual Install

Backend:

git clone https://github.com/Igzela/alters-lab.git
cd alters-lab
python3 -m venv .venv && source .venv/bin/activate
pip install -e "apps/api[dev]"

Frontend:

cd apps/web
npm install

Run (development mode):

# Terminal 1 — Backend
PYTHONPATH=apps/api/src uvicorn alters_lab.main:app --port 18790

# Terminal 2 — Frontend (hot-reload)
cd apps/web && npm run dev

Frontend at http://localhost:5173, API at http://localhost:18790.

Run (production mode):

source .venv/bin/activate
alters-lab start
# Opens http://localhost:18790

API Overview

The API exposes 57+ endpoints across these key areas:

Area	Endpoints	Description
Snapshot	POST /snapshot-intake/...	Capture current state: constraints, directions, values
Branches	GET/POST /branches/...	Discover and manage 3-4 structural life branches
Alters	GET /alters/...	List and manage generated alter personas
Dialogue	POST /alter-dialogue/{alter_id}/...	Chat with an alter about their path
Weekly Review	POST /weekly-review/...	6-step structured weekly calibration flow
Calibration	POST /calibration-conversation/...	LLM-guided calibration via natural conversation
Behavior Metrics	GET/POST /behavior-metrics/...	Weekly structured behavior indicators
Forecast	GET /branch-forecast/...	Personal evidence + optional reference context + adapter forecasts
Snapshots	GET /forecast-snapshots/...	Locked, immutable forecast records
Evidence	POST /external-evidence/...	Real-world observations that inform forecasts
Evaluation	GET /forecast-evaluation/...	Hit/miss tracking per evidence source
Scorecard	GET /calibration-scorecard/...	Aggregate accuracy with per-source hit rates
Provider	POST /provider-config/...	Configure LLM provider (OpenAI-compatible)
Reference Context	GET /public-prior/...	Optional external reference layer for directional context

Full API docs at http://localhost:18790/docs (Swagger UI).

Architecture

┌─────────────────────────────────────────────────────────┐
│  Frontend  React 18 + TypeScript + Tailwind v4          │
│  22 pages: Dashboard, Weekly Review, Dialogue, etc.     │
├─────────────────────────────────────────────────────────┤
│  Backend  Python 3.11+ + FastAPI + Pydantic v2          │
│  57 API routers, 70 service modules                     │
│  Personal calibration + optional reference context       │
├─────────────────────────────────────────────────────────┤
│  Storage  YAML + JSON files (no database)               │
│  alters/current/   Active user data                     │
│  alters/product/   Reviews, forecasts, evidence         │
│  alters/calibration/  Rubric, scores, state             │
└─────────────────────────────────────────────────────────┘

Pipeline:
  Snapshot → Branch Discovery → Alter Generation → Dialogue → Calibration
      ↓                                                          ↓
      └──────────── Reality Score ←──── Weekly Reviews ←──────────┘

Tech Stack

Layer	Technology
Backend	Python 3.11+, FastAPI, Pydantic v2, PyYAML, uvicorn
Frontend	React 18, TypeScript, Vite, Tailwind CSS v4
Data	TanStack Query, Recharts, Phosphor Icons
i18n	English + Chinese
Storage	YAML + JSON files
Deployment	Docker, Debian .deb
Tests	pytest (backend), vitest (frontend)

Development

Run all tests:

# Backend (1980 tests)
PYTHONPATH=apps/api/src python3 -m pytest apps/api/tests/ -q

# Frontend (90 tests)
cd apps/web && npm run test

# Frontend build check
cd apps/web && npm run build

Generate TypeScript types from OpenAPI:

cd apps/web && npm run generate:types

CLI commands:

alters-lab start        # Start local server
alters-lab stop         # Stop server
alters-lab status       # Show server status
alters-lab doctor       # Run health checks
alters-lab backup       # Create a data backup
alters-lab load-sample  # Load sample data for new users

What Makes It Different

	Traditional Tools	Alters Lab
Decision model	Pro/con lists, spreadsheets	Simulated alternate selves you can dialogue with
Prediction	"You'll be happy if you choose X"	Directional forecasts with explicit uncertainty
Feedback loop	None — you decide and forget	Weekly calibration tracks if reality matches intent
Evidence	Your gut feeling	Your weekly reviews, behavior metrics, and real-world observations
Life score	Single number (misleading)	Multi-dimensional, never reduced to one score
Data	Cloud, accounts, telemetry	Local YAML/JSON files, fully yours

Key Concepts

• Personal evidence — Weekly reviews, behavior metrics, predictor profile, and explicit reality scores
• Optional external reference context — Background material used only as a directional reference when available and appropriate
• Personal Prior Adapter — Combines personal evidence, optional external references, and real-world observations into per-domain forecasts
• Calibration — 4-dimension rubric: execution discipline, exploration freedom, life state match, energy level
• No life_score — The system never produces a single number for your life quality
• No exact probability — Directional forecasts only, with explicit uncertainty unless a separately approved model artifact supports a bounded output

Documentation

• User Guide — Workflow walkthrough and reference
• Provider Setup — Configure LLM providers
• Architecture — Technical architecture
• Data Model — Schema definitions
• Product Spec — System design and concepts

Contributing

Issues and PRs welcome. See AGENTS.md for development setup and coding conventions.

If you find this useful, a ⭐ helps others discover it.

License

MIT — Use it, modify it, distribute it. Just keep the license notice.