Turn "I like this" into one brief the homeowner and the designer both approve.

A two-sided agent workspace for Singapore homeowners and interior-design SMEs.
References, notes and practical constraints become one versioned living-room brief. AI suggestions stay proposals, conflicts stay visible, and approval is explicit.

Live demo · Quick start · How it works · Agent loop · Safety & evaluation · Deploy · Write-up (PDF) · 简体中文

A reference image does not say whether someone likes its oak, its lighting, its layout or the whole room. The same word ("warm", "hotel-like") means different things to a homeowner and a designer, and the misunderstanding usually surfaces at the first concept as another revision. AlignSpace focuses on agreement, not image generation: it keeps one explicit shared state, asks the question that removes the most uncertainty, and releases the brief only when both people approve the same version.

_{Two browser sessions, synthetic data, offline note rules, sped up about 3×. Full captioned recording: python scripts/e2e_golden_path.py <url> video.}

Observe → estimate → decide → check → stop. Observe. Answers, notes, saved homes and constraints update one versioned Project Design State. Stale writes are rejected with HTTP 409. Estimate. Each decision has an advisory Dirichlet belief. Evidence is weighted by quality (explicitness, reliability, dispersion). A human confirmation outweighs any machine signal, repeated evidence counts 1/k, and must-avoid items and constraints mask options first. Decide. The next question maximises expected uncertainty removed × impact. A constrained policy ranks safe actions by uncertainty reduction, progress, confirmation and acceptance minus interruption cost. Clicks and dwell time are never rewards. Check. Coverage, conflicts and blockers move the stage through Explore, Clarify, Focus and Commit. Stop. The brief is released only when both roles approve the same hash. The belief never confirms anything and is excluded from the signed brief. Every suggestion and what happened next is logged, so a policy can later be trained on real outcomes. Details: docs/22.

Requires Python 3.11.

git clone https://github.com/JaspinXu/AlignSpace.git
cd AlignSpace
python -m venv .venv
# Windows: .venv\Scripts\activate      macOS/Linux: source .venv/bin/activate
pip install -r requirements-dev.txt
cp .env.example .env                    # PowerShell: Copy-Item .env.example .env
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8010

Open http://127.0.0.1:8010. Without credentials, set ALIGNSPACE_ANALYSIS_MODE=offline: offline rules read only explicit positive keywords in notes, and the UI says so.

1. Choose Start my room brief, or Try a guided sample for labelled sample notes.
2. Add goals, a must-avoid item and a note, then Suggest preferences from notes. Confirm or reject each suggestion.
3. Answer the questions. The side panel shows the suggested next step and how clear each decision is.
4. Invite my designer and open the link in a private window: a session cannot hold both roles.
5. As the designer, answer layout and care, then add a constraint that contradicts a confirmed preference and resolve the conflict.
6. Approve from both sessions, then export JSON or print to PDF. Edit anything afterwards and both approvals disappear.

python -m pytest -q                                   # 77 tests
python scripts/simulate_belief.py                     # belief recovery on synthetic data
# Two-session browser run (synthetic data, offline mode), writes docs/evidence/
ALIGNSPACE_ANALYSIS_MODE=offline ALIGNSPACE_DB_PATH=/tmp/e2e.db python -m uvicorn app.main:app --port 8011
python scripts/e2e_golden_path.py http://127.0.0.1:8011

Every push runs the same checks in GitHub Actions: ruff, the test suite, the belief simulation and a schema check on the recorded brief.

Evidence: verification report · run results · example approved brief · evaluation plan.

The assessed build runs on the organiser-provided AWS Lightsail medium instance. From Git Bash, macOS or Linux, with the change committed:

scripts/deploy_lightsail.sh ubuntu@<PUBLIC_IP> ~/.ssh/alignspace-lightsail.pem   # https://<PUBLIC_IP>.sslip.io

The script ships git archive HEAD only (no local database, uploads or secrets). It installs a versioned release, keeps .env and data between releases, runs a hardened systemd service behind Caddy, checks /health, and rolls back if the check fails. Open ports 80 and 443 in the Lightsail firewall first. See the deployment runbook. For local Docker: docker compose up --build (port 8000).

app/
  main.py              FastAPI app, session middleware, typed endpoints
  engine.py            Design state, adaptive questions, conflicts, readiness, approvals
  belief.py            Evidence-weighted belief and constrained next-step policy
  gateway.py           Organiser LLM / vision adapters, bounded and schema-validated
  interview.py         55 conditional detail questions (EN / 中文)
  knowledge.py         BM25 retrieval over attributed handbook excerpts
  discovery.py         Singapore home previews (parse-only, no script execution)
  access.py, store.py  Memberships, invitations, SQLite store and audit
  static/              Web app, styles, locale data
schemas/               Design brief JSON schema
scripts/               Deploy, E2E run, belief simulation, locale build
deploy/                systemd unit and Caddyfile
tests/                 77 unit, API and regression tests
docs/                  Product, agent, safety, evaluation, deployment and submission docs
  evidence/            E2E results, screenshots, example brief
  writeup/             Write-up source and PDF
  assets/readme/       README figures

Code is released under the MIT License. Design-handbook excerpts, Singapore listing metadata and linked images, and Getty AAT terms keep their original owners' terms: they are attributed and linked for discussion, not relicensed (see the end of LICENSE). All screenshots and demo data in this repository are synthetic.