add module 10 files

Author: santana-ai

module-10-context/demos/.env.example

@@ -0,0 +1,7 @@
+OPENAI_API_KEY=sk-...
+
+# Langfuse tracing. Self-hosted (local docker compose) is the default; for
+# Langfuse Cloud set LANGFUSE_HOST to https://us.cloud.langfuse.com (or the EU host).
+LANGFUSE_PUBLIC_KEY=pk-lf-...
+LANGFUSE_SECRET_KEY=sk-lf-...
+LANGFUSE_HOST=http://localhost:3000

module-10-context/demos/.gitignore

@@ -0,0 +1,8 @@
+.venv
+__pycache__/
+*.pyc
+*.pyo
+.env
+state.db
+realthor.db
+uv.lock

module-10-context/demos/.python-version

@@ -0,0 +1 @@
+3.12

module-10-context/demos/LANGFUSE.md

@@ -0,0 +1,51 @@
+# Local Langfuse for the isolation demo
+
+`demo_02.py --trace` ships each run to Langfuse, attributed to the caller's **user** and
+**session**. Run Langfuse locally with its official Docker stack, pinned to a release:
+
+```bash
+git clone --branch v3.130.0 https://github.com/langfuse/langfuse.git
+cd langfuse
+docker compose up -d          # UI on http://localhost:3000 after ~2-3 min
+```
+
+Then:
+
+1. Open `http://localhost:3000`, create an account (local, not the cloud), create a project.
+2. Copy the project's **public** and **secret** keys into this demo's `.env`:
+
+   ```
+   LANGFUSE_PUBLIC_KEY=pk-lf-...
+   LANGFUSE_SECRET_KEY=sk-lf-...
+   LANGFUSE_HOST=http://localhost:3000
+   ```
+
+3. Run the traced demo and open the runs in the UI:
+
+   ```bash
+   uv run python demo_02.py --case login-sessions --trace
+   ```
+
+This is a **separate** Docker stack from any RealThor container — run it from the cloned
+`langfuse/` directory with its own `docker compose`. Pin the release tag; the self-hosting
+stack evolves. Current quickstart: https://langfuse.com/self-hosting/deployment/docker-compose
+
+The backend is chosen entirely by env vars, so switching to Langfuse Cloud is just a `.env`
+change: set `LANGFUSE_HOST=https://us.cloud.langfuse.com` (or the EU host) and use the keys
+from your cloud project.
+
+## What to look at once it's open
+
+Go to **Tracing → Traces**. Each run carries the caller's identity:
+
+- **Filter by User** — pick `analyst_001` and you see only that analyst's runs. A different
+  user's runs are a separate, attributed group. The isolation the checkpointer enforces on
+  state is now visible in the traces.
+- **Filter by Session** — one session groups a user's turns together, so you can follow a
+  conversation across runs (and come back to it later).
+- Open a trace and read the span tree: **spans** are the `get_demand_score` tool calls
+  (click one for its arguments and returned row); **generations** are the LLM calls with
+  model, tokens, cost, and latency.
+
+Attribution is set in `run_turn` via `config["metadata"]`: `langfuse_user_id`,
+`langfuse_session_id`, and `langfuse_tags`.

module-10-context/demos/config.yaml

@@ -0,0 +1,17 @@
+agent:
+  name: RealThor
+  version: "0.10.0-demo"
+
+model:
+  name: gpt-4o-mini
+  temperature: 0.0
+
+tracing:
+  enabled: true
+
+paths:
+  prompt: prompts/system_prompt.md
+  demand_data: data/demand.csv
+  users_data: data/users.csv
+  app_db: realthor.db      # application state — users + sessions
+  state_db: state.db       # LangGraph checkpointer — agent state, keyed by thread_id

module-10-context/demos/data/demand.csv

@@ -0,0 +1,5 @@
+region,property_type,bedrooms,demand_score,supply_score
+west,apartment,2,0.82,0.41
+west,studio,1,0.69,0.55
+north,apartment,2,0.54,0.80
+north,house,3,0.37,0.91

module-10-context/demos/data/users.csv

@@ -0,0 +1,4 @@
+user_id,name,role,region_access,active
+analyst_001,Maria Santos,analyst,all,True
+broker_west_001,Emma Rossi,broker,west,True
+broker_north_001,Yuki Tanaka,broker,north,True

module-10-context/demos/demo_01.py

@@ -0,0 +1,92 @@
+"""Demo 1 — the *before*: a flag is not a login, a run is not a session.
+
+Reproduces the two failures RealThor has before this module:
+  * impersonation — identity is a bare ``--user`` claim, no password;
+  * amnesia — every run gets a fresh thread, so nothing is remembered, and the
+    naive fix (share a thread) leaks one caller's context into another's.
+
+Run:  uv run python demo_01.py --case all
+      uv run python demo_01.py --case impersonation   # no model call
+      uv run python demo_01.py --case amnesia
+"""
+
+import click
+from dotenv import load_dotenv
+
+from realthor.agent import build_agent, build_checkpointer, ensure_db, run_turn_raw
+from realthor.config import load_config, resolve_paths
+from realthor.context import UserContext, resolve_user
+
+load_dotenv()
+CONFIG = "config.yaml"
+
+
+def _rule(title):
+    click.echo("\n" + "=" * 60)
+    click.echo(title)
+    click.echo("=" * 60)
+
+
+def case_impersonation(cfg):
+    _rule("BEFORE — impersonation: a flag is not a login")
+    db = cfg["paths"]["app_db"]
+
+    # The old CLI trusted --user with no password. Anyone can pick any id.
+    ctx = resolve_user("analyst_001", db)
+    click.echo(f"$ realthor chat --user analyst_001   (no password asked)")
+    click.echo(f"  → became {ctx.user_id}: role={ctx.role}, region_access={ctx.region_access}")
+
+    # Worse, a flag can carry anything the caller invents — nothing verifies it.
+    forged = UserContext(user_id="ceo_root", role="admin", region_access="all")
+    click.echo(f"$ realthor chat --user ceo_root       (also no password)")
+    click.echo(f"  → claimed {forged.user_id}: role={forged.role}, region_access={forged.region_access}")
+    click.echo("\nNo credential was ever checked. Identity is unproven.")
+
+
+def case_amnesia(cfg):
+    _rule("BEFORE — amnesia: every run is a throwaway thread")
+    agent = build_agent(cfg, checkpointer=build_checkpointer(cfg))
+    analyst = resolve_user("analyst_001", cfg["paths"]["app_db"])
+
+    # Two turns, each on a FRESH random thread — the second forgets the first.
+    import uuid
+    click.echo("\nTurn 1 (thread A):")
+    click.echo("  user> For my notes: my client's acquisition budget is 2.4 million euros.")
+    r1 = run_turn_raw(agent, analyst, str(uuid.uuid4()), "For my notes: my client's acquisition budget is 2.4 million euros.")
+    click.echo(f"  realthor> {r1}")
+    click.echo("\nTurn 2 (thread B — a new run):")
+    click.echo("  user> What budget did we just discuss?")
+    r2 = run_turn_raw(agent, analyst, str(uuid.uuid4()), "What budget did we just discuss?")
+    click.echo(f"  realthor> {r2}")
+    click.echo("\n→ No memory across runs. There is no session.")
+
+    # Naive fix: share one hardcoded thread so it 'remembers'. Now it leaks.
+    _rule("BEFORE — the naive fix leaks: one shared thread, two users")
+    broker = resolve_user("broker_north_001", cfg["paths"]["app_db"])
+    shared = "shared-thread"
+    a_msg = "For my notes: my client's acquisition budget is 2.4 million euros."
+    click.echo("\nUser A = analyst_001 (thread 'shared-thread'):")
+    click.echo(f"  user> {a_msg}")
+    a_reply = run_turn_raw(agent, analyst, shared, a_msg)
+    click.echo(f"  realthor> {a_reply}")
+    click.echo("\nUser B = broker_north_001 (SAME thread 'shared-thread'):")
+    click.echo("  user> What budget did we discuss earlier?")
+    leak = run_turn_raw(agent, broker, shared, "What budget did we discuss earlier?")
+    click.echo(f"  realthor> {leak}")
+    click.echo("\n→ User B just read User A's private note. State is shared because nothing keys it to identity.")
+
+
+@click.command()
+@click.option("--case", "case", default="all",
+              type=click.Choice(["all", "impersonation", "amnesia"]))
+def main(case):
+    cfg = resolve_paths(load_config(CONFIG), CONFIG)
+    ensure_db(cfg)
+    if case in ("all", "impersonation"):
+        case_impersonation(cfg)
+    if case in ("all", "amnesia"):
+        case_amnesia(cfg)
+
+
+if __name__ == "__main__":
+    main()

module-10-context/demos/demo_02.py

@@ -0,0 +1,111 @@
+"""Demo 2 — the *after*: log in, and your sessions are yours.
+
+Same scenarios as demo_01, now correct:
+  * login — a password proves identity before any context is resolved;
+  * sessions — owned, resumable conversations with human-readable titles;
+  * isolation — a caller can only see and resume their own sessions, and state
+    is keyed by ``thread_id_for(user, session)`` so nothing leaks.
+
+Run:  uv run python demo_02.py --case all
+      uv run python demo_02.py --case login-sessions --trace   # attribute in Langfuse
+      uv run python demo_02.py --case isolation                # ownership; no model call
+"""
+
+import click
+from dotenv import load_dotenv
+
+from realthor import auth, sessions
+from realthor.agent import build_agent, build_checkpointer, build_tracer, ensure_db, run_turn
+from realthor.config import load_config, resolve_paths
+
+load_dotenv()
+CONFIG = "config.yaml"
+
+
+def _rule(title):
+    click.echo("\n" + "=" * 60)
+    click.echo(title)
+    click.echo("=" * 60)
+
+
+def case_login_sessions(cfg, trace):
+    _rule("AFTER — login + an owned, resumable session")
+    db = cfg["paths"]["app_db"]
+    agent = build_agent(cfg, checkpointer=build_checkpointer(cfg))
+    tracer = build_tracer(cfg) if trace else None
+
+    # 1) Prove identity with a password (not a bare flag).
+    click.echo("\nLogin: analyst_001 / <password>")
+    ctx = auth.authenticate(db, "analyst_001", auth.DEV_PASSWORD)
+    bad = auth.authenticate(db, "analyst_001", "wrong-password")
+    click.echo(f"  correct password → {ctx.user_id} ({ctx.role})")
+    click.echo(f"  wrong password   → {bad}  (denied)")
+
+    # 2) Start a session; its title comes from the first message.
+    first = "What's the demand for a 2-bedroom apartment in the west region?"
+    title = sessions.generate_title(first)
+    sid = sessions.create_session(db, ctx.user_id, title)
+    click.echo(f'\nStarted session "{title}"')
+    click.echo(f"  user> {first}")
+    r1 = run_turn(agent, ctx, sid, first, tracer=tracer)
+    sessions.touch_session(db, sid)
+    click.echo(f"  realthor> {r1}")
+
+    # 3) List and resume it — same user+session → same thread → it remembers.
+    click.echo("\nYour sessions:")
+    for s in sessions.list_sessions(db, ctx.user_id):
+        click.echo(f"  · {s['title']}  ({s['message_count']} msgs)")
+    resumed = sessions.get_session(db, sid, ctx.user_id)
+    click.echo(f'\nResume "{resumed["title"]}":')
+    click.echo("  user> Remind me which segment we were looking at.")
+    r2 = run_turn(agent, ctx, sid, "Remind me which segment we were looking at.", tracer=tracer)
+    sessions.touch_session(db, sid)
+    click.echo(f"  realthor> {r2}")
+    click.echo("\n→ Persisted, because the thread is keyed to (this user, this session).")
+    if tracer:
+        click.echo("(traced — filter Langfuse by user analyst_001 / this session)")
+
+
+def case_isolation(cfg):
+    _rule("AFTER — isolation: sessions belong to their owner")
+    db = cfg["paths"]["app_db"]
+    analyst = auth.authenticate(db, "analyst_001", auth.DEV_PASSWORD)
+    broker = auth.authenticate(db, "broker_north_001", auth.DEV_PASSWORD)
+
+    # analyst_001 owns a session; broker_north_001 must not see or resume it.
+    sid = sessions.create_session(db, analyst.user_id, "Analyst private notes")
+    click.echo(f"\nanalyst_001 created session {sid[:8]}… ('Analyst private notes')")
+
+    click.echo("\nbroker_north_001 lists their sessions:")
+    theirs = sessions.list_sessions(db, broker.user_id)
+    click.echo(f"  → {[s['title'] for s in theirs]}  (analyst's is not here)")
+
+    click.echo("\nbroker_north_001 tries to resume the analyst's session by id:")
+    stolen = sessions.get_session(db, sid, broker.user_id)
+    click.echo(f"  → get_session(...) = {stolen}  (ownership check denies it)")
+
+    # One user, two sessions → different threads → no cross-talk.
+    from realthor.context import thread_id_for
+    s_west = sessions.create_session(db, analyst.user_id, "West focus")
+    s_north = sessions.create_session(db, analyst.user_id, "North focus")
+    click.echo("\nOne analyst, two sessions map to two isolated threads:")
+    click.echo(f"  West  → {thread_id_for(analyst.user_id, s_west)}")
+    click.echo(f"  North → {thread_id_for(analyst.user_id, s_north)}")
+    click.echo("\n→ Isolation is identity-scoped state, not a smarter prompt.")
+
+
+@click.command()
+@click.option("--case", "case", default="all",
+              type=click.Choice(["all", "login-sessions", "isolation"]))
+@click.option("--trace/--no-trace", default=False, help="Attribute the run to user/session in Langfuse.")
+def main(case, trace):
+    cfg = resolve_paths(load_config(CONFIG), CONFIG)
+    ensure_db(cfg)
+    if case in ("all", "login-sessions"):
+        case_login_sessions(cfg, trace)
+    if case in ("all", "isolation"):
+        case_isolation(cfg)
+
+
+if __name__ == "__main__":
+    main()

module-10-context/demos/prompts/system_prompt.md

@@ -0,0 +1,10 @@
+You are RealThor, a listing supply intelligence assistant for Ciudaty PropTech.
+
+Answer questions about market demand and supply for a region, property type, and
+bedroom count. Always call the `get_demand_score` tool for the requested segment
+— do not guess. Keep answers short and concrete.
+
+The tool enforces the caller's region access. Only if it returns a `blocked`
+status with `region_out_of_scope` should you tell the caller that segment is
+outside their access; otherwise report the demand and supply scores it returns.
+Remember what the caller told you earlier in this conversation.