현재 작업 전체 반영

This commit is contained in:
Yun Chan 2026-06-27 16:08:41 +09:00
parent 5560638e54
commit c0dddab594
85 changed files with 11322 additions and 539 deletions

View file

@ -70,10 +70,19 @@ def user_id_from_email(email: str) -> str:
return str(uuid.uuid5(uuid.NAMESPACE_URL, f"vignette:user:{email.strip().lower()}"))
def user_id_from_external_id(external_id: str) -> str:
return str(uuid.uuid5(uuid.NAMESPACE_URL, f"vignette:user-external:{external_id.strip().lower()}"))
def _normalize_email(email: str) -> str:
return email.strip().lower()
def _normalize_external_id(external_id: str | None, email: str) -> str:
value = (external_id or "").strip().lower()
return value or f"email:{_normalize_email(email)}"
def _db_role(role: str) -> str:
return DB_ROLE_BY_APP.get(role, role)
@ -309,6 +318,24 @@ async def ensure_runtime_tables() -> None:
)
"""
)
await conn.execute(
"""
DROP POLICY IF EXISTS p_case_insert ON app.case_profile;
DROP POLICY IF EXISTS p_case_update ON app.case_profile;
CREATE POLICY p_case_insert ON app.case_profile FOR INSERT WITH CHECK (
app.is_ai_context() OR app.current_role_name() IN ('admin','instructor')
OR learner_id = app.current_uid()
);
CREATE POLICY p_case_update ON app.case_profile FOR UPDATE USING (
app.is_ai_context() OR app.current_role_name() IN ('admin','instructor')
OR learner_id = app.current_uid()
) WITH CHECK (
app.is_ai_context() OR app.current_role_name() IN ('admin','instructor')
OR learner_id = app.current_uid()
)
"""
)
await conn.execute(
"""
DROP POLICY IF EXISTS p_turns_modify ON app.turns;
@ -412,10 +439,12 @@ async def upsert_managed_user(
role: str,
cohort_ids: list[str] | None = None,
user_id: str | None = None,
external_id: str | None = None,
affiliation: str | None = None,
reactivate: bool = False,
) -> ManagedUser:
normalized_email = _normalize_email(email)
normalized_external_id = _normalize_external_id(external_id, normalized_email)
try:
pool = get_pool()
async with pool.acquire() as conn:
@ -437,7 +466,7 @@ async def upsert_managed_user(
WHERE app.app_user.is_active OR $7
RETURNING user_id, email, display_name, role, cohort, affiliation, created_at, last_seen_at
""",
f"email:{normalized_email}",
normalized_external_id,
normalized_email,
(display_name.strip() if display_name else normalized_email),
_db_role(role),
@ -468,7 +497,7 @@ async def upsert_managed_user(
display_name=display_name,
role=role,
cohort_ids=cohort_ids,
user_id=user_id,
user_id=user_id or user_id_from_external_id(normalized_external_id),
affiliation=affiliation,
reactivate=reactivate,
)
@ -669,6 +698,7 @@ async def create_session(
role: str,
cohort_ids: list[str] | None = None,
user_id: str | None = None,
external_id: str | None = None,
) -> tuple[str, SessionUser]:
raw_sid = secrets.token_urlsafe(32)
normalized_email = _normalize_email(email)
@ -678,6 +708,7 @@ async def create_session(
role=role,
cohort_ids=cohort_ids,
user_id=user_id,
external_id=external_id,
reactivate=False,
)
expires_at = time.time() + settings.session_ttl_seconds

View file

@ -80,6 +80,10 @@ class Settings(BaseSettings):
)
engine_timeout: float = 120.0 # SSE 롱리브드 (50분 상담 대비, 스트림은 무제한 별도)
engine_connect_timeout: float = 10.0
admin_usage_budget_usd: float = Field(
default=0.0,
validation_alias="ADMIN_USAGE_BUDGET_USD",
)
# ── 외부 LLM 키 (게이트웨이가 못 받을 때 직접 폴백, PII 마스킹 후만) ──
anthropic_api_key: str = Field(default="", validation_alias="ANTHROPIC_API_KEY")
@ -127,6 +131,14 @@ class Settings(BaseSettings):
default=[],
validation_alias="AUTH_ADMIN_EMAILS",
)
auth_email_cohort_map: dict[str, str] = Field(
default_factory=dict,
validation_alias="AUTH_EMAIL_COHORT_MAP",
)
auth_domain_cohort_map: dict[str, str] = Field(
default_factory=dict,
validation_alias="AUTH_DOMAIN_COHORT_MAP",
)
auth_dev_login_enabled: bool = Field(
default=False,
validation_alias="AUTH_DEV_LOGIN_ENABLED",

View file

@ -60,6 +60,12 @@ class PersonaReviewItem:
approved_at: str | None
@dataclass(frozen=True, slots=True)
class PersonaDraftRecord:
review: PersonaReviewItem
card: PersonaCard
def seed_persona_id(code: str) -> str:
return str(uuid.uuid5(uuid.NAMESPACE_URL, f"vignette:persona:{code.upper()}"))
@ -143,6 +149,13 @@ def persona_review_item_from_row(row: Any) -> PersonaReviewItem:
)
def persona_draft_record_from_row(row: Any) -> PersonaDraftRecord:
return PersonaDraftRecord(
review=persona_review_item_from_row(row),
card=card_from_row(row),
)
def seed_fallback_persona(code: str) -> CatalogPersona | None:
card = get_seed_persona(code)
if card is None:
@ -300,6 +313,187 @@ async def list_persona_review_queue(
return [persona_review_item_from_row(row) for row in rows]
async def get_persona_draft_record(
*,
persona_id: str,
role: str,
) -> PersonaDraftRecord | None:
if role not in {"teacher", "admin"}:
raise ValueError("persona draft read requires teacher or admin role")
get_pool()
async with acquire(role=role) as conn:
row = await conn.fetchrow(
f"""
SELECT {_CARD_COLUMNS}, created_at, approved_at
FROM app.persona_card
WHERE persona_id = $1::uuid
AND status IN ('draft', 'review')
LIMIT 1
""",
persona_id,
)
return persona_draft_record_from_row(row) if row is not None else None
async def create_persona_draft(
*,
card: PersonaCard,
author_id: str,
role: str,
submit_for_review: bool = False,
) -> PersonaReviewItem:
if role not in {"teacher", "admin"}:
raise ValueError("persona draft creation requires teacher or admin role")
next_status = "review" if submit_for_review else "draft"
persona_id = str(uuid.uuid4())
get_pool()
async with acquire(role=role, user_id=author_id) as conn:
version = await conn.fetchval(
"""
SELECT COALESCE(MAX(version), 0) + 1
FROM app.persona_card
WHERE upper(code) = upper($1)
""",
card.code,
)
row = await conn.fetchrow(
f"""
INSERT INTO app.persona_card (
persona_id, code, version, status, display_name, difficulty,
theory_target, demographics, presenting, history, big5,
resistance, speech_style, affect_baseline, ccd,
dsm5_dimensional, source_provenance, is_synthetic, created_by
)
VALUES (
$1::uuid, $2, $3, $4, $5, $6,
$7::text[], $8::jsonb, $9::jsonb, $10::jsonb, $11::jsonb,
$12::jsonb, $13::jsonb, $14::jsonb, $15::jsonb,
$16::jsonb, $17, $18, $19::uuid
)
RETURNING {_REVIEW_COLUMNS}
""",
persona_id,
card.code,
int(version or 1),
next_status,
card.display_name,
card.difficulty,
card.theory_target,
card.demographics,
card.presenting,
card.history,
card.big5,
card.resistance,
card.speech_style,
card.affect_baseline,
card.ccd,
card.dsm5_dimensional,
card.source_provenance,
card.is_synthetic,
author_id,
)
await conn.execute(
"""
INSERT INTO audit.audit_log (
actor_uid, action, target_kind, target_id, detail
)
VALUES ($1::uuid, $2, $3, $4, $5::jsonb)
""",
author_id,
"persona_draft_create",
"persona_card",
persona_id,
{
"next_status": next_status,
"code": card.code,
"version": int(row["version"]),
},
)
return persona_review_item_from_row(row)
async def update_persona_draft(
*,
persona_id: str,
card: PersonaCard,
author_id: str,
role: str,
submit_for_review: bool = False,
) -> PersonaReviewItem | None:
if role not in {"teacher", "admin"}:
raise ValueError("persona draft update requires teacher or admin role")
next_status = "review" if submit_for_review else "draft"
get_pool()
async with acquire(role=role, user_id=author_id) as conn:
row = await conn.fetchrow(
f"""
UPDATE app.persona_card
SET
code = $2,
status = $3,
display_name = $4,
difficulty = $5,
theory_target = $6::text[],
demographics = $7::jsonb,
presenting = $8::jsonb,
history = $9::jsonb,
big5 = $10::jsonb,
resistance = $11::jsonb,
speech_style = $12::jsonb,
affect_baseline = $13::jsonb,
ccd = $14::jsonb,
dsm5_dimensional = $15::jsonb,
source_provenance = $16,
is_synthetic = $17,
approved_by = NULL,
approved_at = NULL
WHERE persona_id = $1::uuid
AND status IN ('draft', 'review')
RETURNING {_REVIEW_COLUMNS}
""",
persona_id,
card.code,
next_status,
card.display_name,
card.difficulty,
card.theory_target,
card.demographics,
card.presenting,
card.history,
card.big5,
card.resistance,
card.speech_style,
card.affect_baseline,
card.ccd,
card.dsm5_dimensional,
card.source_provenance,
card.is_synthetic,
)
if row is None:
return None
await conn.execute(
"""
INSERT INTO audit.audit_log (
actor_uid, action, target_kind, target_id, detail
)
VALUES ($1::uuid, $2, $3, $4, $5::jsonb)
""",
author_id,
"persona_draft_update",
"persona_card",
persona_id,
{
"next_status": next_status,
"code": str(row["code"]).upper(),
"version": int(row["version"]),
},
)
return persona_review_item_from_row(row)
async def update_persona_review_status(
*,
persona_id: str,
@ -375,21 +569,26 @@ async def get_catalog_persona(code: str) -> CatalogPersona | None:
__all__ = [
"CatalogPersona",
"PersonaDraftRecord",
"PersonaReviewItem",
"PersonaReviewAction",
"PersonaStatus",
"SEED_VERSION",
"card_from_row",
"catalog_persona_from_row",
"create_persona_draft",
"get_approved_persona",
"get_catalog_persona",
"get_persona_draft_record",
"list_approved_personas",
"list_catalog_personas",
"list_persona_review_queue",
"materialize_seed_personas",
"persona_draft_record_from_row",
"persona_review_item_from_row",
"seed_fallback_persona",
"seed_fallback_personas",
"seed_persona_id",
"update_persona_draft",
"update_persona_review_status",
]

View file

@ -4,9 +4,10 @@ from __future__ import annotations
import time
from datetime import datetime, timezone
from decimal import Decimal
from typing import Annotated, Literal
from fastapi import APIRouter, Depends, HTTPException, status
from fastapi import APIRouter, Depends, HTTPException, Query, status
from pydantic import BaseModel, Field
from ..auth_sessions import (
@ -23,11 +24,13 @@ from ..engine_client import engine_client
from ..runtime_policy import require_runtime_fallback_allowed
from ..services.voice import voice_service
from ..services import rag
from ..store import store
router = APIRouter(prefix="/admin", tags=["admin"])
AdminPrincipal = Annotated[Principal, Depends(require_role(Role.ADMIN))]
HealthStatus = Literal["ok", "degraded", "down"]
UsageBudgetStatus = Literal["disabled", "ok", "warn", "exceeded"]
class AdminServiceHealth(BaseModel):
@ -46,6 +49,36 @@ class AdminHealthResponse(BaseModel):
services: list[AdminServiceHealth]
class AdminUsageBreakdown(BaseModel):
provider: str
model: str
turns: int
tokens_in: int
tokens_out: int
cost_usd: float
class AdminUsageBudget(BaseModel):
limit_usd: float
used_ratio: float
remaining_usd: float | None
status: UsageBudgetStatus
class AdminUsageResponse(BaseModel):
source: Literal["database", "server_session_registry"]
durable: bool
window_days: int
generated_at: float
total_turns: int
metered_turns: int
tokens_in: int
tokens_out: int
cost_usd: float
budget: AdminUsageBudget
by_provider: list[AdminUsageBreakdown]
class AdminEngineConfigResponse(BaseModel):
engine_mode: str
engine_url: str
@ -120,6 +153,47 @@ def _workload_load(count: int, expected_capacity: int) -> float:
return _clamp01(count / expected_capacity)
def _decimal_to_float(value: object) -> float:
if value is None:
return 0.0
if isinstance(value, Decimal):
return float(value)
try:
return float(value)
except (TypeError, ValueError):
return 0.0
def _safe_usage_int(value: object) -> int:
try:
return int(value or 0)
except (TypeError, ValueError):
return 0
def _usage_budget(cost_usd: float) -> AdminUsageBudget:
limit = max(0.0, float(settings.admin_usage_budget_usd or 0.0))
if limit <= 0:
return AdminUsageBudget(
limit_usd=0.0,
used_ratio=0.0,
remaining_usd=None,
status="disabled",
)
used_ratio = max(0.0, cost_usd / limit)
status_value: UsageBudgetStatus = "ok"
if used_ratio >= 1.0:
status_value = "exceeded"
elif used_ratio >= 0.8:
status_value = "warn"
return AdminUsageBudget(
limit_usd=round(limit, 6),
used_ratio=round(used_ratio, 4),
remaining_usd=round(max(0.0, limit - cost_usd), 6),
status=status_value,
)
async def _runtime_health_metrics(*, db_ok: bool) -> RuntimeHealthMetrics:
metrics = RuntimeHealthMetrics()
@ -175,6 +249,157 @@ async def _runtime_health_metrics(*, db_ok: bool) -> RuntimeHealthMetrics:
return metrics
async def _usage_from_database(window_days: int) -> AdminUsageResponse:
async with acquire(role="admin") as conn:
total_row = await conn.fetchrow(
"""
SELECT
COUNT(*) FILTER (WHERE speaker = 'client') AS total_turns,
COUNT(*) FILTER (
WHERE speaker = 'client'
AND (
llm_provider IS NOT NULL OR model IS NOT NULL
OR tokens_in IS NOT NULL OR tokens_out IS NOT NULL
OR cost_usd IS NOT NULL
)
) AS metered_turns,
COALESCE(SUM(tokens_in) FILTER (WHERE speaker = 'client'), 0)::bigint AS tokens_in,
COALESCE(SUM(tokens_out) FILTER (WHERE speaker = 'client'), 0)::bigint AS tokens_out,
COALESCE(SUM(cost_usd) FILTER (WHERE speaker = 'client'), 0)::numeric AS cost_usd
FROM app.turns
WHERE created_at >= now() - ($1::int * interval '1 day')
""",
window_days,
)
rows = await conn.fetch(
"""
SELECT
COALESCE(llm_provider, 'unknown') AS provider,
COALESCE(model, 'unknown') AS model,
COUNT(*) AS turns,
COALESCE(SUM(tokens_in), 0)::bigint AS tokens_in,
COALESCE(SUM(tokens_out), 0)::bigint AS tokens_out,
COALESCE(SUM(cost_usd), 0)::numeric AS cost_usd
FROM app.turns
WHERE created_at >= now() - ($1::int * interval '1 day')
AND speaker = 'client'
AND (
llm_provider IS NOT NULL OR model IS NOT NULL
OR tokens_in IS NOT NULL OR tokens_out IS NOT NULL
OR cost_usd IS NOT NULL
)
GROUP BY 1, 2
ORDER BY cost_usd DESC, tokens_in + tokens_out DESC, turns DESC
LIMIT 12
""",
window_days,
)
total_cost = round(_decimal_to_float(total_row["cost_usd"] if total_row else 0), 6)
return AdminUsageResponse(
source="database",
durable=True,
window_days=window_days,
generated_at=time.time(),
total_turns=_safe_usage_int(total_row["total_turns"] if total_row else 0),
metered_turns=_safe_usage_int(total_row["metered_turns"] if total_row else 0),
tokens_in=_safe_usage_int(total_row["tokens_in"] if total_row else 0),
tokens_out=_safe_usage_int(total_row["tokens_out"] if total_row else 0),
cost_usd=total_cost,
budget=_usage_budget(total_cost),
by_provider=[
AdminUsageBreakdown(
provider=str(row["provider"] or "unknown"),
model=str(row["model"] or "unknown"),
turns=_safe_usage_int(row["turns"]),
tokens_in=_safe_usage_int(row["tokens_in"]),
tokens_out=_safe_usage_int(row["tokens_out"]),
cost_usd=round(_decimal_to_float(row["cost_usd"]), 6),
)
for row in rows
],
)
def _usage_from_runtime_store(window_days: int) -> AdminUsageResponse:
window_start = time.time() - (window_days * 86400)
total_turns = 0
metered_turns = 0
tokens_in = 0
tokens_out = 0
cost_usd = 0.0
buckets: dict[tuple[str, str], dict[str, int | float]] = {}
for sess in store.list():
for turn in getattr(sess, "turns", []) or []:
if getattr(turn, "speaker", "") != "client":
continue
if float(getattr(turn, "created_at", 0.0) or 0.0) < window_start:
continue
total_turns += 1
provider = str(getattr(turn, "llm_provider", None) or "unknown")
model = str(getattr(turn, "model", None) or "unknown")
turn_tokens_in = _safe_usage_int(getattr(turn, "tokens_in", 0))
turn_tokens_out = _safe_usage_int(getattr(turn, "tokens_out", 0))
turn_cost = _decimal_to_float(getattr(turn, "cost_usd", 0.0))
is_metered = (
provider != "unknown"
or model != "unknown"
or turn_tokens_in > 0
or turn_tokens_out > 0
or turn_cost > 0
)
if not is_metered:
continue
metered_turns += 1
tokens_in += turn_tokens_in
tokens_out += turn_tokens_out
cost_usd += turn_cost
key = (provider, model)
bucket = buckets.setdefault(
key,
{"turns": 0, "tokens_in": 0, "tokens_out": 0, "cost_usd": 0.0},
)
bucket["turns"] = int(bucket["turns"]) + 1
bucket["tokens_in"] = int(bucket["tokens_in"]) + turn_tokens_in
bucket["tokens_out"] = int(bucket["tokens_out"]) + turn_tokens_out
bucket["cost_usd"] = float(bucket["cost_usd"]) + turn_cost
by_provider = [
AdminUsageBreakdown(
provider=provider,
model=model,
turns=int(values["turns"]),
tokens_in=int(values["tokens_in"]),
tokens_out=int(values["tokens_out"]),
cost_usd=round(float(values["cost_usd"]), 6),
)
for (provider, model), values in sorted(
buckets.items(),
key=lambda item: (
-float(item[1]["cost_usd"]),
-(int(item[1]["tokens_in"]) + int(item[1]["tokens_out"])),
-int(item[1]["turns"]),
),
)[:12]
]
total_cost = round(cost_usd, 6)
return AdminUsageResponse(
source="server_session_registry",
durable=False,
window_days=window_days,
generated_at=time.time(),
total_turns=total_turns,
metered_turns=metered_turns,
tokens_in=tokens_in,
tokens_out=tokens_out,
cost_usd=total_cost,
budget=_usage_budget(total_cost),
by_provider=by_provider,
)
class AdminUserCreate(BaseModel):
email: str = Field(..., min_length=3, max_length=254)
display_name: str = Field(..., min_length=1, max_length=80)
@ -407,6 +632,19 @@ async def admin_health(principal: AdminPrincipal) -> AdminHealthResponse:
)
@router.get("/usage", response_model=AdminUsageResponse)
async def admin_usage(
principal: AdminPrincipal,
window_days: Annotated[int, Query(ge=1, le=90)] = 7,
) -> AdminUsageResponse:
"""Return AI token/cost usage from persisted turns or dev fallback state."""
try:
return await _usage_from_database(window_days)
except Exception:
require_runtime_fallback_allowed("admin usage")
return _usage_from_runtime_store(window_days)
@router.get("/engine-config", response_model=AdminEngineConfigResponse)
async def get_engine_config(principal: AdminPrincipal) -> AdminEngineConfigResponse:
"""Return the current admin-managed engine settings."""

View file

@ -11,6 +11,9 @@ from __future__ import annotations
import base64
import hashlib
import hmac
import json
import logging
import secrets
import time
from dataclasses import dataclass
@ -34,11 +37,14 @@ from ..saml import (
)
router = APIRouter(prefix="/auth", tags=["auth"])
logger = logging.getLogger(__name__)
GOOGLE_AUTHORIZE_URL = "https://accounts.google.com/o/oauth2/v2/auth"
GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token"
GOOGLE_TOKENINFO_URL = "https://oauth2.googleapis.com/tokeninfo"
OAUTH_STATE_TTL_SECONDS = 10 * 60
OAUTH_STATE_COOKIE_NAME = "__Host-vignette_oauth_state"
DEV_OAUTH_STATE_COOKIE_NAME = "vignette_oauth_state"
@dataclass(slots=True)
@ -201,6 +207,54 @@ def _role_for_saml_identity(identity: SamlIdentity) -> Role:
return _role_for_email(identity.email)
def _split_cohort_values(value: str | None) -> list[str]:
if not value:
return []
return [item.strip() for item in value.split(",") if item.strip()]
def _append_unique(items: list[str], values: list[str]) -> None:
seen = {item.lower() for item in items}
for value in values:
key = value.lower()
if key and key not in seen:
items.append(value)
seen.add(key)
def _configured_cohort_ids(
*,
email: str,
hosted_domain: str | None = None,
claim_hint: str | None = None,
) -> list[str]:
normalized_email = _normalize_email(email)
domain = _email_domain(normalized_email)
hd = _normalize_domain(hosted_domain)
email_map = {
_normalize_email(key): value
for key, value in settings.auth_email_cohort_map.items()
if _normalize_email(key)
}
domain_map = {
_normalize_domain(key): value
for key, value in settings.auth_domain_cohort_map.items()
if _normalize_domain(key)
}
cohorts: list[str] = []
_append_unique(cohorts, _split_cohort_values(email_map.get(normalized_email)))
_append_unique(cohorts, _split_cohort_values(domain_map.get(domain)))
if hd and hd != domain:
_append_unique(cohorts, _split_cohort_values(domain_map.get(hd)))
_append_unique(cohorts, _split_cohort_values(claim_hint))
return cohorts
def _provider_external_id(provider: str, subject: str | None, email: str) -> str:
value = (subject or "").strip() or _normalize_email(email)
return f"{provider}:{value.lower()}"
def _safe_next_path(next_path: str | None) -> str:
if not next_path or not next_path.startswith("/") or next_path.startswith("//"):
return "/"
@ -254,7 +308,12 @@ def _is_dev_login_allowed_origin(origin: str) -> bool:
def _configured_frontend_origins() -> list[str]:
origins: list[str] = []
for value in [settings.frontend_base_url, *settings.frontend_origin_map.values(), *settings.cors_origins]:
for value in [
settings.frontend_base_url,
*settings.frontend_origin_map.values(),
*settings.cors_origins,
*settings.auth_dev_login_extra_origins,
]:
origin = _url_origin(value)
if origin and origin not in origins:
origins.append(origin)
@ -276,6 +335,17 @@ def _frontend_origin_for_request(request: Request | None = None) -> str:
hostname = host.rsplit(":", 1)[0].lower() if host else ""
if mapped_origin := _frontend_origin_map().get(hostname):
return mapped_origin
forwarded_proto = (
request.headers.get("x-forwarded-proto", "").split(",", 1)[0].strip().lower()
)
if forwarded_host and forwarded_proto in {"http", "https"}:
forwarded_origin = _url_origin(f"{forwarded_proto}://{host}")
if (
settings.environment == "dev"
and forwarded_origin
and _is_dev_login_allowed_origin(forwarded_origin)
):
return forwarded_origin
if hostname in {"localhost", "127.0.0.1", "::1"}:
return fallback
@ -299,6 +369,93 @@ def _pkce_challenge(verifier: str) -> str:
return base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
def _b64url_encode(value: bytes) -> str:
return base64.urlsafe_b64encode(value).decode("ascii").rstrip("=")
def _b64url_decode(value: str) -> bytes:
padded = value + ("=" * (-len(value) % 4))
return base64.urlsafe_b64decode(padded.encode("ascii"))
def _oauth_state_signature(payload: str) -> str:
digest = hmac.new(
settings.session_secret.encode("utf-8"),
f"oauth-state:{payload}".encode("utf-8"),
hashlib.sha256,
).digest()
return _b64url_encode(digest)
def _oauth_code_verifier_for_state(state: str) -> str:
digest = hmac.new(
settings.session_secret.encode("utf-8"),
f"oauth-pkce:{state}".encode("utf-8"),
hashlib.sha256,
).digest()
return _b64url_encode(digest)
def _build_oauth_state(next_path: str | None) -> tuple[str, OAuthState]:
created_at = time.time()
safe_next = _safe_next_path(next_path)
payload = {
"iat": created_at,
"next": safe_next,
"nonce": secrets.token_urlsafe(24),
}
payload_blob = _b64url_encode(
json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
)
state = f"{payload_blob}.{_oauth_state_signature(payload_blob)}"
return state, OAuthState(
code_verifier=_oauth_code_verifier_for_state(state),
next_path=safe_next,
created_at=created_at,
)
def _oauth_state_from_signed_token(state: str | None) -> OAuthState | None:
if not state or "." not in state:
return None
payload_blob, signature = state.rsplit(".", 1)
if not payload_blob or not signature:
return None
if not hmac.compare_digest(signature, _oauth_state_signature(payload_blob)):
return None
try:
payload = json.loads(_b64url_decode(payload_blob).decode("utf-8"))
created_at = float(payload.get("iat", 0))
except (ValueError, TypeError, json.JSONDecodeError):
return None
if created_at <= 0 or created_at < time.time() - OAUTH_STATE_TTL_SECONDS:
return None
if not isinstance(payload.get("nonce"), str):
return None
next_path = payload.get("next")
if not isinstance(next_path, str):
return None
return OAuthState(
code_verifier=_oauth_code_verifier_for_state(state),
next_path=_safe_next_path(next_path),
created_at=created_at,
)
def _oauth_state_for_callback(state: str | None, cookie_state: str | None) -> OAuthState | None:
if not state:
return None
if cookie_state != state:
return None
stored = _oauth_states.pop(state, None)
if stored is not None:
return stored
return _oauth_state_from_signed_token(state)
def _prune_oauth_states() -> None:
cutoff = time.time() - OAUTH_STATE_TTL_SECONDS
stale = [key for key, value in _oauth_states.items() if value.created_at < cutoff]
@ -342,6 +499,46 @@ def _set_session_cookie(response: Response, sid: str) -> None:
)
def _set_oauth_state_cookie(response: Response, state: str) -> None:
response.set_cookie(
key=OAUTH_STATE_COOKIE_NAME,
value=state,
max_age=OAUTH_STATE_TTL_SECONDS,
httponly=True,
secure=True,
samesite="lax",
path="/",
)
if settings.environment == "dev":
response.set_cookie(
key=DEV_OAUTH_STATE_COOKIE_NAME,
value=state,
max_age=OAUTH_STATE_TTL_SECONDS,
httponly=True,
secure=False,
samesite="lax",
path="/",
)
def _delete_oauth_state_cookie(response: Response) -> None:
response.delete_cookie(
OAUTH_STATE_COOKIE_NAME,
httponly=True,
secure=True,
samesite="lax",
path="/",
)
if settings.environment == "dev":
response.delete_cookie(
DEV_OAUTH_STATE_COOKIE_NAME,
httponly=True,
secure=False,
samesite="lax",
path="/",
)
def _delete_session_cookie(response: Response) -> None:
response.delete_cookie(
settings.cookie_name,
@ -375,13 +572,28 @@ def _frontend_login_redirect(reason: str, request: Request) -> RedirectResponse:
return RedirectResponse(f"{base_url}/login?{urlencode({'oauth': reason})}", status_code=302)
def _oauth_callback_error(reason: str, request: Request) -> RedirectResponse:
response = _frontend_login_redirect(reason, request)
_delete_oauth_state_cookie(response)
return response
def _log_oauth_callback_failure(request: Request, reason: str, **fields: object) -> None:
"""Log OAuth callback failures without authorization codes, tokens, or raw user IDs."""
host = request.headers.get("x-forwarded-host") or request.headers.get("host")
logger.warning(
"google_oauth_callback_failed reason=%s host=%s forwarded_proto=%s details=%s",
reason,
host,
request.headers.get("x-forwarded-proto"),
fields,
)
def _dev_login_available(request: Request) -> bool:
if settings.environment != "dev" or not settings.auth_dev_login_enabled:
return False
if _dev_login_extra_origins():
return True
saw_browser_origin = False
for header_name in ("origin", "referer"):
origin = _url_origin(request.headers.get(header_name))
@ -389,16 +601,28 @@ def _dev_login_available(request: Request) -> bool:
saw_browser_origin = True
if not _is_dev_login_allowed_origin(origin):
return False
if not saw_browser_origin and _dev_login_extra_origins():
if saw_browser_origin:
return True
forwarded_host = request.headers.get("x-forwarded-host")
host = (forwarded_host or request.headers.get("host") or "").split(",", 1)[0].strip()
origin = _url_origin(f"http://{host}") if host else None
forwarded_proto = (
request.headers.get("x-forwarded-proto", "").split(",", 1)[0].strip().lower()
)
scheme = forwarded_proto if forwarded_host and forwarded_proto in {"http", "https"} else "http"
origin = _url_origin(f"{scheme}://{host}") if host else None
return bool(origin and _is_dev_login_allowed_origin(origin))
def _dev_oauth_redirect_unavailable(request: Request) -> bool:
redirect_origin = _url_origin(settings.oauth_redirect_uri)
return bool(
_dev_login_available(request)
and redirect_origin
and not _is_local_origin(redirect_origin)
)
@router.get("/config", response_model=AuthConfigResponse)
async def auth_config(request: Request) -> AuthConfigResponse:
"""Return non-secret login configuration for the browser login screen."""
@ -449,15 +673,12 @@ async def login(
return _frontend_login_redirect("unsupported_provider", request)
if not _google_configured():
return _frontend_login_redirect("not_configured", request)
if _dev_oauth_redirect_unavailable(request):
return _frontend_login_redirect("local_oauth_unavailable", request)
_prune_oauth_states()
state = secrets.token_urlsafe(32)
verifier = secrets.token_urlsafe(64)
_oauth_states[state] = OAuthState(
code_verifier=verifier,
next_path=_safe_next_path(next),
created_at=time.time(),
)
state, stored_state = _build_oauth_state(next)
_oauth_states[state] = stored_state
params = {
"client_id": settings.oauth_google_client_id,
@ -465,11 +686,13 @@ async def login(
"response_type": "code",
"scope": "openid email profile",
"state": state,
"code_challenge": _pkce_challenge(verifier),
"code_challenge": _pkce_challenge(stored_state.code_verifier),
"code_challenge_method": "S256",
"prompt": "select_account",
}
return RedirectResponse(f"{GOOGLE_AUTHORIZE_URL}?{urlencode(params)}", status_code=302)
response = RedirectResponse(f"{GOOGLE_AUTHORIZE_URL}?{urlencode(params)}", status_code=302)
_set_oauth_state_cookie(response, state)
return response
@router.get("/callback")
@ -477,15 +700,45 @@ async def callback(
request: Request,
code: Annotated[Optional[str], Query()] = None,
state: Annotated[Optional[str], Query()] = None,
error: Annotated[Optional[str], Query()] = None,
error_description: Annotated[Optional[str], Query()] = None,
oauth_state_cookie: Annotated[Optional[str], Cookie(alias=OAUTH_STATE_COOKIE_NAME)] = None,
dev_oauth_state_cookie: Annotated[Optional[str], Cookie(alias=DEV_OAUTH_STATE_COOKIE_NAME)] = None,
) -> RedirectResponse:
"""Exchange Google auth code, validate identity, and issue a BFF cookie."""
if error:
reason = "access_denied" if error == "access_denied" else "provider_error"
_log_oauth_callback_failure(
request,
reason,
provider_error=error,
has_state=bool(state),
has_error_description=bool(error_description),
)
return _oauth_callback_error(reason, request)
if not code or not state:
return _frontend_login_redirect("missing_callback", request)
_log_oauth_callback_failure(
request,
"missing_callback",
has_code=bool(code),
has_state=bool(state),
)
return _oauth_callback_error("missing_callback", request)
_prune_oauth_states()
stored = _oauth_states.pop(state, None)
cookie_state = oauth_state_cookie or (
dev_oauth_state_cookie if settings.environment == "dev" else None
)
stored = _oauth_state_for_callback(state, cookie_state)
if stored is None:
return _frontend_login_redirect("invalid_state", request)
_log_oauth_callback_failure(
request,
"invalid_state",
has_cookie=bool(cookie_state),
state_in_memory=state in _oauth_states if state else False,
)
return _oauth_callback_error("invalid_state", request)
async with httpx.AsyncClient(timeout=10.0) as client:
token_res = await client.post(
@ -501,22 +754,45 @@ async def callback(
headers={"Accept": "application/json"},
)
if token_res.status_code >= 400:
return _frontend_login_redirect("token_exchange_failed", request)
token_error: object
try:
token_body = token_res.json()
token_error = {
"error": token_body.get("error"),
"error_description": token_body.get("error_description"),
}
except Exception:
token_error = "non_json_error"
_log_oauth_callback_failure(
request,
"token_exchange_failed",
status_code=token_res.status_code,
token_error=token_error,
)
return _oauth_callback_error("token_exchange_failed", request)
token_payload = token_res.json()
id_token = token_payload.get("id_token")
if not isinstance(id_token, str) or not id_token:
return _frontend_login_redirect("id_token_missing", request)
_log_oauth_callback_failure(request, "id_token_missing")
return _oauth_callback_error("id_token_missing", request)
info_res = await client.get(GOOGLE_TOKENINFO_URL, params={"id_token": id_token})
if info_res.status_code >= 400:
return _frontend_login_redirect("id_token_invalid", request)
_log_oauth_callback_failure(
request,
"id_token_invalid",
status_code=info_res.status_code,
)
return _oauth_callback_error("id_token_invalid", request)
claims = info_res.json()
if claims.get("aud") != settings.oauth_google_client_id:
return _frontend_login_redirect("audience_mismatch", request)
_log_oauth_callback_failure(request, "audience_mismatch")
return _oauth_callback_error("audience_mismatch", request)
issuer = claims.get("iss")
if issuer not in {"accounts.google.com", "https://accounts.google.com"}:
return _frontend_login_redirect("issuer_mismatch", request)
_log_oauth_callback_failure(request, "issuer_mismatch", issuer=issuer)
return _oauth_callback_error("issuer_mismatch", request)
try:
email = validate_google_identity_domain(
@ -525,21 +801,39 @@ async def callback(
hosted_domain=claims.get("hd"),
)
except HTTPException:
return _frontend_login_redirect("domain_not_allowed", request)
_log_oauth_callback_failure(
request,
"domain_not_allowed",
email_domain=_email_domain(str(claims.get("email") or "")),
hosted_domain=_normalize_domain(str(claims.get("hd") or "")),
)
return _oauth_callback_error("domain_not_allowed", request)
role = _role_for_email(email)
display_name = str(claims.get("name") or email)
cohort_ids = _configured_cohort_ids(
email=email,
hosted_domain=str(claims.get("hd") or ""),
)
external_id = _provider_external_id("google", str(claims.get("sub") or ""), email)
try:
sid, _ = await create_session(
email=email,
display_name=display_name,
role=role.value,
cohort_ids=[],
cohort_ids=cohort_ids,
external_id=external_id,
)
except InactiveUserError as exc:
return _frontend_login_redirect("inactive_user", request)
_log_oauth_callback_failure(
request,
"inactive_user",
email_domain=_email_domain(email),
)
return _oauth_callback_error("inactive_user", request)
response = RedirectResponse(_frontend_url(stored.next_path, request), status_code=302)
_set_session_cookie(response, sid)
_delete_oauth_state_cookie(response)
return response
@ -580,12 +874,15 @@ async def saml_acs(request: Request) -> RedirectResponse:
return _frontend_login_redirect("saml_assertion_invalid", request)
role = _role_for_saml_identity(identity)
cohort_ids = _configured_cohort_ids(email=email, claim_hint=identity.cohort_hint)
external_id = _provider_external_id("saml", identity.subject, email)
try:
sid, _ = await create_session(
email=email,
display_name=identity.display_name or email,
role=role.value,
cohort_ids=[],
cohort_ids=cohort_ids,
external_id=external_id,
)
except InactiveUserError:
return _frontend_login_redirect("inactive_user", request)
@ -615,7 +912,8 @@ async def dev_login(request: Request, body: DevLoginRequest, response: Response)
email=email,
display_name=body.display_name or email,
role=body.role,
cohort_ids=[],
cohort_ids=_configured_cohort_ids(email=email),
external_id=_provider_external_id("dev", email, email),
)
except InactiveUserError as exc:
raise HTTPException(status.HTTP_403_FORBIDDEN, detail="user is inactive") from exc

View file

@ -115,6 +115,7 @@ async def reevaluate_session(
technique_codes=technique_codes,
theory_mode=_theory_mode_of(sess),
scope=body.scope if body.scope in ("session_end", "stage_transition") else "session_end",
audit_hook=session_persistence.record_llm_call_audit,
)
except EngineError as e:
raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, detail=f"engine unavailable: {e}")
@ -184,7 +185,12 @@ async def reevaluate_turn(
recent_turns=recent,
)
result = await evaluator.evaluate_turn(ctx, client_reply, engine=engine_client)
result = await evaluator.evaluate_turn(
ctx,
client_reply,
engine=engine_client,
audit_hook=session_persistence.record_llm_call_audit,
)
if result.error and result.error.startswith("engine_error"):
raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, detail=result.error)
return result

View file

@ -5,20 +5,26 @@ from __future__ import annotations
from typing import Annotated, Any, Literal
from fastapi import APIRouter, Depends, HTTPException, Response, status
from pydantic import BaseModel
from pydantic import BaseModel, Field
from ..deps import CurrentPrincipal, Principal, Role, require_role
from ..persona_repository import (
CatalogPersona,
PersonaDraftRecord,
PersonaReviewAction,
PersonaReviewItem,
create_persona_draft,
get_persona_draft_record,
list_catalog_personas,
list_persona_review_queue,
update_persona_draft,
update_persona_review_status,
)
from ..services.persona import PersonaCard
router = APIRouter(prefix="/personas", tags=["personas"])
TeacherOrAdmin = Annotated[Principal, Depends(require_role(Role.TEACHER, Role.ADMIN))]
JSON_OBJECT_FIELD = {"additionalProperties": True}
class PersonaSummary(BaseModel):
@ -51,6 +57,37 @@ class PersonaReviewDecisionRequest(BaseModel):
action: PersonaReviewAction
class PersonaDraftPayload(BaseModel):
code: str = Field(min_length=1, max_length=24)
display_name: str = Field(min_length=1, max_length=80)
difficulty: Literal["easy", "moderate", "hard"]
theory_target: list[str] = Field(default_factory=list)
demographics: dict[str, Any] = Field(default_factory=dict, json_schema_extra=JSON_OBJECT_FIELD)
presenting: dict[str, Any] = Field(default_factory=dict, json_schema_extra=JSON_OBJECT_FIELD)
history: dict[str, Any] = Field(default_factory=dict, json_schema_extra=JSON_OBJECT_FIELD)
big5: dict[str, float] = Field(default_factory=dict)
resistance: dict[str, float] = Field(default_factory=dict)
speech_style: dict[str, Any] = Field(default_factory=dict, json_schema_extra=JSON_OBJECT_FIELD)
affect_baseline: dict[str, float] = Field(default_factory=dict)
ccd: dict[str, Any] = Field(default_factory=dict, json_schema_extra=JSON_OBJECT_FIELD)
dsm5_dimensional: dict[str, Any] = Field(default_factory=dict, json_schema_extra=JSON_OBJECT_FIELD)
source_provenance: str = Field(default="", max_length=240)
is_synthetic: bool = True
submit_for_review: bool = False
class PersonaDraftDetail(PersonaReviewSummary):
demographics: dict[str, Any] = Field(json_schema_extra=JSON_OBJECT_FIELD)
presenting: dict[str, Any] = Field(json_schema_extra=JSON_OBJECT_FIELD)
history: dict[str, Any] = Field(json_schema_extra=JSON_OBJECT_FIELD)
big5: dict[str, float]
resistance: dict[str, float]
speech_style: dict[str, Any] = Field(json_schema_extra=JSON_OBJECT_FIELD)
affect_baseline: dict[str, float]
ccd: dict[str, Any] = Field(json_schema_extra=JSON_OBJECT_FIELD)
dsm5_dimensional: dict[str, Any] = Field(json_schema_extra=JSON_OBJECT_FIELD)
def _first_text_value(data: dict[str, Any]) -> str:
for value in data.values():
if isinstance(value, str) and value.strip():
@ -88,6 +125,49 @@ def _review_summary(entry: PersonaReviewItem) -> PersonaReviewSummary:
)
def _draft_detail(entry: PersonaDraftRecord) -> PersonaDraftDetail:
card = entry.card
return PersonaDraftDetail(
**_review_summary(entry.review).model_dump(),
demographics=card.demographics,
presenting=card.presenting,
history=card.history,
big5=card.big5,
resistance=card.resistance,
speech_style=card.speech_style,
affect_baseline=card.affect_baseline,
ccd=card.ccd,
dsm5_dimensional=card.dsm5_dimensional,
)
def _card_from_draft_payload(request: PersonaDraftPayload) -> PersonaCard:
code = request.code.strip().upper()
display_name = request.display_name.strip()
if not code:
raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, detail="persona code is required")
if not display_name:
raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, detail="display_name is required")
theory_target = [value.strip().lower() for value in request.theory_target if value.strip()]
return PersonaCard(
code=code,
display_name=display_name,
difficulty=request.difficulty,
theory_target=theory_target,
demographics=request.demographics,
presenting=request.presenting,
history=request.history,
big5=request.big5,
resistance=request.resistance,
speech_style=request.speech_style,
affect_baseline=request.affect_baseline,
ccd=request.ccd,
dsm5_dimensional=request.dsm5_dimensional,
source_provenance=request.source_provenance.strip(),
is_synthetic=request.is_synthetic,
)
def _ensure_teacher_or_admin(principal: Principal) -> None:
if principal.role not in {Role.TEACHER, Role.ADMIN}:
raise HTTPException(status.HTTP_403_FORBIDDEN, detail="only teachers and admins can review personas")
@ -127,6 +207,79 @@ async def list_persona_reviews(principal: TeacherOrAdmin) -> list[PersonaReviewS
return [_review_summary(entry) for entry in queue]
@router.post("/drafts", response_model=PersonaReviewSummary, status_code=status.HTTP_201_CREATED)
async def create_persona_draft_route(
request: PersonaDraftPayload,
principal: TeacherOrAdmin,
) -> PersonaReviewSummary:
"""Create a draft persona card version for faculty review."""
_ensure_teacher_or_admin(principal)
try:
created = await create_persona_draft(
card=_card_from_draft_payload(request),
author_id=principal.user_id,
role=principal.role.value,
submit_for_review=request.submit_for_review,
)
except ValueError as exc:
raise HTTPException(status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
except Exception as exc:
raise HTTPException(
status.HTTP_503_SERVICE_UNAVAILABLE,
detail="persona draft database unavailable",
) from exc
return _review_summary(created)
@router.get("/drafts/{persona_id}", response_model=PersonaDraftDetail)
async def get_persona_draft_route(
persona_id: str,
principal: TeacherOrAdmin,
) -> PersonaDraftDetail:
"""Return a draft/review persona card for editing."""
_ensure_teacher_or_admin(principal)
try:
record = await get_persona_draft_record(persona_id=persona_id, role=principal.role.value)
except ValueError as exc:
raise HTTPException(status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
except Exception as exc:
raise HTTPException(
status.HTTP_503_SERVICE_UNAVAILABLE,
detail="persona draft database unavailable",
) from exc
if record is None:
raise HTTPException(status.HTTP_404_NOT_FOUND, detail="persona draft not found")
return _draft_detail(record)
@router.put("/drafts/{persona_id}", response_model=PersonaReviewSummary)
async def update_persona_draft_route(
persona_id: str,
request: PersonaDraftPayload,
principal: TeacherOrAdmin,
) -> PersonaReviewSummary:
"""Update a draft/review persona card and optionally submit it for review."""
_ensure_teacher_or_admin(principal)
try:
updated = await update_persona_draft(
persona_id=persona_id,
card=_card_from_draft_payload(request),
author_id=principal.user_id,
role=principal.role.value,
submit_for_review=request.submit_for_review,
)
except ValueError as exc:
raise HTTPException(status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
except Exception as exc:
raise HTTPException(
status.HTTP_503_SERVICE_UNAVAILABLE,
detail="persona draft update database unavailable",
) from exc
if updated is None:
raise HTTPException(status.HTTP_404_NOT_FOUND, detail="persona draft not found or locked")
return _review_summary(updated)
@router.post("/review/{persona_id}", response_model=PersonaReviewSummary)
async def decide_persona_review(
persona_id: str,

View file

@ -18,18 +18,19 @@ from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel, Field
from sse_starlette.sse import EventSourceResponse
from .. import db, session_persistence
from .. import db, session_persistence, turn_runtime
from ..config import settings
from ..deps import CurrentPrincipal, Principal, Role
from ..engine_client import EngineError, engine_client
from ..persona_repository import get_catalog_persona
from ..runtime_policy import require_runtime_fallback_allowed, runtime_fallback_allowed
from ..runtime_policy import require_runtime_fallback_allowed
from ..services import evaluator, memory, orchestrator, rag, state_machine
from ..store import InProcSession, TurnRecord, store
router = APIRouter(prefix="/sessions", tags=["sessions"])
TheoryMode = Literal["humanistic", "cbt", "integrative"]
EndStateValue = str | int | float | bool | None | dict[str, float]
class SessionStartRequest(BaseModel):
@ -51,6 +52,12 @@ class TurnRequest(BaseModel):
text: str = Field(..., min_length=1)
class CrisisResourceResponse(BaseModel):
title: str
number: str
message: str
class TurnResponse(BaseModel):
turn_seq: int
stage: str
@ -58,13 +65,15 @@ class TurnResponse(BaseModel):
client_reply: Optional[str] = None
safety_flagged: bool = False
crisis_kind: str = "none"
crisis_resource: Optional[CrisisResourceResponse] = None
conversation_stopped: bool = False
class SessionEndResponse(BaseModel):
session_id: str
session_no: int
digest_pending: bool
end_state: dict
end_state: dict[str, EndStateValue]
class LearnerSessionSummary(BaseModel):
@ -121,6 +130,12 @@ class ReviewTechnique(BaseModel):
label: str
class ReviewNonverbalEvent(BaseModel):
kind: Literal["audio", "silence", "pace", "barge_in"]
label: str
detail: str
class ReviewNote(BaseModel):
author: str
tone: str
@ -136,6 +151,7 @@ class ReviewTurn(BaseModel):
who: str
text: str
techniques: list[ReviewTechnique] = Field(default_factory=list)
nonverbal: list[ReviewNonverbalEvent] = Field(default_factory=list)
note: Optional[ReviewNote] = None
@ -164,6 +180,34 @@ class ReviewPoint(BaseModel):
jumpTo: Optional[str] = None
class ReviewWorksheetEvidence(BaseModel):
turnId: str
speaker: Literal["learner", "client"]
quote: str
class ReviewWorksheetItem(BaseModel):
key: str
label: str
value: Optional[str] = None
evidence: list[ReviewWorksheetEvidence] = Field(default_factory=list)
confidence: Literal["none", "low", "medium"] = "none"
emptyReason: Optional[str] = None
class ReviewWorksheetSection(BaseModel):
key: str
title: str
items: list[ReviewWorksheetItem] = Field(default_factory=list)
class ReviewCaseWorksheet(BaseModel):
status: Literal["empty", "draft_from_transcript"] = "empty"
generatedBy: str = "rule-based transcript extractor"
sections: list[ReviewWorksheetSection] = Field(default_factory=list)
limitations: list[str] = Field(default_factory=list)
class SessionReviewResponse(BaseModel):
session_id: str
client: ReviewClient
@ -184,6 +228,7 @@ class SessionReviewResponse(BaseModel):
rubric: list[ReviewRubricRow] = Field(default_factory=list)
goodMoments: list[ReviewPoint] = Field(default_factory=list)
growthPoints: list[ReviewPoint] = Field(default_factory=list)
caseWorksheet: ReviewCaseWorksheet = Field(default_factory=ReviewCaseWorksheet)
nextLine: Optional[str] = None
clientFeedback: Optional[str] = None
audioUrl: Optional[str] = None
@ -337,6 +382,27 @@ async def _build_start_recall(*, case_id: str, card) -> memory.RecallContext:
)
async def _build_seed_recall(*, case_id: str | None) -> memory.RecallContext:
if not case_id:
return memory.build_recall_context()
try:
db.get_pool()
except RuntimeError:
return memory.build_recall_context()
prev_summary = await _load_prev_case_summary(case_id)
pinned = list((prev_summary or {}).get("pinned_facts") or [])
return memory.build_recall_context(prev_summary=prev_summary, pinned_facts=pinned)
async def ensure_recall_context(sess: InProcSession) -> memory.RecallContext:
cached = _RECALL_CACHE.get(sess.session_id)
if cached is not None:
return cached
recall = await _build_seed_recall(case_id=sess.case_id)
_RECALL_CACHE[sess.session_id] = recall
return recall
async def _warm_rag_caches(session_id: str, case_id: str, card) -> None:
"""RAG 회상·KB 행동단서를 **백그라운드**로 산출해 캐시한다(요청 경로 비차단).
@ -362,13 +428,7 @@ _PHASE_KEY_BY_LABEL = {
def _stage_label(stage: object) -> str:
name = getattr(stage, "name", "")
return {
"RAPPORT": "라포",
"EXPLORE": "탐색",
"INTERVENE": "개입",
"CLOSE": "정리",
}.get(name, str(getattr(stage, "value", stage)))
return turn_runtime.stage_label(stage)
def _ensure_learner(principal: Principal) -> None:
@ -383,54 +443,22 @@ async def _load_session_or_404(
allow_ended: bool = False,
include_turn_evaluation: bool = False,
) -> InProcSession:
sess = await session_persistence.load_session(
sess, err = await turn_runtime.load_owned_session(
session_id,
principal,
allow_ended=True,
allow_ended=allow_ended,
include_turn_evaluation=include_turn_evaluation,
)
if sess is not None:
store.put(sess)
elif runtime_fallback_allowed():
sess = store.get(session_id)
if sess is None:
if err == turn_runtime.SessionAccessError.NOT_FOUND:
raise HTTPException(status.HTTP_404_NOT_FOUND, detail="session not found")
if sess.learner_id != principal.user_id:
if err == turn_runtime.SessionAccessError.FORBIDDEN:
raise HTTPException(status.HTTP_403_FORBIDDEN, detail="session does not belong to user")
if sess.ended and not allow_ended:
if err == turn_runtime.SessionAccessError.ENDED:
raise HTTPException(status.HTTP_409_CONFLICT, detail="session already ended")
assert sess is not None
return sess
async def _append_session_turn(sess: InProcSession, turn: TurnRecord) -> None:
if await session_persistence.append_turn(
session_id=sess.session_id,
learner_id=sess.learner_id,
turn=turn,
):
sess.turns.append(turn)
store.put(sess)
return
require_runtime_fallback_allowed("session turn append")
store.append_turn(sess.session_id, turn)
async def _update_session_state(
sess: InProcSession,
state: state_machine.SessionState,
) -> None:
if await session_persistence.update_state(
session_id=sess.session_id,
learner_id=sess.learner_id,
state=state,
):
sess.state = state
store.put(sess)
return
require_runtime_fallback_allowed("session state update")
store.update_state(sess.session_id, state)
async def _end_persisted_session(sess: InProcSession, carry: memory.CarryOver) -> None:
if await session_persistence.end_session(sess, carry):
sess.ended = True
@ -639,6 +667,178 @@ def _latest_client_feedback(turns: list[ReviewTurn]) -> str | None:
return None
def _worksheet_evidence(turn: ReviewTurn) -> ReviewWorksheetEvidence:
return ReviewWorksheetEvidence(
turnId=turn.id,
speaker=turn.speaker,
quote=_clip_text(turn.text, 120),
)
def _worksheet_item(
*,
key: str,
label: str,
turns: list[ReviewTurn],
keywords: list[str],
preferred_speaker: Literal["learner", "client"] | None = None,
fallback_turn: ReviewTurn | None = None,
) -> ReviewWorksheetItem:
lowered_keywords = [keyword.lower() for keyword in keywords if keyword]
candidates = turns
if preferred_speaker:
preferred = [turn for turn in turns if turn.speaker == preferred_speaker]
candidates = preferred + [turn for turn in turns if turn.speaker != preferred_speaker]
for turn in candidates:
text = _compact_text(turn.text)
lower_text = text.lower()
if lowered_keywords and any(keyword in lower_text for keyword in lowered_keywords):
return ReviewWorksheetItem(
key=key,
label=label,
value=_clip_text(text, 140),
evidence=[_worksheet_evidence(turn)],
confidence="medium",
)
if fallback_turn is not None:
return ReviewWorksheetItem(
key=key,
label=label,
value=_clip_text(fallback_turn.text, 140),
evidence=[_worksheet_evidence(fallback_turn)],
confidence="low",
)
return ReviewWorksheetItem(
key=key,
label=label,
value=None,
evidence=[],
confidence="none",
emptyReason="저장된 축어록에서 명시 근거를 찾지 못했습니다.",
)
def _worksheet_section(
key: str,
title: str,
specs: list[tuple[str, str, list[str], Literal["learner", "client"] | None]],
turns: list[ReviewTurn],
fallback_client: ReviewTurn | None,
fallback_learner: ReviewTurn | None,
) -> ReviewWorksheetSection:
items: list[ReviewWorksheetItem] = []
for item_key, label, keywords, speaker in specs:
fallback = fallback_client if speaker == "client" else fallback_learner if speaker == "learner" else None
items.append(
_worksheet_item(
key=item_key,
label=label,
turns=turns,
keywords=keywords,
preferred_speaker=speaker,
fallback_turn=fallback if item_key in {"presenting_complaint", "first_goal"} else None,
)
)
return ReviewWorksheetSection(key=key, title=title, items=items)
def _case_worksheet_from_turns(turns: list[ReviewTurn]) -> ReviewCaseWorksheet:
if not turns:
return ReviewCaseWorksheet(
status="empty",
sections=[],
limitations=["저장된 축어록이 없어 사례개념화 워크시트를 생성하지 않았습니다."],
)
fallback_client = next((turn for turn in turns if turn.speaker == "client"), None)
fallback_learner = next((turn for turn in turns if turn.speaker == "learner"), None)
section_specs: list[
tuple[str, str, list[tuple[str, str, list[str], Literal["learner", "client"] | None]]]
] = [
(
"exploration_11",
"탐색 11항목",
[
("presenting_complaint", "주호소", ["힘들", "문제", "걱정", "불안", "우울", "스트레스", "관계"], "client"),
("trigger_context", "계기·상황", ["언제", "상황", "최근", "계기", "때"], "client"),
("emotion", "정서", ["불안", "우울", "화", "슬프", "답답", "무섭", "외롭", "걱정"], "client"),
("cognition", "생각", ["생각", "느낌", "해야", "못", "실패", "의미"], "client"),
("behavior", "행동", ["피하", "잠", "먹", "울", "말", "연락", "공부", "멈"], "client"),
("body", "신체·수면", ["잠", "식욕", "몸", "두통", "심장", "숨", "피곤"], "client"),
("relationship", "관계", ["친구", "가족", "부모", "엄마", "아빠", "교수", "사람", "관계"], "client"),
("resources", "자원", ["도움", "지지", "친구", "상담", "선생님", "가족"], "client"),
("risk", "위험 신호", ["죽", "자살", "해치", "사라지고", "끝내", "위험"], "client"),
("motivation", "변화동기", ["원", "바라", "변화", "해보고", "싶"], None),
("first_goal", "상담 목표 초안", ["목표", "계획", "다음", "해볼", "원하"], "learner"),
],
),
(
"five_domains",
"호소 5영역",
[
("domain_emotion", "정서", ["불안", "우울", "화", "슬프", "답답", "외롭"], "client"),
("domain_cognition", "인지", ["생각", "걱정", "실패", "못", "의미"], "client"),
("domain_behavior", "행동", ["피하", "연락", "공부", "잠", "멈"], "client"),
("domain_relationship", "대인관계", ["친구", "가족", "사람", "관계", "부모"], "client"),
("domain_body", "신체", ["잠", "식욕", "몸", "두통", "피곤", "숨"], "client"),
],
),
(
"cognitive_triad_emotions",
"인지삼제·1/2차 감정",
[
("triad_self", "자기", ["나는", "내가", "나 자신", "스스로"], "client"),
("triad_world", "타인·세계", ["사람", "세상", "학교", "가족", "친구"], "client"),
("triad_future", "미래", ["앞으로", "미래", "계속", "나중"], "client"),
("primary_emotion", "1차 감정", ["불안", "슬프", "무섭", "외롭", "걱정"], "client"),
("secondary_emotion", "2차 감정", ["화", "짜증", "수치", "죄책", "부끄"], "client"),
],
),
(
"protective_barrier_quadrants",
"보호·방해 4사분면",
[
("internal_protective", "내적 보호요인", ["해보고", "버텼", "노력", "원", "견뎠"], None),
("internal_barrier", "내적 방해요인", ["못", "두려", "불안", "회피", "걱정"], "client"),
("external_protective", "외적 보호요인", ["친구", "가족", "상담", "교수", "도움"], "client"),
("external_barrier", "외적 방해요인", ["갈등", "압박", "비난", "스트레스", "혼자"], "client"),
],
),
(
"biopsychosocial_goals",
"생물·심리·사회 목표",
[
("bio_goal", "생물", ["잠", "식사", "운동", "몸", "피곤"], "client"),
("psy_goal", "심리", ["생각", "감정", "불안", "연습", "조절"], None),
("social_goal", "사회", ["관계", "대화", "연락", "도움", "친구"], None),
],
),
]
sections = [
_worksheet_section(
key,
title,
specs,
turns,
fallback_client,
fallback_learner,
)
for key, title, specs in section_specs
]
return ReviewCaseWorksheet(
status="draft_from_transcript",
sections=sections,
limitations=[
"저장된 축어록에서 키워드 근거를 추출한 1차 초안입니다.",
"임상팀 루브릭, 교수자 검수, 학습자 수정 입력 전에는 확정 사례개념화로 보지 않습니다.",
],
)
def _evaluation_payload(record: dict[str, object] | None) -> dict[str, object]:
if not record:
return {}
@ -697,35 +897,88 @@ def _review_note_from_turn_eval(ev: dict[str, object] | None) -> Optional[Review
return None
async def _record_safety_event(sess: InProcSession, ctx, result) -> None:
"""위기 escalate 시 app.safety_events 적재(교수자 감사·알림 레코드). C2.
def _seconds_label(milliseconds: int) -> str:
seconds = max(0, milliseconds) / 1000.0
if seconds >= 10:
return f"{seconds:.0f}초"
return f"{seconds:.1f}초"
비차단: DB 미가용(degraded)·FK 미충족(in-memory 세션) 시 graceful skip — 상담 루프를
절대 막지 않는다. 실시간 교수자 push 알림은 후속(이 레코드가 1차 알림원).
"""
crisis = getattr(ctx, "crisis", None)
if crisis is None or not getattr(crisis, "escalate", False):
return
kind = getattr(crisis.kind, "value", None) or str(getattr(crisis, "kind", "crisis"))
try:
async with db.acquire() as conn:
await conn.execute(
"""
INSERT INTO app.safety_events
(session_id, trigger_type, ko_risk_level, escalated, detail)
VALUES ($1::uuid, $2, $3, TRUE, $4::jsonb)
""",
sess.session_id,
kind,
int(getattr(crisis, "risk_level", 0) or 0),
json.dumps({
"matched": list(getattr(crisis, "matched", []) or []),
"stage": getattr(result, "stage", None),
"turn_seq": getattr(result, "turn_seq", None),
}),
def _review_nonverbal_events(turn: TurnRecord) -> list[ReviewNonverbalEvent]:
events: list[ReviewNonverbalEvent] = []
if turn.silence_ms is not None and turn.silence_ms >= 1000:
events.append(
ReviewNonverbalEvent(
kind="silence",
label="침묵",
detail=_seconds_label(turn.silence_ms),
)
)
if turn.speech_rate is not None:
events.append(
ReviewNonverbalEvent(
kind="pace",
label="발화 속도",
detail=f"분당 {turn.speech_rate:.0f}자",
)
)
if turn.barge_in is True:
events.append(
ReviewNonverbalEvent(
kind="barge_in",
label="끼어듦",
detail="내담자 발화 중 시작",
)
)
if turn.audio_ref:
events.append(
ReviewNonverbalEvent(
kind="audio",
label="음성 입력",
detail="음성으로 기록됨",
)
)
return events
async def _evaluate_stream_turn(ctx: orchestrator.TurnContext, final_reply: str) -> Optional[dict]:
"""stream 경로 완료 후 fast-loop 평가를 계산한다. 실패는 턴 저장을 막지 않는다."""
if not final_reply:
return None
try:
hook = evaluator.make_eval_hook(
engine_client,
audit_hook=session_persistence.record_llm_call_audit,
)
return await hook(ctx, final_reply)
except Exception:
pass # 비차단(R5): 적재 실패가 위기 대응/상담을 막지 않음.
return None
def _stream_result_from_done(
ctx: orchestrator.TurnContext,
final_reply: str,
data: dict[str, object],
evaluation: Optional[dict],
) -> orchestrator.TurnResult:
assert ctx.state_after is not None
return orchestrator.TurnResult(
turn_seq=ctx.state_after.turn_seq,
stage=_stage_label(ctx.state_after.stage),
effective_openness=ctx.state_after.effective_openness,
client_reply=final_reply or None,
safety_flagged=bool(data.get("safety_flagged")),
state_after=ctx.state_after,
evaluation=evaluation,
crisis_kind=ctx.crisis.kind.value if ctx.crisis else "none",
crisis_resource=data.get("crisis_resource") if isinstance(data.get("crisis_resource"), dict) else None,
conversation_stopped=bool(data.get("conversation_stopped")),
llm_provider=str(data.get("llm_provider") or "") or None,
model=str(data.get("model") or "") or None,
tokens_in=int(data.get("tokens_in") or 0),
tokens_out=int(data.get("tokens_out") or 0),
cost_usd=float(data.get("cost_usd") or 0.0),
)
def _learner_visible_turns(sess: InProcSession) -> list[TurnRecord]:
@ -752,6 +1005,7 @@ async def _generate_and_save_session_evaluation(sess: InProcSession) -> None:
technique_codes=[],
theory_mode=sess.theory_mode,
scope="session_end",
audit_hook=session_persistence.record_llm_call_audit,
),
timeout=min(float(settings.engine_timeout), 45.0),
)
@ -907,7 +1161,12 @@ async def start_session(
raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"unknown persona {body.persona_code}")
card = catalog_persona.card
recall = memory.build_recall_context()
case_context = await session_persistence.get_case_context(
learner_id=principal.user_id,
persona_id=catalog_persona.persona_id,
)
recall = await _build_seed_recall(case_id=case_context.case_id if case_context else None)
session_no = (case_context.last_session_no + 1) if case_context else 1
st = state_machine.init_state(
params=card.openness_params(),
carry=recall.carry,
@ -919,10 +1178,11 @@ async def start_session(
card=card,
theory_mode=body.theory_mode,
state=st,
session_no=1,
session_no=session_no,
carry_rapport=carry_rapport,
persona_id=catalog_persona.persona_id,
persona_version=catalog_persona.version,
case_id=case_context.case_id if case_context else None,
)
degraded = catalog_persona.degraded or sess is None
if sess is None:
@ -932,7 +1192,7 @@ async def start_session(
persona=card,
theory_mode=body.theory_mode,
state=st,
session_no=1,
session_no=session_no,
carry_rapport=carry_rapport,
)
else:
@ -1007,6 +1267,7 @@ async def get_session_review(
who="학습자" if speaker == "learner" else client_name,
text=turn.text_masked,
techniques=_review_techniques_from_turn_eval(turn_eval),
nonverbal=_review_nonverbal_events(turn) if speaker == "learner" else [],
note=_review_note_from_turn_eval(turn_eval),
)
)
@ -1085,6 +1346,7 @@ async def get_session_review(
rubric=rubric,
goodMoments=good_moments,
growthPoints=growth_points,
caseWorksheet=_case_worksheet_from_turns(turns),
nextLine=next_line,
clientFeedback=client_feedback,
audioUrl=None,
@ -1103,7 +1365,7 @@ async def submit_turn(
"""Submit one trainee utterance and return the generated client reply."""
_ensure_learner(principal)
sess = await _load_session_or_404(session_id, principal)
recall = _RECALL_CACHE.get(session_id) or memory.RecallContext()
recall = await ensure_recall_context(sess)
kb_cues = _KB_CUES_CACHE.get(session_id) or [] # 비차단: warm 전이면 빈 단서(graceful)
ctx = orchestrator.prepare_turn(
@ -1124,7 +1386,11 @@ async def submit_turn(
result = await orchestrator.run_turn_generate(
ctx,
engine_client,
eval_hook=evaluator.make_eval_hook(engine_client),
eval_hook=evaluator.make_eval_hook(
engine_client,
audit_hook=session_persistence.record_llm_call_audit,
),
audit_hook=session_persistence.record_llm_call_audit,
)
except EngineError as exc:
raise HTTPException(
@ -1132,37 +1398,13 @@ async def submit_turn(
detail=f"engine unavailable: {exc}",
) from exc
# 턴별 fast-loop 평가는 학습자(상담자) 발화에 부착(기법 태깅·적절성·의도이탈).
await _append_session_turn(
await turn_runtime.record_completed_turn(
sess,
TurnRecord(
turn_seq=ctx.state_after.turn_seq,
speaker="counselor",
stage=_stage_label(ctx.state_after.stage),
text=body.text,
text_masked=ctx.learner_text_masked,
evaluation=result.evaluation,
),
ctx,
result,
context_prefix="session",
)
if result.client_reply:
await _append_session_turn(
sess,
TurnRecord(
turn_seq=result.turn_seq,
speaker="client",
stage=_stage_label(result.state_after.stage),
text=result.client_reply,
text_masked=result.client_reply,
llm_provider=result.llm_provider,
model=result.model,
tokens_in=result.tokens_in,
tokens_out=result.tokens_out,
cost_usd=result.cost_usd,
),
)
await _update_session_state(sess, result.state_after)
await _record_safety_event(sess, ctx, result) # C2: 위기 escalate 시 safety_events 적재(비차단)
await turn_runtime.record_safety_event(sess, ctx, result)
return TurnResponse(
turn_seq=result.turn_seq,
@ -1171,6 +1413,8 @@ async def submit_turn(
client_reply=result.client_reply,
safety_flagged=result.safety_flagged,
crisis_kind=result.crisis_kind,
crisis_resource=result.crisis_resource,
conversation_stopped=result.conversation_stopped,
)
@ -1183,7 +1427,7 @@ async def stream_turn(
"""Stream a generated client reply for one trainee utterance."""
_ensure_learner(principal)
sess = await _load_session_or_404(session_id, principal)
recall = _RECALL_CACHE.get(session_id) or memory.RecallContext()
recall = await ensure_recall_context(sess)
kb_cues = _KB_CUES_CACHE.get(session_id) or [] # 비차단: warm 전이면 빈 단서(graceful)
ctx = orchestrator.prepare_turn(
@ -1204,40 +1448,26 @@ async def stream_turn(
last_beat = asyncio.get_running_loop().time()
final_reply = ""
try:
async for ev in orchestrator.run_turn_stream(ctx, engine_client):
async for ev in orchestrator.run_turn_stream(
ctx,
engine_client,
audit_hook=session_persistence.record_llm_call_audit,
):
if ev.event == "token":
text = str(ev.data.get("text", ""))
final_reply += text
yield {"event": "token", "data": text}
elif ev.event == "done":
data = {**ev.data, "stage": _stage_label(ctx.state_after.stage)}
await _append_session_turn(
evaluation = await _evaluate_stream_turn(ctx, final_reply)
result = _stream_result_from_done(ctx, final_reply, data, evaluation)
await turn_runtime.record_completed_turn(
sess,
TurnRecord(
turn_seq=ctx.state_after.turn_seq,
speaker="counselor",
stage=_stage_label(ctx.state_after.stage),
text=body.text,
text_masked=ctx.learner_text_masked,
),
ctx,
result,
context_prefix="session",
)
await _update_session_state(sess, ctx.state_after)
if final_reply:
await _append_session_turn(
sess,
TurnRecord(
turn_seq=ctx.state_after.turn_seq,
speaker="client",
stage=_stage_label(ctx.state_after.stage),
text=final_reply,
text_masked=final_reply,
llm_provider=str(ev.data.get("llm_provider") or ""),
model=str(ev.data.get("model") or ""),
tokens_in=int(ev.data.get("tokens_in") or 0),
tokens_out=int(ev.data.get("tokens_out") or 0),
cost_usd=float(ev.data.get("cost_usd") or 0.0),
),
)
await turn_runtime.record_safety_event(sess, ctx, result)
yield {"event": "done", "data": json.dumps(data, ensure_ascii=False)}
else:
yield {"event": ev.event, "data": json.dumps(ev.data, ensure_ascii=False)}

View file

@ -3,7 +3,7 @@
from __future__ import annotations
from datetime import datetime
from typing import Annotated
from typing import Annotated, Any
from fastapi import APIRouter, Depends
from pydantic import BaseModel, Field
@ -34,17 +34,70 @@ class TeacherSessionSummary(BaseModel):
ended_at: str | None = None
class TeacherGrowthPoint(BaseModel):
session_id: str
session_no: int
persona_code: str
stage: str
started_at: str
ended_at: str | None = None
score: float | None = None
rapport: float | None = None
technique_count: int = 0
watch_count: int = 0
class TeacherLearnerGrowth(BaseModel):
learner_id: str
learner_label: str
sessions: int
ended_sessions: int
latest_at: str
first_score: float | None = None
latest_score: float | None = None
score_delta: float | None = None
avg_score: float | None = None
avg_rapport: float | None = None
trend: str = "insufficient"
top_techniques: list[str] = Field(default_factory=list)
points: list[TeacherGrowthPoint] = Field(default_factory=list)
class TeacherSafetyAlert(BaseModel):
id: str
session_id: str
learner_id: str
learner_label: str
persona_code: str
session_no: int
trigger_type: str
ko_risk_level: int
escalated: bool
created_at: str
resource_title: str = "자살예방상담전화 109"
resource_number: str = "109"
class TeacherDashboardResponse(BaseModel):
source: str = "in_memory"
cohort_label: str = "현재 학습 기록"
total_learners: int
active_sessions: int
ended_sessions: int
safety_alerts: list[TeacherSafetyAlert] = Field(default_factory=list)
learner_growth: list[TeacherLearnerGrowth] = Field(default_factory=list)
pending_reviews: list[TeacherSessionSummary] = Field(default_factory=list)
recent_sessions: list[TeacherSessionSummary] = Field(default_factory=list)
message: str
_APPROPRIATENESS_SCORE = {
"neg": 0.0,
"neutral": 0.5,
"pos": 1.0,
}
def _iso(ts: float | None) -> str | None:
if ts is None:
return None
@ -56,6 +109,149 @@ def _learner_label(learner_id: str) -> str:
return f"학습자 {suffix}"
def _safe_float(value: object) -> float | None:
try:
return float(value) # type: ignore[arg-type]
except (TypeError, ValueError):
return None
def _avg(values: list[float]) -> float | None:
if not values:
return None
return round(sum(values) / len(values), 3)
def _turn_eval(turn: Any) -> dict[str, Any] | None:
ev = getattr(turn, "evaluation", None)
return ev if isinstance(ev, dict) else None
def _turn_score(ev: dict[str, Any]) -> float | None:
raw = str(ev.get("appropriateness") or "").strip().lower()
return _APPROPRIATENESS_SCORE.get(raw)
def _turn_rapport(ev: dict[str, Any]) -> float | None:
value = _safe_float(ev.get("rapport_signal"))
if value is None:
return None
return max(-1.0, min(1.0, value))
def _turn_techniques(ev: dict[str, Any]) -> list[str]:
raw = ev.get("techniques")
if not isinstance(raw, list):
return []
labels: list[str] = []
for item in raw:
if isinstance(item, dict):
label = item.get("label") or item.get("name") or item.get("id")
else:
label = item
if label:
labels.append(str(label))
return labels
def _session_growth_point(sess: InProcSession) -> TeacherGrowthPoint:
scores: list[float] = []
rapports: list[float] = []
technique_count = 0
watch_count = 0
for turn in sess.turns:
if turn.speaker != "counselor":
continue
ev = _turn_eval(turn)
if ev is None:
continue
score = _turn_score(ev)
if score is not None:
scores.append(score)
if score < 1.0:
watch_count += 1
rapport = _turn_rapport(ev)
if rapport is not None:
rapports.append(rapport)
technique_count += len(_turn_techniques(ev))
return TeacherGrowthPoint(
session_id=sess.session_id,
session_no=sess.session_no,
persona_code=sess.persona_code,
stage=sess.state.stage.value,
started_at=_iso(sess.created_at) or "",
ended_at=_iso(sess.ended_at),
score=_avg(scores),
rapport=_avg(rapports),
technique_count=technique_count,
watch_count=watch_count,
)
def _build_learner_growth(sessions: list[InProcSession]) -> list[TeacherLearnerGrowth]:
grouped: dict[str, list[InProcSession]] = {}
for sess in sessions:
grouped.setdefault(sess.learner_id, []).append(sess)
result: list[TeacherLearnerGrowth] = []
for learner_id, learner_sessions in grouped.items():
ordered = sorted(learner_sessions, key=lambda sess: sess.created_at)
points = [_session_growth_point(sess) for sess in ordered]
scored = [point for point in points if point.score is not None]
rapport_values = [point.rapport for point in points if point.rapport is not None]
technique_counts: dict[str, int] = {}
for sess in ordered:
for turn in sess.turns:
if turn.speaker != "counselor":
continue
ev = _turn_eval(turn)
if ev is None:
continue
for label in _turn_techniques(ev):
technique_counts[label] = technique_counts.get(label, 0) + 1
first_score = scored[0].score if scored else None
latest_score = scored[-1].score if scored else None
score_delta: float | None = None
trend = "insufficient"
if first_score is not None and latest_score is not None:
score_delta = round(latest_score - first_score, 3)
if len(scored) >= 2:
if score_delta >= 0.1:
trend = "up"
elif score_delta <= -0.1:
trend = "down"
else:
trend = "flat"
latest_session = ordered[-1]
top_techniques = [
label
for label, _count in sorted(
technique_counts.items(),
key=lambda item: (-item[1], item[0]),
)[:3]
]
result.append(
TeacherLearnerGrowth(
learner_id=learner_id,
learner_label=_learner_label(learner_id),
sessions=len(ordered),
ended_sessions=sum(1 for sess in ordered if sess.ended),
latest_at=_iso(latest_session.ended_at or latest_session.created_at) or "",
first_score=first_score,
latest_score=latest_score,
score_delta=score_delta,
avg_score=_avg([point.score for point in scored if point.score is not None]),
avg_rapport=_avg([value for value in rapport_values if value is not None]),
trend=trend,
top_techniques=top_techniques,
points=points[-6:],
)
)
return sorted(result, key=lambda item: item.latest_at, reverse=True)[:12]
def _summary(sess: InProcSession) -> TeacherSessionSummary:
learner_turns = sum(1 for turn in sess.turns if turn.speaker == "counselor")
client_turns = sum(1 for turn in sess.turns if turn.speaker == "client")
@ -79,13 +275,45 @@ def _summary(sess: InProcSession) -> TeacherSessionSummary:
@router.get("/dashboard", response_model=TeacherDashboardResponse)
async def teacher_dashboard(principal: TeacherPrincipal) -> TeacherDashboardResponse:
"""Return teacher-visible dashboard data from real sessions only."""
sessions, durable = await session_persistence.list_sessions(principal)
sessions, durable = await session_persistence.list_sessions(
principal,
include_turn_evaluation=True,
)
if not durable:
require_runtime_fallback_allowed("teacher dashboard")
sessions = sorted(store.list(), key=lambda sess: sess.created_at, reverse=True)
summaries = [_summary(sess) for sess in sessions]
pending_reviews = [item for item in summaries if item.status == "ended"]
learners = {sess.learner_id for sess in sessions}
learner_growth = _build_learner_growth(sessions)
safety_alerts: list[TeacherSafetyAlert] = []
if durable:
raw_alerts, alerts_durable = await session_persistence.list_safety_alerts(principal)
if alerts_durable:
safety_alerts = [
TeacherSafetyAlert(
id=str(item.get("id") or ""),
session_id=str(item.get("session_id") or ""),
learner_id=str(item.get("learner_id") or ""),
learner_label=str(item.get("learner_label") or "학습자"),
persona_code=str(item.get("persona_code") or ""),
session_no=int(item.get("session_no") or 0),
trigger_type=str(item.get("trigger_type") or "crisis"),
ko_risk_level=int(item.get("ko_risk_level") or 0),
escalated=bool(item.get("escalated")),
created_at=str(item.get("created_at") or ""),
resource_title=str(
(item.get("detail") or {}).get("crisis_resource", {}).get(
"title",
"자살예방상담전화 109",
)
),
resource_number=str(
(item.get("detail") or {}).get("crisis_resource", {}).get("number", "109")
),
)
for item in raw_alerts
]
if sessions:
message = "현재 기록된 실제 학습 세션만 표시합니다."
@ -97,6 +325,8 @@ async def teacher_dashboard(principal: TeacherPrincipal) -> TeacherDashboardResp
total_learners=len(learners),
active_sessions=sum(1 for sess in sessions if not sess.ended),
ended_sessions=sum(1 for sess in sessions if sess.ended),
safety_alerts=safety_alerts,
learner_growth=learner_growth,
pending_reviews=pending_reviews[:20],
recent_sessions=summaries[:20],
message=message,

View file

@ -22,14 +22,14 @@ from fastapi import APIRouter, WebSocket, WebSocketDisconnect
from fastapi.responses import JSONResponse
from starlette.websockets import WebSocketState
from .. import session_persistence
from .. import session_persistence, turn_runtime
from ..auth_sessions import get_session
from ..config import settings
from ..deps import Principal, Role
from ..engine_client import EngineError, engine_client
from ..persona_repository import get_catalog_persona
from ..runtime_policy import require_runtime_fallback_allowed, runtime_fallback_allowed
from ..services import evaluator, memory, orchestrator, state_machine
from ..runtime_policy import require_runtime_fallback_allowed
from ..services import evaluator, orchestrator, state_machine
from ..services import voice as voice_svc
from ..services.voice import VoicePreset, VoiceUnavailable, resolve_voice, voice_service
from ..store import InProcSession, TurnRecord, store
@ -292,7 +292,10 @@ async def _run_turn_and_speak(
await _safe_send_json(websocket, {"type": "state", "state": "idle"})
return
recall = memory.RecallContext()
from . import sessions as session_routes
recall = await session_routes.ensure_recall_context(sess)
kb_cues = session_routes._KB_CUES_CACHE.get(session_id) or []
ctx = orchestrator.prepare_turn(
session_id=session_id,
case_id=sess.case_id,
@ -302,6 +305,7 @@ async def _run_turn_and_speak(
recall_summary=recall.recall_summary,
pinned_facts=recall.pinned_facts,
recent_turns=sess.recent_turns(visible_to="client"),
kb_behavior_cues=kb_cues,
theory_mode=sess.theory_mode,
)
assert ctx.state_after is not None
@ -311,7 +315,11 @@ async def _run_turn_and_speak(
result = await orchestrator.run_turn_generate(
ctx,
engine_client,
eval_hook=evaluator.make_eval_hook(engine_client),
eval_hook=evaluator.make_eval_hook(
engine_client,
audit_hook=session_persistence.record_llm_call_audit,
),
audit_hook=session_persistence.record_llm_call_audit,
)
except EngineError as e:
await _safe_send_json(websocket, {"type": "error", "detail": f"engine unavailable: {e}"})
@ -321,12 +329,15 @@ async def _run_turn_and_speak(
reply = result.client_reply or ""
# Persist only after the client reply has been generated. A failed AI turn
# must not leave a learner-only transcript in review or history.
await _append_voice_turn(
await turn_runtime.record_completed_turn(
sess,
TurnRecord(
ctx,
result,
context_prefix="voice session",
counselor_turn=TurnRecord(
turn_seq=ctx.state_after.turn_seq,
speaker="counselor",
stage=ctx.state_after.stage.value,
stage=turn_runtime.stage_label(ctx.state_after.stage),
text=learner_text,
text_masked=ctx.learner_text_masked,
audio_ref=audio_ref,
@ -336,24 +347,7 @@ async def _run_turn_and_speak(
evaluation=result.evaluation,
),
)
if reply:
# Persist the generated client reply before TTS playback.
await _append_voice_turn(
sess,
TurnRecord(
turn_seq=result.turn_seq,
speaker="client",
stage=result.stage,
text=reply,
text_masked=reply,
llm_provider=result.llm_provider,
model=result.model,
tokens_in=result.tokens_in,
tokens_out=result.tokens_out,
cost_usd=result.cost_usd,
),
)
await _update_voice_state(sess, result.state_after)
await turn_runtime.record_safety_event(sess, ctx, result)
# Send the final client text before audio playback.
await _safe_send_json(
@ -367,6 +361,8 @@ async def _run_turn_and_speak(
"turn_seq": result.turn_seq,
"safety_flagged": result.safety_flagged,
"crisis_kind": result.crisis_kind,
"crisis_resource": result.crisis_resource,
"conversation_stopped": result.conversation_stopped,
},
)
@ -403,49 +399,17 @@ async def _load_voice_session(
session_id: str,
principal: Principal,
) -> tuple[InProcSession | None, str | None]:
sess = await session_persistence.load_session(session_id, principal, allow_ended=True)
if sess is not None:
store.put(sess)
elif runtime_fallback_allowed():
sess = store.get(session_id)
if sess is None:
sess, err = await turn_runtime.load_owned_session(session_id, principal)
if err == turn_runtime.SessionAccessError.NOT_FOUND:
return None, f"unknown session {session_id}"
if sess.learner_id != principal.user_id:
if err == turn_runtime.SessionAccessError.FORBIDDEN:
return None, "session does not belong to user"
if sess.ended:
if err == turn_runtime.SessionAccessError.ENDED:
return None, "session already ended"
assert sess is not None
return sess, None
async def _append_voice_turn(sess: InProcSession, turn: TurnRecord) -> None:
if await session_persistence.append_turn(
session_id=sess.session_id,
learner_id=sess.learner_id,
turn=turn,
):
sess.turns.append(turn)
store.put(sess)
return
require_runtime_fallback_allowed("voice session turn append")
store.append_turn(sess.session_id, turn)
async def _update_voice_state(
sess: InProcSession,
state: state_machine.SessionState,
) -> None:
if await session_persistence.update_state(
session_id=sess.session_id,
learner_id=sess.learner_id,
state=state,
):
sess.state = state
store.put(sess)
return
require_runtime_fallback_allowed("voice session state update")
store.update_state(sess.session_id, state)
async def _principal_from_websocket(websocket: WebSocket) -> Principal | None:
"""Restore the same server-side browser session used by REST routes."""
raw_cookie = websocket.cookies.get(settings.cookie_name)

View file

@ -41,13 +41,24 @@ SAML_ATTRIBUTE_DISPLAY_NAME_NAMES = {
"cn",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
}
SAML_ATTRIBUTE_COHORT_NAMES = {
"cohort",
"cohort_id",
"cohortIds",
"cohorts",
"class",
"group",
"groups",
}
@dataclass(frozen=True, slots=True)
class SamlIdentity:
subject: str
email: str
display_name: str
role_hint: str | None = None
cohort_hint: str | None = None
def acs_url_for_entity_id(entity_id: str) -> str:
@ -120,7 +131,14 @@ def parse_fixture_response(encoded_response: str) -> SamlIdentity:
or email
)
role_hint = _first_attribute(attributes, SAML_ATTRIBUTE_ROLE_NAMES)
return SamlIdentity(email=email, display_name=display_name or email, role_hint=role_hint)
cohort_hint = _first_attribute(attributes, SAML_ATTRIBUTE_COHORT_NAMES)
return SamlIdentity(
subject=name_id or email,
email=email,
display_name=display_name or email,
role_hint=role_hint,
cohort_hint=cohort_hint or None,
)
def _first_text(root: ElementTree.Element, selector: str) -> str:

View file

@ -0,0 +1,400 @@
"""Phase 3 recursive-learning dataset export helpers.
The exporter is intentionally conservative: it only emits masked text, keeps raw
database identifiers out of JSONL records, and never upgrades an artifact to an
approved seed dataset unless the explicit approval and agreement gates pass.
"""
from __future__ import annotations
import hashlib
import json
import math
import re
from collections import Counter, defaultdict
from dataclasses import dataclass, field
from datetime import UTC, date, datetime
from decimal import Decimal
from pathlib import Path
from typing import Any, Iterable, Mapping, Sequence
from uuid import UUID
DATASET_ITEM_SCHEMA = "phase3_dataset_item_v1"
APPROVED_EXPORT_STATUS = "approved_for_recursive_learning_seed"
DRY_RUN_EXPORT_STATUS = "technical_dry_run"
BLOCKED_EXPORT_STATUS = "blocked"
EXPORT_STATUSES = {APPROVED_EXPORT_STATUS, DRY_RUN_EXPORT_STATUS, BLOCKED_EXPORT_STATUS}
BLOCKED_FIELD_NAMES = {
"name",
"email",
"phone",
"student_id",
"national_id",
"address",
"date_of_birth",
"raw_audio_path",
"raw_voice",
"raw_source_case",
"identity_map",
"api_key",
"api_keys",
"access_token",
"refresh_token",
"token",
"cookie",
"credentials",
"credential",
"secret",
}
PII_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
("email", re.compile(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", re.I)),
(
"phone",
re.compile(r"\b(?:\+?82[-. ]?)?(?:0?1[016789]|0[2-9]\d?)[-. ]?\d{3,4}[-. ]?\d{4}\b"),
),
("national_id", re.compile(r"\b\d{6}[- ]?[1-4]\d{6}\b")),
("student_id", re.compile(r"\b20\d{2}[- ]?\d{4,8}\b")),
(
"secret",
re.compile(
r"(?i)\b(?:api[_-]?key|access[_-]?token|refresh[_-]?token|session[_-]?secret|cookie)\b\s*[:=]\s*\S+"
),
),
("secret", re.compile(r"\b(?:sk-[A-Za-z0-9_-]{12,}|AIza[0-9A-Za-z_-]{20,}|xox[baprs]-[A-Za-z0-9-]+)\b")),
)
@dataclass
class ExportKeyMaps:
participant: dict[str, str] = field(default_factory=dict)
session: dict[str, str] = field(default_factory=dict)
def participant_key(self, raw_id: Any) -> str:
key = str(raw_id or "unknown-participant")
if key not in self.participant:
self.participant[key] = f"PX-{len(self.participant) + 1:04d}"
return self.participant[key]
def session_key(self, raw_id: Any) -> str:
key = str(raw_id or "unknown-session")
if key not in self.session:
self.session[key] = f"SX-{len(self.session) + 1:04d}"
return self.session[key]
def json_safe(value: Any) -> Any:
if isinstance(value, (datetime, date)):
if isinstance(value, datetime) and value.tzinfo is None:
value = value.replace(tzinfo=UTC)
return value.isoformat().replace("+00:00", "Z")
if isinstance(value, (UUID, Decimal)):
return str(value)
if isinstance(value, Mapping):
return {str(key): json_safe(item) for key, item in value.items()}
if isinstance(value, list):
return [json_safe(item) for item in value]
if isinstance(value, tuple):
return [json_safe(item) for item in value]
return value
def normalize_json_value(value: Any) -> Any:
if isinstance(value, str):
stripped = value.strip()
if stripped.startswith(("{", "[")):
try:
return json.loads(stripped)
except json.JSONDecodeError:
return value
return value
def _redacted_sample(kind: str, value: str) -> str:
if kind == "email" and "@" in value:
return f"<email:{value.rsplit('@', 1)[1].lower()}>"
return f"<{kind}>"
def _scan_text(value: str, path: str) -> list[dict[str, Any]]:
findings: list[dict[str, Any]] = []
for kind, pattern in PII_PATTERNS:
for match in pattern.finditer(value):
findings.append(
{
"kind": kind,
"path": path,
"sample": _redacted_sample(kind, match.group(0)),
}
)
return findings
def scan_for_pii(value: Any, path: str = "$") -> list[dict[str, Any]]:
findings: list[dict[str, Any]] = []
if isinstance(value, Mapping):
for raw_key, item in value.items():
key = str(raw_key)
next_path = f"{path}.{key}"
if key.lower() in BLOCKED_FIELD_NAMES:
findings.append({"kind": "blocked_field", "path": next_path, "sample": f"<{key.lower()}>"})
findings.extend(scan_for_pii(item, next_path))
return findings
if isinstance(value, list):
for index, item in enumerate(value):
findings.extend(scan_for_pii(item, f"{path}[{index}]"))
return findings
if isinstance(value, str):
findings.extend(_scan_text(value, path))
return findings
def build_dataset_record(
row: Mapping[str, Any],
*,
item_index: int,
export_manifest_id: str,
keys: ExportKeyMaps,
pii_scan_status: str = "pending",
consent_scope: str = "recursive_learning_seed",
) -> dict[str, Any]:
text_masked = str(row.get("text_masked") or "").strip()
if not text_masked:
raise ValueError("dataset export requires non-empty text_masked")
participant_key = keys.participant_key(row.get("learner_id"))
session_key = keys.session_key(row.get("session_id"))
persona_code = row.get("persona_code") or row.get("persona_id") or "unknown"
return {
"schema": DATASET_ITEM_SCHEMA,
"item_id": f"DI-{item_index:06d}",
"participant_key": participant_key,
"session_key": session_key,
"turn_key": f"TX-{item_index:06d}",
"persona_id": str(persona_code),
"stage": row.get("stage") or "",
"speaker": row.get("speaker") or "",
"text_masked": text_masked,
"techniques": json_safe(normalize_json_value(row.get("techniques") or [])),
"client_states": json_safe(normalize_json_value(row.get("client_states") or [])),
"feedback_scores": json_safe(normalize_json_value(row.get("feedback_scores") or [])),
"supervisor_comments": json_safe(normalize_json_value(row.get("supervisor_comments") or [])),
"source_refs": {
"session_started_at": json_safe(row.get("session_started_at") or row.get("started_at")),
"export_manifest_id": export_manifest_id,
},
"privacy": {
"direct_identifiers_removed": True,
"pii_scan_status": pii_scan_status,
"consent_scope": consent_scope,
},
}
def write_jsonl(records: Sequence[Mapping[str, Any]], path: Path) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
with path.open("w", encoding="utf-8", newline="\n") as handle:
for record in records:
handle.write(json.dumps(json_safe(record), ensure_ascii=False, sort_keys=True, separators=(",", ":")))
handle.write("\n")
def sha256_file(path: Path) -> str:
digest = hashlib.sha256()
with path.open("rb") as handle:
for chunk in iter(lambda: handle.read(1024 * 1024), b""):
digest.update(chunk)
return digest.hexdigest()
def cohen_kappa(annotations: Iterable[Mapping[str, Any]], label_key: str) -> float | None:
pairs: list[tuple[Any, Any]] = []
by_item: dict[Any, list[Any]] = defaultdict(list)
for annotation in annotations:
labels = normalize_json_value(annotation.get("labels") or {})
if not isinstance(labels, Mapping) or label_key not in labels:
continue
by_item[annotation.get("item_id")].append(labels[label_key])
for values in by_item.values():
if len(values) >= 2:
pairs.append((values[0], values[1]))
if not pairs:
return None
total = len(pairs)
observed = sum(1 for left, right in pairs if left == right) / total
left_counts = Counter(left for left, _ in pairs)
right_counts = Counter(right for _, right in pairs)
expected = sum((left_counts[label] / total) * (right_counts[label] / total) for label in set(left_counts) | set(right_counts))
if math.isclose(1.0, expected):
return 1.0 if math.isclose(1.0, observed) else None
return round((observed - expected) / (1.0 - expected), 4)
def intraclass_correlation(annotations: Iterable[Mapping[str, Any]], score_key: str) -> float | None:
by_item: dict[Any, list[float]] = defaultdict(list)
for annotation in annotations:
labels = normalize_json_value(annotation.get("labels") or {})
if not isinstance(labels, Mapping) or score_key not in labels:
continue
try:
by_item[annotation.get("item_id")].append(float(labels[score_key]))
except (TypeError, ValueError):
continue
matrix = [values[:2] for values in by_item.values() if len(values) >= 2]
if len(matrix) < 2:
return None
n = len(matrix)
k = 2
row_means = [sum(row) / k for row in matrix]
col_means = [sum(row[col] for row in matrix) / n for col in range(k)]
grand_mean = sum(row_means) / n
msr = k * sum((mean - grand_mean) ** 2 for mean in row_means) / (n - 1)
msc = n * sum((mean - grand_mean) ** 2 for mean in col_means) / (k - 1)
residual = 0.0
for row_index, row in enumerate(matrix):
for col_index, value in enumerate(row):
residual += (value - row_means[row_index] - col_means[col_index] + grand_mean) ** 2
mse = residual / ((n - 1) * (k - 1))
denominator = msr + (k - 1) * mse + (k * (msc - mse) / n)
if math.isclose(denominator, 0.0):
return None
return round((msr - mse) / denominator, 4)
def infer_source_window(records: Sequence[Mapping[str, Any]]) -> dict[str, Any]:
starts = [record.get("source_refs", {}).get("session_started_at") for record in records]
starts = [value for value in starts if value]
return {
"started_at": min(starts) if starts else "",
"ended_at": max(starts) if starts else "",
}
def build_manifest(
*,
export_id: str,
dataset_name: str,
export_status: str,
purpose: str,
records: Sequence[Mapping[str, Any]],
jsonl_path: str,
jsonl_sha256: str,
pii_findings: Sequence[Mapping[str, Any]],
participants_included: int,
participants_excluded: int = 0,
cohort_id: str = "phase3",
consent_version: str = "",
agreement: Mapping[str, Any] | None = None,
approvals: Mapping[str, str] | None = None,
known_limitations: Sequence[str] | None = None,
created_at: datetime | None = None,
) -> dict[str, Any]:
if export_status not in EXPORT_STATUSES:
raise ValueError(f"unsupported export_status: {export_status}")
agreement_payload = {
"kappa": None,
"icc": None,
"gold_status": "not_gold",
}
if agreement:
agreement_payload.update(dict(agreement))
approvals_payload = {
"data_steward": "",
"legal_or_privacy_reviewer": "",
"technical_operator": "",
"approved_at": "",
}
if approvals:
approvals_payload.update({key: value for key, value in approvals.items() if value is not None})
pii_status = "pass" if not pii_findings else "fail"
limitations = list(known_limitations or [])
if export_status != APPROVED_EXPORT_STATUS:
limitations.append("technical dry-run only; data-steward/legal approval is not complete")
if pii_findings:
limitations.append("PII scan found records requiring reviewer disposition")
manifest = {
"export_id": export_id,
"dataset_name": dataset_name,
"export_status": export_status,
"created_at": json_safe(created_at or datetime.now(UTC)),
"purpose": purpose,
"source_window": infer_source_window(records),
"source_tables": [
"app.sessions",
"app.turns",
"app.feedback_scores",
"app.turn_technique",
"app.turn_client_state",
"app.supervisor_comment",
"ds.annotation",
"ds.export_manifest",
],
"selection_criteria": {
"cohort_id": cohort_id,
"min_completed_sessions": 0,
"include_withdrawn": False,
"excluded_safety_scope": ["self_harm_scenario_primary"],
},
"consent_scope": {
"consent_version": consent_version,
"allowed_uses": ["education_quality_review", "recursive_learning_seed"],
"withdrawal_cutoff_applied_at": "",
"participants_included": participants_included,
"participants_excluded": participants_excluded,
},
"anonymization": {
"participant_key": "pseudonymous export key; no identity map included",
"text_transform": "masked_text_only",
"direct_identifier_policy": "blocked",
"salt_or_identity_map_location": "not in export",
},
"pii_scan": {
"tool": "vignette.dataset_export.regex",
"version": "1",
"ran_at": json_safe(datetime.now(UTC)),
"status": pii_status,
"findings": [json_safe(finding) for finding in pii_findings],
},
"agreement": agreement_payload,
"files": [
{
"path": jsonl_path,
"rows": len(records),
"sha256": jsonl_sha256,
"schema": DATASET_ITEM_SCHEMA,
}
],
"approvals": approvals_payload,
"known_limitations": sorted(set(limitations)),
}
validate_manifest_gate(manifest)
return manifest
def validate_manifest_gate(manifest: Mapping[str, Any]) -> None:
if manifest.get("export_status") != APPROVED_EXPORT_STATUS:
return
errors: list[str] = []
pii_scan = manifest.get("pii_scan") or {}
agreement = manifest.get("agreement") or {}
approvals = manifest.get("approvals") or {}
if pii_scan.get("status") != "pass":
errors.append("PII scan must pass")
if (agreement.get("kappa") or 0) < 0.60:
errors.append("kappa must be >= 0.60")
if (agreement.get("icc") or 0) < 0.75:
errors.append("ICC must be >= 0.75")
for key in ("data_steward", "legal_or_privacy_reviewer", "technical_operator", "approved_at"):
if not str(approvals.get(key) or "").strip():
errors.append(f"approval missing: {key}")
if errors:
raise ValueError("; ".join(errors))

View file

@ -26,6 +26,7 @@ from __future__ import annotations
import json
import os
import time
from typing import TYPE_CHECKING, Any, Optional
from pydantic import BaseModel, Field
@ -48,7 +49,7 @@ from ..taxonomy import (
)
if TYPE_CHECKING: # 런타임 import 회피(순환·소유권 경계). 타입 힌트 전용.
from .orchestrator import TurnContext
from .orchestrator import LlmAuditHook, TurnContext
# ════════════════════════════════════════════════════════════════════════════
@ -624,6 +625,7 @@ async def evaluate_turn(
client_reply: str,
*,
engine: EngineClient,
audit_hook: Optional["LlmAuditHook"] = None,
) -> TurnEvaluation:
"""fast-loop 턴 평가 — 턴 직후 경량 4차원 태깅(비치명적).
@ -644,7 +646,20 @@ async def evaluate_turn(
session_id=ctx.session_id,
metadata={"loop": "fast", "stage": st.stage.value, "turn_seq": st.turn_seq},
)
started = time.perf_counter()
resp = await engine.generate(req)
latency_ms = int((time.perf_counter() - started) * 1000)
await _record_llm_audit(
audit_hook,
session_id=ctx.session_id,
provider=resp.provider,
model=resp.model,
tokens_in=resp.tokens_in,
tokens_out=resp.tokens_out,
cost_usd=resp.cost_usd,
inference_geo=resp.inference_geo,
latency_ms=latency_ms,
)
except EngineError as e:
base.error = f"engine_error: {e}"
return base
@ -672,6 +687,7 @@ async def evaluate_session(
technique_codes: Optional[list[str]] = None,
theory_mode: Optional[str] = None,
scope: str = "session_end",
audit_hook: Optional["LlmAuditHook"] = None,
) -> SessionEvaluation:
"""deep-loop 정밀 평가 — 단계전환/회기말. 전체 축어록 + 코드 집계 분포 + LLM 정성 평가.
@ -706,7 +722,20 @@ async def evaluate_session(
session_id=session_id,
metadata={"loop": "deep", "scope": scope, "stage": stage},
)
started = time.perf_counter()
resp = await engine.generate(req)
latency_ms = int((time.perf_counter() - started) * 1000)
await _record_llm_audit(
audit_hook,
session_id=session_id,
provider=resp.provider,
model=resp.model,
tokens_in=resp.tokens_in,
tokens_out=resp.tokens_out,
cost_usd=resp.cost_usd,
inference_geo=resp.inference_geo,
latency_ms=latency_ms,
)
except EngineError as e:
base.error = f"engine_error: {e}"
return base
@ -736,7 +765,23 @@ async def evaluate_session(
# ════════════════════════════════════════════════════════════════════════════
# 7. orchestrator EvalHook 어댑터 — 주입형 클로저(엔진 바인딩)
# ════════════════════════════════════════════════════════════════════════════
def make_eval_hook(engine: EngineClient):
async def _record_llm_audit(
audit_hook: Optional["LlmAuditHook"],
**payload: Any,
) -> None:
if audit_hook is None:
return
try:
await audit_hook(payload)
except Exception:
return
def make_eval_hook(
engine: EngineClient,
*,
audit_hook: Optional["LlmAuditHook"] = None,
):
"""orchestrator.EvalHook(Callable[[TurnContext, str], Awaitable[Optional[dict]]]) 호환 클로저.
sessions 라우트가 run_turn_generate(ctx, engine, eval_hook=make_eval_hook(engine_client)) 로
@ -744,7 +789,7 @@ def make_eval_hook(engine: EngineClient):
"""
async def _hook(ctx: "TurnContext", client_reply: str) -> Optional[dict[str, Any]]:
ev = await evaluate_turn(ctx, client_reply, engine=engine)
ev = await evaluate_turn(ctx, client_reply, engine=engine, audit_hook=audit_hook)
d = ev.to_hook_dict()
return d if d else None

View file

@ -23,6 +23,12 @@ from typing import Optional
# ── 출력 가드레일 상한 (R5) ──────────────────────────────
IDEATION_STAGE_CAP = 3 # 내담자 발화/상태가 넘을 수 없는 자살사고 단계 상한
CRISIS_HOTLINE_NUMBER = "109"
CRISIS_HOTLINE_LABEL = "자살예방상담전화 109"
CRISIS_RESOURCE_MESSAGE = (
"지금은 연습을 멈추고 실제 안전 확인이 먼저입니다. 즉시 위험하면 119 또는 가까운 "
"응급실에 연락하고, 자살예방상담전화 109로 도움을 요청하세요."
)
# ════════════════════════════════════════════════════════════════════════════
@ -224,8 +230,20 @@ def clamp_ideation(stage: int) -> int:
return max(1, min(IDEATION_STAGE_CAP, stage))
def crisis_resource() -> dict[str, str]:
"""LLM 밖 위기 안내 리소스. UI/API 응답에 그대로 실어 보낸다."""
return {
"title": CRISIS_HOTLINE_LABEL,
"number": CRISIS_HOTLINE_NUMBER,
"message": CRISIS_RESOURCE_MESSAGE,
}
__all__ = [
"IDEATION_STAGE_CAP",
"CRISIS_HOTLINE_NUMBER",
"CRISIS_HOTLINE_LABEL",
"CRISIS_RESOURCE_MESSAGE",
"MaskResult",
"mask_pii",
"CrisisKind",
@ -234,4 +252,5 @@ __all__ = [
"OutputGuardResult",
"sanitize_client_reply",
"clamp_ideation",
"crisis_resource",
]

View file

@ -19,6 +19,7 @@ MASTERPLAN §2.2 / MEMORY_DESIGN §2-B 턴 사이클:
from __future__ import annotations
import time
from dataclasses import dataclass, field
from typing import Any, AsyncIterator, Awaitable, Callable, Optional
@ -37,6 +38,7 @@ from .state_machine import SessionState, Stage
# 평가 훅 타입: U_t(수련생 마스킹 발화) + 내담자응답 + 상태 → 평가 결과(dict)
# Features evaluator 가 이 시그니처에 맞춰 함수를 주입한다(여기선 호출만).
EvalHook = Callable[["TurnContext", str], Awaitable[Optional[dict]]]
LlmAuditHook = Callable[[dict[str, Any]], Awaitable[None]]
@dataclass(slots=True)
@ -84,6 +86,8 @@ class TurnResult:
state_after: SessionState
evaluation: Optional[dict] = None
crisis_kind: str = "none"
crisis_resource: Optional[dict[str, str]] = None
conversation_stopped: bool = False
llm_provider: Optional[str] = None
model: Optional[str] = None
tokens_in: int = 0
@ -161,6 +165,7 @@ def prepare_turn(
pinned_facts=ctx.pinned_facts,
recent_turns=ctx.recent_turns,
kb_behavior_cues=ctx.kb_behavior_cues,
theory_mode=ctx.theory_mode,
)
return ctx
@ -192,6 +197,7 @@ async def run_turn_generate(
engine: EngineClient,
*,
eval_hook: Optional[EvalHook] = None,
audit_hook: Optional[LlmAuditHook] = None,
) -> TurnResult:
"""동기 턴 실행(4~8). 내담자 응답을 한 번에 받아 가드레일·평가 순차 적용.
@ -200,6 +206,9 @@ async def run_turn_generate(
assert ctx.state_after is not None
st = ctx.state_after
if ctx.crisis is not None and ctx.crisis.escalate:
return _crisis_gate_result(ctx)
# 4) 내담자 AI 생성
req = GenerateRequest(
ai_role="client",
@ -207,7 +216,20 @@ async def run_turn_generate(
session_id=ctx.session_id,
metadata={"stage": st.stage.value},
)
started = time.perf_counter()
resp: GenerateResponse = await engine.generate(req)
latency_ms = int((time.perf_counter() - started) * 1000)
await _record_llm_audit(
audit_hook,
session_id=ctx.session_id,
provider=resp.provider,
model=resp.model,
tokens_in=resp.tokens_in,
tokens_out=resp.tokens_out,
cost_usd=resp.cost_usd,
inference_geo=resp.inference_geo,
latency_ms=latency_ms,
)
reply = resp.text
# 5) 출력 가드레일 — 수단 차단 + ideation 상한
@ -242,6 +264,24 @@ async def run_turn_generate(
)
def _crisis_gate_result(ctx: TurnContext) -> TurnResult:
"""실제 위기 신호는 LLM 호출 전에 중단하고 109 리소스를 반환한다."""
assert ctx.state_after is not None
crisis = ctx.crisis
return TurnResult(
turn_seq=ctx.state_after.turn_seq,
stage=ctx.state_after.stage.value,
effective_openness=ctx.state_after.effective_openness,
client_reply=None,
safety_flagged=True,
state_after=ctx.state_after,
evaluation=None,
crisis_kind=crisis.kind.value if crisis else "learner_real",
crisis_resource=guardrail.crisis_resource(),
conversation_stopped=True,
)
# ════════════════════════════════════════════════════════════════════════════
# 4~8단계 — SSE 스트림 경로 (기본 UX)
# ════════════════════════════════════════════════════════════════════════════
@ -256,6 +296,8 @@ class StreamEvent:
async def run_turn_stream(
ctx: TurnContext,
engine: EngineClient,
*,
audit_hook: Optional[LlmAuditHook] = None,
) -> AsyncIterator[StreamEvent]:
"""스트리밍 턴 실행(4~8). 게이트웨이 SSE 를 받아 token/done/safety/error 로 재방출.
@ -277,10 +319,34 @@ async def run_turn_stream(
stream_meta: dict[str, Any] = {}
if ctx.crisis is not None and ctx.crisis.escalate:
flagged = True
yield StreamEvent("safety", {"reason": "learner_real_crisis", "level": ctx.crisis.risk_level})
resource = guardrail.crisis_resource()
yield StreamEvent(
"safety",
{
"reason": "learner_real_crisis",
"level": ctx.crisis.risk_level,
"crisis_resource": resource,
"conversation_stopped": True,
},
)
yield StreamEvent(
"done",
{
"session_id": ctx.session_id,
"stage": st.stage.value,
"effective_openness": round(st.effective_openness, 4),
"turn_seq": st.turn_seq,
"safety_flagged": True,
"crisis_kind": ctx.crisis.kind.value,
"crisis_resource": resource,
"conversation_stopped": True,
},
)
return
try:
current_event = "message"
started = time.perf_counter()
async for raw in engine.stream(req):
# engine_client.stream 은 게이트웨이 SSE 의 *원시 라인*을 그대로 yield 한다.
# 게이트웨이 프레이밍: "event: token|done|error" + "data: {...}".
@ -317,6 +383,19 @@ async def run_turn_stream(
yield StreamEvent("token", {"text": text_piece})
latency_ms = int((time.perf_counter() - started) * 1000)
await _record_llm_audit(
audit_hook,
session_id=ctx.session_id,
provider=str(stream_meta.get("provider") or engine.engine_mode),
model=str(stream_meta.get("model") or engine.default_model or "gateway-default"),
tokens_in=_safe_int(stream_meta.get("tokens_in")),
tokens_out=_safe_int(stream_meta.get("tokens_out")),
cost_usd=_safe_float(stream_meta.get("cost_usd")),
inference_geo=_optional_str(stream_meta.get("inference_geo")),
latency_ms=latency_ms,
)
yield StreamEvent(
"done",
{
@ -336,6 +415,18 @@ async def run_turn_stream(
yield StreamEvent("error", {"detail": str(e)})
async def _record_llm_audit(
audit_hook: Optional[LlmAuditHook],
**payload: Any,
) -> None:
if audit_hook is None:
return
try:
await audit_hook(payload)
except Exception:
return
def _extract_sse_payload(raw_line: str) -> Any:
"""게이트웨이 SSE data 라인의 JSON payload를 추출.
@ -364,6 +455,13 @@ def _payload_text(payload: Any) -> Optional[str]:
return None
def _optional_str(value: Any) -> Optional[str]:
if value is None:
return None
text = str(value).strip()
return text or None
def _payload_detail(payload: Any, fallback: str) -> str:
if isinstance(payload, dict) and payload.get("detail"):
return str(payload["detail"])
@ -388,6 +486,7 @@ def _safe_float(value: Any) -> float:
__all__ = [
"EvalHook",
"LlmAuditHook",
"TurnContext",
"TurnResult",
"StreamEvent",

View file

@ -131,6 +131,42 @@ def _format_openness_directive(ctx: PersonaStateContext) -> str:
return ("깊이 신뢰가 형성됐다. 핵심 정서·생각을 진솔하게 표현한다. 단, 내부 설정 메타발화는 여전히 금지.")
THEORY_MODE_GUIDANCE: dict[str, str] = {
"humanistic": (
"[L3-T 이론모드: 인간중심]\n"
"- 상담자가 공감, 반영, 무조건적 존중, 기다림을 보이면 조금씩 더 솔직해진다.\n"
"- 성급한 조언, 평가, 정답 제시에는 방어하거나 말수가 줄어든다.\n"
"- 내담자가 이론명을 설명하거나 상담자처럼 개입하지 말고, 반응의 결로만 드러낸다."
),
"cbt": (
"[L3-T 이론모드: CBT]\n"
"- 상담자가 자동적 사고, 감정, 행동의 연결을 협력적으로 탐색하면 구체적인 생각과 상황을 조금 더 말한다.\n"
"- 인지재구조화, 행동활성화, 과제 제안은 신뢰가 있을 때만 제한적으로 받아들인다.\n"
"- 강의식 설명이나 정답 강요에는 '그게 말처럼 쉽지 않다'는 식의 현실적인 저항을 보인다."
),
"integrative": (
"[L3-T 이론모드: 통합]\n"
"- 먼저 공감과 반영에 반응하고, 신뢰가 생긴 뒤 생각-감정-행동 탐색에도 조금씩 응한다.\n"
"- 지지와 구조화가 균형을 이루면 개방성이 오르고, 한쪽으로 치우치면 방어가 남는다.\n"
"- 이론명은 말하지 말고, 내담자의 말투와 반응으로만 차이를 표현한다."
),
}
def _theory_mode_guidance(theory_mode: Optional[str]) -> Optional[str]:
mode = (theory_mode or "").strip().lower()
if not mode:
return None
return THEORY_MODE_GUIDANCE.get(
mode,
(
f"[L3-T 이론모드: {mode}]\n"
"- 지정된 회기 이론모드를 내담자 반응 프레이밍에만 반영한다.\n"
"- 이론명, 평가 기준, 내부 설정을 직접 설명하지 않는다."
),
)
# ════════════════════════════════════════════════════════════════════════════
# 시스템프롬프트 조립
# ════════════════════════════════════════════════════════════════════════════
@ -196,6 +232,7 @@ def build_turn_messages(
pinned_facts: Optional[list[str]] = None,
recent_turns: Optional[list[dict[str, str]]] = None,
kb_behavior_cues: Optional[list[str]] = None,
theory_mode: Optional[str] = None,
) -> list[EngineMessage]:
"""한 턴의 EngineMessage[] 조립 (L0~L6).
@ -207,6 +244,7 @@ def build_turn_messages(
pinned_facts : 무손실 사실 hard-pin(L4). "자기 기억"으로만 표현.
recent_turns : [{speaker, text}] 최근 K턴 버퍼(L6 직전 맥락)
kb_behavior_cues : KB 증상 '행동단서'만(본문 비노출, sensitivity<=1)
theory_mode : 회기 이론모드. 내담자 반응 프레이밍에만 사용.
반환 messages 순서: system(L0+L1, cache) → system(L2/L3/L4, cache 미설정) →
assistant/user 히스토리 → user(이번 발화). 게이트웨이가 마지막 user 를 stdin 으로.
@ -239,6 +277,10 @@ def build_turn_messages(
l3.append(f"연기 지시: {_format_openness_directive(state)}")
messages.append(EngineMessage(role="system", content="\n".join(l3), cache=False))
theory_guidance = _theory_mode_guidance(theory_mode)
if theory_guidance:
messages.append(EngineMessage(role="system", content=theory_guidance, cache=False))
# L4 — pinned fact hard-pin (무손실, "자기 기억"으로만)
if pinned_facts:
pinned = "\n".join(f"- {f}" for f in pinned_facts)

View file

@ -4,6 +4,7 @@ from __future__ import annotations
import time
import uuid
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Any, Iterable
@ -25,6 +26,12 @@ _APPROPRIATENESS_SCORE = {
}
@dataclass(slots=True)
class CaseContext:
case_id: str
last_session_no: int
_JOINED_CARD_COLUMNS = (
"card_persona_id",
"card_code",
@ -89,6 +96,16 @@ def _safe_float(value: Any) -> float | None:
return None
def _safe_int(value: Any) -> int | None:
if isinstance(value, bool):
return int(value)
if isinstance(value, int):
return value
if isinstance(value, float):
return int(value)
return None
def _evaluation_loop(evaluation: dict[str, Any]) -> str:
loop = _clean_text(evaluation.get("loop")) or "fast"
return loop if loop in {"fast", "deep"} else "fast"
@ -208,6 +225,25 @@ def _evaluation_comment_rows(evaluation: dict[str, Any] | None) -> list[dict[str
return [{"kind": "critique", "text": note, "intent_deviation": deviation}]
def _evaluation_alternative_rows(evaluation: dict[str, Any] | None) -> list[dict[str, str | None]]:
if not isinstance(evaluation, dict):
return []
alternatives = evaluation.get("alternative_utterances")
if not isinstance(alternatives, list):
return []
rows: list[dict[str, str | None]] = []
for item in alternatives:
if isinstance(item, dict):
suggestion = _clean_text(item.get("suggestion") or item.get("text"))
rationale = _clean_text(item.get("rationale"))
else:
suggestion = _clean_text(item)
rationale = None
if suggestion:
rows.append({"suggestion": suggestion, "rationale": rationale})
return rows
def _appropriateness_from_score(score: Any) -> str:
value = _safe_float(score)
if value is None:
@ -237,6 +273,7 @@ def _rebuild_turn_evaluations(
technique_rows: Iterable[Any],
client_state_rows: Iterable[Any],
comment_rows: Iterable[Any],
alternative_rows: Iterable[Any] = (),
) -> dict[str, dict[str, Any]]:
"""Rehydrate normalized DB rows back into the TurnRecord.evaluation shape."""
refs = {turn_id: (turn_seq, stage) for turn_id, turn_seq, stage in turn_refs}
@ -315,6 +352,14 @@ def _rebuild_turn_evaluations(
if isinstance(deviation, dict):
ensure(turn_id)["intent_deviation"] = deviation
for row in alternative_rows:
turn_id = str(row["turn_id"])
if turn_id not in refs:
continue
suggestion = _clean_text(row["suggestion"])
if suggestion:
ensure(turn_id).setdefault("alternative_utterances", []).append(suggestion)
return evaluations
@ -343,6 +388,47 @@ async def _record_session_read_audit(
)
async def record_llm_call_audit(payload: dict[str, Any]) -> bool:
"""Append provider/token/cost metadata for an external LLM call.
The audit table intentionally stores no prompt or completion text. A DB outage
must not block the counseling loop, so failures are reported as False.
"""
try:
get_pool()
except Exception:
return False
try:
async with acquire(ai_context=True, ai_view="evaluator") as conn:
await conn.execute(
"""
INSERT INTO audit.llm_call_log (
session_id, turn_id, provider, model,
tokens_in, tokens_out, cost_usd,
inference_geo, latency_ms
)
VALUES (
$1::uuid, $2::uuid, $3, $4,
$5, $6, $7,
$8, $9
)
""",
_clean_text(payload.get("session_id")),
_clean_text(payload.get("turn_id")),
_clean_text(payload.get("provider")),
_clean_text(payload.get("model")),
_safe_int(payload.get("tokens_in")),
_safe_int(payload.get("tokens_out")),
_safe_float(payload.get("cost_usd")),
_clean_text(payload.get("inference_geo")),
_safe_int(payload.get("latency_ms")),
)
return True
except Exception:
return False
def _state_from_row(row, card: PersonaCard) -> state_machine.SessionState:
if row is None:
return state_machine.init_state(
@ -474,6 +560,20 @@ async def _persist_turn_evaluation(conn: Any, turn_id: str, evaluation: dict[str
row["intent_deviation"],
)
await conn.execute("DELETE FROM app.alternative_utterance WHERE turn_id = $1::uuid", turn_id)
for row in _evaluation_alternative_rows(evaluation):
await conn.execute(
"""
INSERT INTO app.alternative_utterance (
turn_id, suggestion, rationale
)
VALUES ($1::uuid, $2, $3)
""",
turn_id,
row["suggestion"],
row["rationale"],
)
async def _load_turn_evaluations(
conn: Any,
@ -528,12 +628,22 @@ async def _load_turn_evaluations(
""",
turn_ids,
)
alternative_rows = await conn.fetch(
"""
SELECT turn_id::text AS turn_id, suggestion, rationale
FROM app.alternative_utterance
WHERE turn_id = ANY($1::uuid[])
ORDER BY turn_id, created_at, id
""",
turn_ids,
)
return _rebuild_turn_evaluations(
turn_refs,
feedback_rows=feedback_rows,
technique_rows=technique_rows,
client_state_rows=client_state_rows,
comment_rows=comment_rows,
alternative_rows=alternative_rows,
)
@ -742,7 +852,7 @@ def _session_from_rows(row, state_row, turn_rows: Iterable) -> InProcSession | N
started_at = _ts(row["started_at"]) or time.time()
return InProcSession(
session_id=str(row["id"]),
case_id=str(row["runtime_case_id"] or row["case_id"] or row["id"]),
case_id=str(row["case_id"] or row["runtime_case_id"] or row["id"]),
learner_id=str(row["learner_id"]),
persona_code=persona_code,
theory_mode=row["theory_mode"] or "humanistic",
@ -788,6 +898,34 @@ async def _upsert_state(conn, session_id: str, state: state_machine.SessionState
)
async def get_case_context(
*,
learner_id: str,
persona_id: str,
) -> CaseContext | None:
"""Return the stable learner-persona case row, creating it when possible."""
try:
get_pool()
async with acquire(role="learner", user_id=learner_id) as conn:
row = await conn.fetchrow(
"""
INSERT INTO app.case_profile (persona_id, learner_id)
VALUES ($1::uuid, $2::uuid)
ON CONFLICT (persona_id, learner_id) DO UPDATE SET
updated_at = app.case_profile.updated_at
RETURNING case_id, last_session_no
""",
persona_id,
learner_id,
)
return CaseContext(
case_id=str(row["case_id"]),
last_session_no=int(row["last_session_no"] or 0),
)
except Exception:
return None
async def create_session(
*,
learner_id: str,
@ -798,6 +936,7 @@ async def create_session(
carry_rapport: float = 0.0,
persona_id: str | None = None,
persona_version: int | None = None,
case_id: str | None = None,
) -> InProcSession | None:
"""Create a DB-backed session, returning None when DB persistence is unavailable."""
try:
@ -806,42 +945,74 @@ async def create_session(
pinned_persona_id = persona_id or seed_persona_id(card.code)
pinned_persona_version = persona_version or SEED_VERSION
async with acquire(role="learner", user_id=learner_id) as conn:
row = await conn.fetchrow(
"""
INSERT INTO app.sessions (
runtime_case_id, learner_id, persona_id, persona_version,
persona_code, persona_display_name, persona_difficulty,
session_no, theory_mode, stage_path, prev_rapport_credit
async with conn.transaction():
stable_case_id = case_id
if stable_case_id is None:
case_row = await conn.fetchrow(
"""
INSERT INTO app.case_profile (persona_id, learner_id)
VALUES ($1::uuid, $2::uuid)
ON CONFLICT (persona_id, learner_id) DO UPDATE SET
updated_at = app.case_profile.updated_at
RETURNING case_id, last_session_no
""",
pinned_persona_id,
learner_id,
)
stable_case_id = str(case_row["case_id"])
session_no = int(case_row["last_session_no"] or 0) + 1
counter_row = await conn.fetchrow(
"""
UPDATE app.case_profile
SET last_session_no = GREATEST(last_session_no + 1, $2),
updated_at = now()
WHERE case_id = $1::uuid
AND learner_id = $3::uuid
RETURNING last_session_no
""",
stable_case_id,
session_no,
learner_id,
)
VALUES (
$1::uuid, $2::uuid, $3::uuid, $4,
$5, $6, $7,
$8, $9, '[]'::jsonb, $10
if counter_row is not None:
session_no = int(counter_row["last_session_no"] or session_no)
row = await conn.fetchrow(
"""
INSERT INTO app.sessions (
runtime_case_id, case_id, learner_id, persona_id, persona_version,
persona_code, persona_display_name, persona_difficulty,
session_no, theory_mode, stage_path, prev_rapport_credit
)
VALUES (
$1::uuid, $2::uuid, $3::uuid, $4::uuid, $5,
$6, $7, $8,
$9, $10, '[]'::jsonb, $11
)
RETURNING id, runtime_case_id, case_id, learner_id, persona_code,
session_no, theory_mode, started_at, ended_at, prev_rapport_credit
""",
runtime_case_id,
stable_case_id,
learner_id,
pinned_persona_id,
pinned_persona_version,
card.code,
card.display_name,
card.difficulty,
session_no,
theory_mode,
carry_rapport,
)
RETURNING id, runtime_case_id, case_id, learner_id, persona_code,
session_no, theory_mode, started_at, ended_at, prev_rapport_credit
""",
runtime_case_id,
learner_id,
pinned_persona_id,
pinned_persona_version,
card.code,
card.display_name,
card.difficulty,
session_no,
theory_mode,
carry_rapport,
)
await _upsert_state(conn, str(row["id"]), state)
await _upsert_state(conn, str(row["id"]), state)
return InProcSession(
session_id=str(row["id"]),
case_id=runtime_case_id,
case_id=str(row["case_id"] or row["runtime_case_id"] or row["id"]),
learner_id=learner_id,
persona_code=card.code,
theory_mode=theory_mode,
persona=card,
state=state,
session_no=session_no,
session_no=int(row["session_no"] or session_no),
created_at=_ts(row["started_at"]) or time.time(),
ended_at=None,
turns=[],
@ -1071,7 +1242,11 @@ async def end_session(sess: InProcSession, carry: memory.CarryOver) -> bool:
return False
async def list_sessions(principal: Principal) -> tuple[list[InProcSession], bool]:
async def list_sessions(
principal: Principal,
*,
include_turn_evaluation: bool = False,
) -> tuple[list[InProcSession], bool]:
try:
get_pool()
learner_filter = "WHERE s.learner_id = $1::uuid" if principal.role.value == "learner" else ""
@ -1140,6 +1315,8 @@ async def list_sessions(principal: Principal) -> tuple[list[InProcSession], bool
)
sess = _session_from_rows(row, state_row, turn_rows)
if sess is not None:
if include_turn_evaluation:
await _hydrate_session_turn_evaluations(sess)
sessions.append(sess)
await _record_session_read_audit(
conn,
@ -1156,3 +1333,62 @@ async def list_sessions(principal: Principal) -> tuple[list[InProcSession], bool
except Exception:
require_runtime_fallback_allowed("session list")
return [], False
async def list_safety_alerts(
principal: Principal,
*,
limit: int = 20,
) -> tuple[list[dict[str, Any]], bool]:
"""Teacher/admin-visible crisis alerts from app.safety_events."""
try:
get_pool()
async with acquire(
role=principal.role.value,
user_id=principal.user_id,
cohort_ids=principal.cohort_ids,
) as conn:
rows = await conn.fetch(
"""
SELECT
se.id, se.session_id, se.trigger_type, se.ko_risk_level,
se.escalated, se.detail, se.created_at,
s.learner_id, s.persona_code, s.session_no
FROM app.safety_events se
LEFT JOIN app.sessions s ON s.id = se.session_id
WHERE se.escalated = TRUE
ORDER BY se.created_at DESC
LIMIT $1
""",
limit,
)
return [
{
"id": str(row["id"]),
"session_id": str(row["session_id"]),
"learner_id": str(row["learner_id"] or ""),
"learner_label": _learner_label_from_id(str(row["learner_id"] or "")),
"persona_code": str(row["persona_code"] or ""),
"session_no": int(row["session_no"] or 0),
"trigger_type": str(row["trigger_type"] or "crisis"),
"ko_risk_level": int(row["ko_risk_level"] or 0),
"escalated": bool(row["escalated"]),
"detail": dict(row["detail"] or {}),
"created_at": _iso_dt(row["created_at"]),
}
for row in rows
], True
except Exception:
require_runtime_fallback_allowed("safety alert list")
return [], False
def _learner_label_from_id(learner_id: str) -> str:
suffix = learner_id[-6:] if len(learner_id) > 6 else learner_id
return f"학습자 {suffix}" if suffix else "학습자"
def _iso_dt(value: datetime | None) -> str:
if value is None:
return ""
return value.astimezone(timezone.utc).isoformat()

View file

@ -70,14 +70,20 @@ def _fixture_saml_response(
email: str = "learner@hs.ac.kr",
display_name: str = "SAML Learner",
role: str = "learner",
cohort: str | None = None,
) -> str:
cohort_attr = (
f'\n <saml:Attribute Name="cohort"><saml:AttributeValue>{cohort}</saml:AttributeValue></saml:Attribute>'
if cohort
else ""
)
xml = f"""<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
<saml:Assertion>
<saml:Subject><saml:NameID>{email}</saml:NameID></saml:Subject>
<saml:AttributeStatement>
<saml:Attribute Name="email"><saml:AttributeValue>{email}</saml:AttributeValue></saml:Attribute>
<saml:Attribute Name="displayName"><saml:AttributeValue>{display_name}</saml:AttributeValue></saml:Attribute>
<saml:Attribute Name="role"><saml:AttributeValue>{role}</saml:AttributeValue></saml:Attribute>
<saml:Attribute Name="role"><saml:AttributeValue>{role}</saml:AttributeValue></saml:Attribute>{cohort_attr}
</saml:AttributeStatement>
</saml:Assertion>
</samlp:Response>"""
@ -157,6 +163,25 @@ class AuthProviderScaffoldTest(unittest.IsolatedAsyncioTestCase):
self.assertTrue(config.dev_login_enabled)
async def test_auth_config_keeps_dev_login_closed_for_public_origin(self) -> None:
request = _request(
[
(b"host", b"127.0.0.1:8000"),
(b"origin", b"https://vignette.chanpaca.net"),
(b"x-forwarded-host", b"api-vignette.chanpaca.net"),
(b"x-forwarded-proto", b"https"),
]
)
with patched_settings(
environment="dev",
auth_dev_login_enabled=True,
auth_dev_login_extra_origins=["https://alpaca-home.taile93291.ts.net"],
):
config = await auth_routes.auth_config(request)
self.assertFalse(config.dev_login_enabled)
async def test_frontend_origin_map_routes_vnet_api_callbacks_to_vnet_frontend(self) -> None:
request = _request([(b"host", b"api-vnet.18ka.net")])
@ -233,6 +258,7 @@ class AuthProviderScaffoldTest(unittest.IsolatedAsyncioTestCase):
display_name="SAML Learner",
role="teacher",
cohort_ids=[],
external_id="saml:learner@hs.ac.kr",
)
cookie_blob = "\n".join(
value.decode("latin1")
@ -240,6 +266,54 @@ class AuthProviderScaffoldTest(unittest.IsolatedAsyncioTestCase):
if name.lower() == b"set-cookie"
)
self.assertIn("__Host-vignette_sid=opaque-session", cookie_blob)
async def test_saml_acs_maps_cohort_claim_into_session(self) -> None:
relay_state = "relay-state"
auth_routes._saml_states[relay_state] = auth_routes.SamlState(
request_id="_request",
next_path="/teach",
created_at=1_800_000_000.0,
)
request = _form_request(
"/auth/saml/acs",
{
"RelayState": relay_state,
"SAMLResponse": _fixture_saml_response(
email="teacher@hs.ac.kr",
display_name="Teacher",
role="teacher",
cohort="counseling-2026-a, lab-b",
),
},
)
create_session_mock = AsyncMock(return_value=("opaque-session", object()))
with (
patched_settings(
auth_saml_enabled=True,
saml_sp_entity_id="https://api-vignette.chanpaca.net/auth/saml/metadata",
saml_sso_url="https://sso.hs.ac.kr/idp/profile/SAML2/Redirect/SSO",
saml_x509_cert_fingerprint="",
frontend_base_url="https://vignette.test",
environment="dev",
),
patch.object(auth_routes, "create_session", create_session_mock),
):
response = await auth_routes.saml_acs(request)
self.assertEqual(response.status_code, 302)
create_session_mock.assert_awaited_once_with(
email="teacher@hs.ac.kr",
display_name="Teacher",
role="teacher",
cohort_ids=["counseling-2026-a", "lab-b"],
external_id="saml:teacher@hs.ac.kr",
)
cookie_blob = "\n".join(
value.decode("latin1")
for name, value in response.raw_headers
if name.lower() == b"set-cookie"
)
self.assertIn("HttpOnly", cookie_blob)
self.assertIn("Secure", cookie_blob)
self.assertNotIn("SAMLResponse", cookie_blob)
@ -330,6 +404,7 @@ class AuthProviderScaffoldTest(unittest.IsolatedAsyncioTestCase):
async def test_google_login_uses_pkce_state_without_exposing_secret(self) -> None:
with patched_settings(
environment="prod",
oauth_google_client_id="google-client",
oauth_google_client_secret="google-secret",
oauth_redirect_uri="https://api-vignette.test/auth/callback",
@ -353,6 +428,41 @@ class AuthProviderScaffoldTest(unittest.IsolatedAsyncioTestCase):
query["code_challenge"],
[auth_routes._pkce_challenge(stored.code_verifier)],
)
cookie_blob = "\n".join(
value.decode("latin1")
for name, value in response.raw_headers
if name.lower() == b"set-cookie"
)
self.assertIn("__Host-vignette_oauth_state=", cookie_blob)
self.assertIn("HttpOnly", cookie_blob)
self.assertIn("Secure", cookie_blob)
async def test_dev_google_login_rejects_public_callback_redirect(self) -> None:
request = _request(
[
(b"host", b"127.0.0.1:8010"),
(b"x-forwarded-host", b"alpaca-home.taile93291.ts.net"),
(b"x-forwarded-proto", b"https"),
]
)
with patched_settings(
environment="dev",
auth_dev_login_enabled=True,
auth_dev_login_extra_origins=["https://alpaca-home.taile93291.ts.net"],
oauth_google_client_id="google-client",
oauth_google_client_secret="google-secret",
oauth_redirect_uri="https://api-vignette.chanpaca.net/auth/callback",
frontend_base_url="https://vignette.chanpaca.net",
cors_origins=["https://vignette.chanpaca.net"],
):
response = await auth_routes.login(request, provider="google", next="/learn")
self.assertEqual(response.status_code, 302)
location = response.headers["location"]
self.assertIn("https://alpaca-home.taile93291.ts.net/login", location)
self.assertIn("oauth=local_oauth_unavailable", location)
self.assertFalse(auth_routes._oauth_states)
async def test_google_callback_sets_opaque_cookie_without_browser_tokens(self) -> None:
state = "state-token"
@ -401,6 +511,7 @@ class AuthProviderScaffoldTest(unittest.IsolatedAsyncioTestCase):
},
)
create_session_mock = AsyncMock(return_value=("opaque-session", object()))
with (
patched_settings(
oauth_google_client_id="google-client",
@ -408,14 +519,28 @@ class AuthProviderScaffoldTest(unittest.IsolatedAsyncioTestCase):
oauth_redirect_uri="https://api-vignette.test/auth/callback",
frontend_base_url="https://vignette.test",
environment="prod",
auth_domain_cohort_map={"hs.ac.kr": "hanshin-2026"},
auth_email_cohort_map={"learner@hs.ac.kr": "pilot-a"},
),
patch.object(auth_routes.httpx, "AsyncClient", FakeAsyncClient),
patch.object(auth_routes, "create_session", AsyncMock(return_value=("opaque-session", object()))),
patch.object(auth_routes, "create_session", create_session_mock),
):
response = await auth_routes.callback(_request(), code="auth-code", state=state)
response = await auth_routes.callback(
_request(),
code="auth-code",
state=state,
oauth_state_cookie=state,
)
self.assertEqual(response.status_code, 302)
self.assertEqual(response.headers["location"], "https://vignette.test/learn")
create_session_mock.assert_awaited_once_with(
email="learner@hs.ac.kr",
display_name="Learner",
role="learner",
cohort_ids=["pilot-a", "hanshin-2026"],
external_id="google:learner@hs.ac.kr",
)
cookie_blob = "\n".join(
value.decode("latin1")
for name, value in response.raw_headers
@ -428,6 +553,128 @@ class AuthProviderScaffoldTest(unittest.IsolatedAsyncioTestCase):
self.assertNotIn("browser-must-not-see-this", cookie_blob)
self.assertNotIn(state, auth_routes._oauth_states)
async def test_google_callback_accepts_signed_state_after_process_restart(self) -> None:
with patched_settings(
environment="prod",
oauth_google_client_id="google-client",
oauth_google_client_secret="google-secret",
oauth_redirect_uri="https://api-vignette.test/auth/callback",
frontend_base_url="https://vignette.test",
session_secret="signed-oauth-state-secret",
):
login_response = await auth_routes.login(_request(), provider="google", next="/learn")
query = parse_qs(urlsplit(login_response.headers["location"]).query)
state = query["state"][0]
expected_verifier = auth_routes._oauth_states[state].code_verifier
auth_routes._oauth_states.clear()
calls: list[tuple[str, str, dict[str, Any]]] = []
class FakeResponse:
def __init__(self, status_code: int, payload: dict[str, Any]) -> None:
self.status_code = status_code
self._payload = payload
def json(self) -> dict[str, Any]:
return self._payload
class FakeAsyncClient:
def __init__(self, *args: Any, **kwargs: Any) -> None:
pass
async def __aenter__(self) -> "FakeAsyncClient":
return self
async def __aexit__(self, exc_type: object, exc: object, tb: object) -> None:
return None
async def post(self, url: str, **kwargs: Any) -> FakeResponse:
calls.append(("POST", url, kwargs))
return FakeResponse(200, {"id_token": "id-token"})
async def get(self, url: str, **kwargs: Any) -> FakeResponse:
calls.append(("GET", url, kwargs))
return FakeResponse(
200,
{
"aud": "google-client",
"iss": "https://accounts.google.com",
"email": "learner@hs.ac.kr",
"email_verified": "true",
"name": "Learner",
"hd": "hs.ac.kr",
},
)
with (
patched_settings(
environment="prod",
oauth_google_client_id="google-client",
oauth_google_client_secret="google-secret",
oauth_redirect_uri="https://api-vignette.test/auth/callback",
frontend_base_url="https://vignette.test",
session_secret="signed-oauth-state-secret",
),
patch.object(auth_routes.httpx, "AsyncClient", FakeAsyncClient),
patch.object(auth_routes, "create_session", AsyncMock(return_value=("opaque-session", object()))),
):
response = await auth_routes.callback(
_request(),
code="auth-code",
state=state,
oauth_state_cookie=state,
)
self.assertEqual(response.status_code, 302)
self.assertEqual(response.headers["location"], "https://vignette.test/learn")
self.assertEqual(calls[0][2]["data"]["code_verifier"], expected_verifier)
async def test_google_callback_requires_state_cookie_match(self) -> None:
with patched_settings(
environment="prod",
oauth_google_client_id="google-client",
oauth_google_client_secret="google-secret",
oauth_redirect_uri="https://api-vignette.test/auth/callback",
frontend_base_url="https://vignette.test",
session_secret="signed-oauth-state-secret",
):
login_response = await auth_routes.login(_request(), provider="google", next="/learn")
state = parse_qs(urlsplit(login_response.headers["location"]).query)["state"][0]
auth_routes._oauth_states.clear()
with patched_settings(
environment="prod",
oauth_google_client_id="google-client",
oauth_google_client_secret="google-secret",
oauth_redirect_uri="https://api-vignette.test/auth/callback",
frontend_base_url="https://vignette.test",
session_secret="signed-oauth-state-secret",
):
response = await auth_routes.callback(_request(), code="auth-code", state=state)
self.assertEqual(response.status_code, 302)
self.assertIn("oauth=invalid_state", response.headers["location"])
async def test_google_callback_maps_provider_error_reason(self) -> None:
with patched_settings(
environment="prod",
oauth_google_client_id="google-client",
oauth_google_client_secret="google-secret",
oauth_redirect_uri="https://api-vignette.test/auth/callback",
frontend_base_url="https://vignette.test",
session_secret="signed-oauth-state-secret",
):
response = await auth_routes.callback(
_request(),
state="provider-state",
error="access_denied",
error_description="The user denied access.",
)
self.assertEqual(response.status_code, 302)
self.assertEqual(response.headers["location"], "https://vignette.test/login?oauth=access_denied")
def test_session_cookie_is_host_prefixed_httponly_secure_lax_without_domain(self) -> None:
response = Response()

View file

@ -0,0 +1,119 @@
import tempfile
import unittest
from pathlib import Path
from app.services.dataset_export import (
APPROVED_EXPORT_STATUS,
DRY_RUN_EXPORT_STATUS,
ExportKeyMaps,
build_dataset_record,
build_manifest,
cohen_kappa,
intraclass_correlation,
scan_for_pii,
sha256_file,
write_jsonl,
)
class DatasetExportTests(unittest.TestCase):
def test_build_dataset_record_uses_masked_text_and_pseudonymous_keys(self) -> None:
keys = ExportKeyMaps()
record = build_dataset_record(
{
"session_id": "11111111-1111-1111-1111-111111111111",
"learner_id": "22222222-2222-2222-2222-222222222222",
"turn_id": "33333333-3333-3333-3333-333333333333",
"persona_code": "P1",
"stage": "rapport",
"speaker": "counselor",
"text": "raw text should never be exported",
"text_masked": "안녕하세요, [NAME]님.",
"feedback_scores": [{"dimension": "공감", "score": 4}],
},
item_index=1,
export_manifest_id="phase3-rl-seed-test",
keys=keys,
)
self.assertEqual(record["participant_key"], "PX-0001")
self.assertEqual(record["session_key"], "SX-0001")
self.assertEqual(record["turn_key"], "TX-000001")
self.assertEqual(record["text_masked"], "안녕하세요, [NAME]님.")
blob = str(record)
self.assertNotIn("11111111-1111-1111-1111-111111111111", blob)
self.assertNotIn("22222222-2222-2222-2222-222222222222", blob)
self.assertNotIn("raw text should never be exported", blob)
def test_pii_scan_detects_identifiers_without_raw_samples(self) -> None:
findings = scan_for_pii(
{
"text_masked": "메일 learner@hs.ac.kr, 전화 010-1234-5678, 주민 990101-1234567",
"api_key": "sk-should-not-appear",
}
)
kinds = {finding["kind"] for finding in findings}
self.assertIn("email", kinds)
self.assertIn("phone", kinds)
self.assertIn("national_id", kinds)
self.assertIn("blocked_field", kinds)
self.assertFalse(any("learner@hs.ac.kr" in finding["sample"] for finding in findings))
self.assertFalse(any("010-1234-5678" in finding["sample"] for finding in findings))
def test_agreement_metrics(self) -> None:
annotations = [
{"item_id": "1", "labels": {"appropriateness": "good", "rapport_signal": 4.0}},
{"item_id": "1", "labels": {"appropriateness": "good", "rapport_signal": 4.1}},
{"item_id": "2", "labels": {"appropriateness": "bad", "rapport_signal": 2.0}},
{"item_id": "2", "labels": {"appropriateness": "bad", "rapport_signal": 2.1}},
{"item_id": "3", "labels": {"appropriateness": "good", "rapport_signal": 5.0}},
{"item_id": "3", "labels": {"appropriateness": "good", "rapport_signal": 5.0}},
]
self.assertEqual(cohen_kappa(annotations, "appropriateness"), 1.0)
self.assertGreater(intraclass_correlation(annotations, "rapport_signal") or 0, 0.9)
def test_manifest_gate_blocks_unapproved_approved_status(self) -> None:
with self.assertRaisesRegex(ValueError, "PII scan must pass"):
build_manifest(
export_id="phase3-rl-seed-test",
dataset_name="vignette_phase3_recursive_learning_seed",
export_status=APPROVED_EXPORT_STATUS,
purpose="test",
records=[],
jsonl_path="03-export/anonymized_dataset.jsonl",
jsonl_sha256="",
pii_findings=[{"kind": "email", "path": "$.text_masked", "sample": "<email:hs.ac.kr>"}],
participants_included=0,
agreement={"kappa": 0.59, "icc": 0.74, "gold_status": "not_gold"},
)
def test_jsonl_hash_manifest_dry_run(self) -> None:
record = {
"schema": "phase3_dataset_item_v1",
"item_id": "DI-000001",
"source_refs": {"session_started_at": "2026-06-27T00:00:00Z"},
}
with tempfile.TemporaryDirectory() as tmp:
path = Path(tmp) / "03-export" / "anonymized_dataset.jsonl"
write_jsonl([record], path)
digest = sha256_file(path)
manifest = build_manifest(
export_id="phase3-rl-seed-test",
dataset_name="vignette_phase3_recursive_learning_seed",
export_status=DRY_RUN_EXPORT_STATUS,
purpose="test",
records=[record],
jsonl_path="03-export/anonymized_dataset.jsonl",
jsonl_sha256=digest,
pii_findings=[],
participants_included=1,
)
self.assertEqual(manifest["files"][0]["rows"], 1)
self.assertEqual(manifest["files"][0]["sha256"], digest)
self.assertEqual(manifest["pii_scan"]["status"], "pass")
if __name__ == "__main__":
unittest.main()

View file

@ -32,6 +32,17 @@ class FakeEvaluationConn:
raise AssertionError(f"unexpected fetchval query: {query}")
class FakeAcquire:
def __init__(self, conn: FakeEvaluationConn) -> None:
self.conn = conn
async def __aenter__(self) -> FakeEvaluationConn:
return self.conn
async def __aexit__(self, exc_type: object, exc: object, tb: object) -> None:
return None
class EvaluationPersistenceMappingTest(unittest.TestCase):
def test_feedback_rows_preserve_review_scalar_contract(self) -> None:
evaluation = {
@ -126,6 +137,13 @@ class EvaluationPersistenceMappingTest(unittest.TestCase):
},
}
],
alternative_rows=[
{
"turn_id": "11111111-1111-1111-1111-111111111111",
"suggestion": "감정을 먼저 반영해 보세요.",
"rationale": None,
}
],
)
ev = rebuilt["11111111-1111-1111-1111-111111111111"]
@ -137,6 +155,7 @@ class EvaluationPersistenceMappingTest(unittest.TestCase):
self.assertEqual(ev["techniques"][0]["rationale"], "정서 반영이 포함됐다.")
self.assertEqual(ev["client_state_read"][0]["label_ko"], "방어")
self.assertEqual(ev["intent_deviation"]["dimension"], "pacing")
self.assertEqual(ev["alternative_utterances"], ["감정을 먼저 반영해 보세요."])
def test_evaluation_rls_blocks_raw_learner_writes(self) -> None:
root = Path(__file__).resolve().parents[3]
@ -158,6 +177,43 @@ class EvaluationPersistenceMappingTest(unittest.TestCase):
class EvaluationPersistenceIOTest(unittest.IsolatedAsyncioTestCase):
async def test_record_llm_call_audit_inserts_metadata_only(self) -> None:
conn = FakeEvaluationConn()
payload = {
"session_id": "11111111-1111-1111-1111-111111111111",
"provider": "claude_cli",
"model": "sonnet",
"tokens_in": 120,
"tokens_out": 45,
"cost_usd": 0.0123,
"inference_geo": "us",
"latency_ms": 345,
"messages": [{"content": "raw prompt must not be persisted"}],
}
with (
patch.object(session_persistence, "get_pool", return_value=object()),
patch.object(session_persistence, "acquire", return_value=FakeAcquire(conn)) as acquire,
):
ok = await session_persistence.record_llm_call_audit(payload)
self.assertTrue(ok)
acquire.assert_called_once_with(ai_context=True, ai_view="evaluator")
self.assertEqual(len(conn.executed), 1)
query, args = conn.executed[0]
self.assertIn("INSERT INTO audit.llm_call_log", query)
self.assertNotIn("raw prompt", query)
self.assertNotIn("messages", query)
self.assertEqual(args[0], "11111111-1111-1111-1111-111111111111")
self.assertIsNone(args[1])
self.assertEqual(args[2], "claude_cli")
self.assertEqual(args[3], "sonnet")
self.assertEqual(args[4], 120)
self.assertEqual(args[5], 45)
self.assertEqual(args[6], 0.0123)
self.assertEqual(args[7], "us")
self.assertEqual(args[8], 345)
async def test_persist_turn_evaluation_uses_evaluator_context_and_real_fast_tables(self) -> None:
conn = FakeEvaluationConn()
evaluation = {
@ -187,6 +243,7 @@ class EvaluationPersistenceIOTest(unittest.IsolatedAsyncioTestCase):
"actual": "조언",
"severity": "minor",
},
"alternative_utterances": ["감정을 먼저 반영해 보세요."],
}
await session_persistence._persist_turn_evaluation(
@ -202,7 +259,8 @@ class EvaluationPersistenceIOTest(unittest.IsolatedAsyncioTestCase):
self.assertIn("INSERT INTO app.turn_technique", executed_sql)
self.assertIn("INSERT INTO app.turn_client_state", executed_sql)
self.assertIn("INSERT INTO app.supervisor_comment", executed_sql)
self.assertNotIn("app.alternative_utterance", executed_sql)
self.assertIn("DELETE FROM app.alternative_utterance", executed_sql)
self.assertIn("INSERT INTO app.alternative_utterance", executed_sql)
async def test_route_loader_only_hydrates_when_requested(self) -> None:
principal = Principal(

View file

@ -145,11 +145,34 @@ class OrchestratorMaskingGateTest(unittest.IsolatedAsyncioTestCase):
for masked in MASK_VALUES:
self.assertIn(masked, blob)
def test_prepare_turn_threads_theory_mode_into_engine_messages(self) -> None:
ctx = orchestrator.prepare_turn(
session_id="theory-session",
case_id="theory-case",
card=persona.P2,
state=_initial_state(),
learner_text="그냥 아무것도 하기 싫어요.",
theory_mode="cbt",
)
blob = _message_blob(ctx.messages)
self.assertIn("[L3-T 이론모드: CBT]", blob)
self.assertIn("자동적 사고", blob)
self.assertIn("행동활성화", blob)
async def test_run_turn_generate_sends_only_masked_engine_payload(self) -> None:
ctx = _prepare_context()
engine = CaptureGenerateEngine()
audit_payloads: list[dict[str, Any]] = []
await orchestrator.run_turn_generate(ctx, engine) # type: ignore[arg-type]
async def audit_hook(payload: dict[str, Any]) -> None:
audit_payloads.append(payload)
await orchestrator.run_turn_generate(
ctx,
engine, # type: ignore[arg-type]
audit_hook=audit_hook,
)
self.assertIsNotNone(engine.request)
self.assertIsNotNone(engine.payload)
@ -158,14 +181,28 @@ class OrchestratorMaskingGateTest(unittest.IsolatedAsyncioTestCase):
_assert_masked_pii_present(self, engine.request.messages)
_assert_masked_pii_present(self, engine.payload)
self.assertEqual(ctx.learner_text_raw, RAW_TEXT)
self.assertEqual(len(audit_payloads), 1)
self.assertEqual(audit_payloads[0]["provider"], "fake-provider")
self.assertEqual(audit_payloads[0]["model"], "fake-model")
_assert_no_raw_pii(self, audit_payloads)
for key in ("messages", "prompt", "text"):
self.assertNotIn(key, audit_payloads[0])
async def test_run_turn_stream_sends_only_masked_engine_payload(self) -> None:
ctx = _prepare_context()
engine = CaptureStreamEngine()
audit_payloads: list[dict[str, Any]] = []
async def audit_hook(payload: dict[str, Any]) -> None:
audit_payloads.append(payload)
events = [
event
async for event in orchestrator.run_turn_stream(ctx, engine) # type: ignore[arg-type]
async for event in orchestrator.run_turn_stream(
ctx,
engine, # type: ignore[arg-type]
audit_hook=audit_hook,
)
]
self.assertEqual([event.event for event in events], ["token", "done"])
@ -176,6 +213,12 @@ class OrchestratorMaskingGateTest(unittest.IsolatedAsyncioTestCase):
_assert_masked_pii_present(self, engine.request.messages)
_assert_masked_pii_present(self, engine.payload)
self.assertEqual(ctx.learner_text_raw, RAW_TEXT)
self.assertEqual(len(audit_payloads), 1)
self.assertEqual(audit_payloads[0]["tokens_in"], 5)
self.assertEqual(audit_payloads[0]["tokens_out"], 6)
_assert_no_raw_pii(self, audit_payloads)
for key in ("messages", "prompt", "text"):
self.assertNotIn(key, audit_payloads[0])
if __name__ == "__main__":

View file

@ -10,7 +10,7 @@ from fastapi import HTTPException
from . import persona_repository
from .deps import Principal, Role
from .persona_repository import PersonaReviewItem
from .persona_repository import PersonaDraftRecord, PersonaReviewItem
from .routes import personas, sessions
from .services import persona as persona_service
@ -72,6 +72,7 @@ class _PersonaCardConn:
self.rows = rows
self.fetch_calls: list[tuple[str, tuple[Any, ...]]] = []
self.fetchrow_calls: list[tuple[str, tuple[Any, ...]]] = []
self.fetchval_calls: list[tuple[str, tuple[Any, ...]]] = []
self.execute_calls: list[tuple[str, tuple[Any, ...]]] = []
async def fetch(self, query: str, *args: Any) -> list[dict[str, Any]]:
@ -81,6 +82,36 @@ class _PersonaCardConn:
async def fetchrow(self, query: str, *args: Any) -> dict[str, Any] | None:
self.fetchrow_calls.append((query, args))
if "UPDATE app.persona_card" in query:
if "display_name = $4" in query:
persona_id = str(args[0])
next_status = str(args[2])
for row in self.rows:
if row["persona_id"] != persona_id or row["status"] not in {"draft", "review"}:
continue
row.update(
{
"code": str(args[1]).upper(),
"status": next_status,
"display_name": args[3],
"difficulty": args[4],
"theory_target": list(args[5]),
"demographics": dict(args[6]),
"presenting": dict(args[7]),
"history": dict(args[8]),
"big5": dict(args[9]),
"resistance": dict(args[10]),
"speech_style": dict(args[11]),
"affect_baseline": dict(args[12]),
"ccd": dict(args[13]),
"dsm5_dimensional": dict(args[14]),
"source_provenance": args[15],
"is_synthetic": bool(args[16]),
"approved_by": None,
"approved_at": None,
}
)
return row
return None
persona_id = str(args[0])
next_status = str(args[1])
approved_by = args[2]
@ -92,12 +123,51 @@ class _PersonaCardConn:
row["approved_at"] = "2026-01-03T00:00:00" if next_status == "approved" else None
return row
return None
if "INSERT INTO app.persona_card" in query:
row = {
"persona_id": str(args[0]),
"code": str(args[1]).upper(),
"version": int(args[2]),
"status": str(args[3]),
"display_name": args[4],
"difficulty": args[5],
"theory_target": list(args[6]),
"demographics": dict(args[7]),
"presenting": dict(args[8]),
"history": dict(args[9]),
"big5": dict(args[10]),
"resistance": dict(args[11]),
"speech_style": dict(args[12]),
"affect_baseline": dict(args[13]),
"ccd": dict(args[14]),
"dsm5_dimensional": dict(args[15]),
"source_provenance": args[16],
"is_synthetic": bool(args[17]),
"created_by": args[18],
"approved_by": None,
"created_at": "2026-01-04T00:00:00",
"approved_at": None,
}
self.rows.append(row)
return row
if "WHERE persona_id = $1::uuid" in query:
persona_id = str(args[0])
for row in self.rows:
if row["persona_id"] == persona_id and row["status"] in {"draft", "review"}:
return row
return None
rows = self._filter_rows(query, args)
code = str(args[0]).upper() if args else ""
matches = [row for row in rows if str(row["code"]).upper() == code]
matches.sort(key=lambda row: int(row["version"]), reverse=True)
return matches[0] if matches else None
async def fetchval(self, query: str, *args: Any) -> int:
self.fetchval_calls.append((query, args))
code = str(args[0]).upper()
versions = [int(row["version"]) for row in self.rows if str(row["code"]).upper() == code]
return (max(versions) if versions else 0) + 1
async def execute(self, query: str, *args: Any) -> str:
self.execute_calls.append((query, args))
return "INSERT 0 1"
@ -111,6 +181,31 @@ class _PersonaCardConn:
return list(self.rows)
def _draft_payload(
card: persona_service.PersonaCard,
*,
submit_for_review: bool = False,
) -> personas.PersonaDraftPayload:
return personas.PersonaDraftPayload(
code=card.code,
display_name=card.display_name,
difficulty=card.difficulty, # type: ignore[arg-type]
theory_target=list(card.theory_target),
demographics=dict(card.demographics),
presenting=dict(card.presenting),
history=dict(card.history),
big5=dict(card.big5),
resistance=dict(card.resistance),
speech_style=dict(card.speech_style),
affect_baseline=dict(card.affect_baseline),
ccd=dict(card.ccd),
dsm5_dimensional=dict(card.dsm5_dimensional),
source_provenance=card.source_provenance,
is_synthetic=card.is_synthetic,
submit_for_review=submit_for_review,
)
class PersonaApprovalBoundaryTest(unittest.IsolatedAsyncioTestCase):
async def test_catalog_repository_lists_only_approved_personas(self) -> None:
conn = _PersonaCardConn(
@ -249,6 +344,165 @@ class PersonaReviewQueueTest(unittest.IsolatedAsyncioTestCase):
with self.assertRaises(ValueError):
await persona_repository.list_persona_review_queue(role="learner")
async def test_teacher_creates_persona_draft_version_and_audits(self) -> None:
author_id = "00000000-0000-0000-0000-000000000901"
conn = _PersonaCardConn(
[
_card_row(
persona_service.P2,
persona_id="00000000-0000-0000-0000-000000000501",
status="approved",
version=1,
),
]
)
acquire_calls: list[dict[str, Any]] = []
def fake_acquire(**kwargs: Any) -> _Acquire:
acquire_calls.append(kwargs)
return _Acquire(conn)
with (
patch.object(persona_repository, "get_pool", return_value=object()),
patch.object(persona_repository, "acquire", fake_acquire),
):
created = await persona_repository.create_persona_draft(
card=persona_service.P2,
author_id=author_id,
role="teacher",
submit_for_review=True,
)
self.assertEqual(created.code, "P2")
self.assertEqual(created.version, 2)
self.assertEqual(created.status, "review")
self.assertEqual(acquire_calls, [{"role": "teacher", "user_id": author_id}])
self.assertEqual(conn.fetchval_calls[0][1], ("P2",))
audit_query, audit_args = conn.execute_calls[0]
self.assertIn("INSERT INTO audit.audit_log", audit_query)
self.assertEqual(audit_args[1], "persona_draft_create")
self.assertEqual(audit_args[4]["next_status"], "review")
async def test_teacher_updates_persona_draft_and_submits_review(self) -> None:
author_id = "00000000-0000-0000-0000-000000000901"
persona_id = "00000000-0000-0000-0000-000000000502"
conn = _PersonaCardConn(
[
_card_row(
persona_service.P3,
persona_id=persona_id,
status="draft",
version=4,
),
]
)
edited_card = persona_service.P3
with (
patch.object(persona_repository, "get_pool", return_value=object()),
patch.object(persona_repository, "acquire", lambda **_: _Acquire(conn)),
):
updated = await persona_repository.update_persona_draft(
persona_id=persona_id,
card=edited_card,
author_id=author_id,
role="admin",
submit_for_review=True,
)
self.assertIsNotNone(updated)
assert updated is not None
self.assertEqual(updated.status, "review")
self.assertEqual(updated.version, 4)
update_query, update_args = conn.fetchrow_calls[0]
self.assertIn("display_name = $4", update_query)
self.assertEqual(update_args[0], persona_id)
self.assertEqual(update_args[2], "review")
_, audit_args = conn.execute_calls[0]
self.assertEqual(audit_args[1], "persona_draft_update")
async def test_teacher_reads_persona_draft_detail_route(self) -> None:
record = PersonaDraftRecord(
review=PersonaReviewItem(
persona_id="00000000-0000-0000-0000-000000000503",
code="P3",
version=2,
status="draft",
display_name=persona_service.P3.display_name,
difficulty=persona_service.P3.difficulty,
theory_target=list(persona_service.P3.theory_target),
source_provenance=persona_service.P3.source_provenance,
is_synthetic=persona_service.P3.is_synthetic,
created_at="2026-01-04T00:00:00",
approved_at=None,
),
card=persona_service.P3,
)
with patch.object(
personas,
"get_persona_draft_record",
AsyncMock(return_value=record),
) as get_draft:
response = await personas.get_persona_draft_route(
"00000000-0000-0000-0000-000000000503",
_principal(Role.TEACHER),
)
self.assertEqual(response.code, "P3")
self.assertEqual(response.presenting, persona_service.P3.presenting)
get_draft.assert_awaited_once_with(
persona_id="00000000-0000-0000-0000-000000000503",
role="teacher",
)
async def test_teacher_create_draft_route_calls_repository(self) -> None:
created = PersonaReviewItem(
persona_id="00000000-0000-0000-0000-000000000504",
code="P2",
version=2,
status="review",
display_name=persona_service.P2.display_name,
difficulty=persona_service.P2.difficulty,
theory_target=list(persona_service.P2.theory_target),
source_provenance=persona_service.P2.source_provenance,
is_synthetic=persona_service.P2.is_synthetic,
created_at="2026-01-04T00:00:00",
approved_at=None,
)
with patch.object(
personas,
"create_persona_draft",
AsyncMock(return_value=created),
) as create_draft:
response = await personas.create_persona_draft_route(
_draft_payload(persona_service.P2, submit_for_review=True),
_principal(Role.ADMIN),
)
self.assertEqual(response.status, "review")
args = create_draft.await_args.kwargs
self.assertEqual(args["role"], "admin")
self.assertEqual(args["author_id"], "00000000-0000-0000-0000-000000000901")
self.assertTrue(args["submit_for_review"])
self.assertEqual(args["card"].code, "P2")
async def test_learner_cannot_create_persona_draft_route(self) -> None:
with patch.object(
personas,
"create_persona_draft",
AsyncMock(side_effect=AssertionError("learner must not reach draft repository")),
) as create_draft:
with self.assertRaises(HTTPException) as caught:
await personas.create_persona_draft_route(
_draft_payload(persona_service.P1),
_principal(Role.LEARNER),
)
self.assertEqual(caught.exception.status_code, 403)
create_draft.assert_not_awaited()
async def test_learner_cannot_call_review_route(self) -> None:
with patch.object(
personas,

View file

@ -146,7 +146,7 @@ class LearnerSessionIdorTest(unittest.IsolatedAsyncioTestCase):
"load_session",
AsyncMock(return_value=None),
),
patch.object(sessions, "runtime_fallback_allowed", return_value=True),
patch.object(sessions.turn_runtime, "runtime_fallback_allowed", return_value=True),
patch.object(
sessions,
"_review_ready",
@ -188,7 +188,7 @@ class LearnerSessionIdorTest(unittest.IsolatedAsyncioTestCase):
"load_session",
AsyncMock(return_value=None),
),
patch.object(sessions, "runtime_fallback_allowed", return_value=True),
patch.object(sessions.turn_runtime, "runtime_fallback_allowed", return_value=True),
patch.object(sessions, "_review_ready", AsyncMock(return_value=False)),
):
response = await sessions.get_session_detail(sess.session_id, owner)
@ -235,7 +235,7 @@ class LearnerSessionIdorTest(unittest.IsolatedAsyncioTestCase):
"load_session",
AsyncMock(return_value=None),
),
patch.object(sessions, "runtime_fallback_allowed", return_value=True),
patch.object(sessions.turn_runtime, "runtime_fallback_allowed", return_value=True),
patch.object(
sessions.session_persistence,
"load_session_evaluation",
@ -299,7 +299,7 @@ class LearnerSessionIdorTest(unittest.IsolatedAsyncioTestCase):
"load_session",
AsyncMock(return_value=None),
),
patch.object(sessions, "runtime_fallback_allowed", return_value=True),
patch.object(sessions.turn_runtime, "runtime_fallback_allowed", return_value=True),
patch.object(sessions.orchestrator, "run_turn_generate", successful_turn),
):
await sessions.submit_turn(

View file

@ -3,7 +3,9 @@
from __future__ import annotations
import unittest
import time
from contextlib import contextmanager
from types import SimpleNamespace
from unittest.mock import AsyncMock, patch
from fastapi import HTTPException
@ -215,6 +217,95 @@ class RuntimeFallbackPolicyTest(unittest.IsolatedAsyncioTestCase):
self.assertEqual(db.metric, "비영구 런타임 기록")
self.assertIn("비영구 개발 런타임 기록", db.detail)
async def test_dev_admin_usage_falls_back_to_runtime_store(self) -> None:
principal = Principal(
user_id="00000000-0000-0000-0000-000000000007",
role=Role.ADMIN,
cohort_ids=[],
email="admin@twentyoz.kr",
display_name="Admin",
)
now = time.time()
fake_session = SimpleNamespace(
turns=[
SimpleNamespace(
speaker="client",
created_at=now,
llm_provider="claude_cli",
model="gateway-default",
tokens_in=11,
tokens_out=13,
cost_usd=0.0042,
),
SimpleNamespace(
speaker="client",
created_at=now,
llm_provider=None,
model=None,
tokens_in=None,
tokens_out=None,
cost_usd=None,
),
SimpleNamespace(
speaker="counselor",
created_at=now,
llm_provider="ignored",
model="ignored",
tokens_in=100,
tokens_out=100,
cost_usd=9.0,
),
]
)
with (
environment("dev"),
patch.object(
admin_routes,
"_usage_from_database",
AsyncMock(side_effect=RuntimeError("db unavailable")),
),
patch.object(admin_routes.store, "list", return_value=[fake_session]),
patch.object(admin_routes.settings, "admin_usage_budget_usd", 0.005),
):
usage = await admin_routes.admin_usage(principal, window_days=7)
self.assertEqual(usage.source, "server_session_registry")
self.assertFalse(usage.durable)
self.assertEqual(usage.total_turns, 2)
self.assertEqual(usage.metered_turns, 1)
self.assertEqual(usage.tokens_in, 11)
self.assertEqual(usage.tokens_out, 13)
self.assertAlmostEqual(usage.cost_usd, 0.0042)
self.assertEqual(usage.budget.status, "warn")
self.assertAlmostEqual(usage.budget.limit_usd, 0.005)
self.assertAlmostEqual(usage.budget.used_ratio, 0.84)
self.assertEqual(usage.by_provider[0].provider, "claude_cli")
self.assertEqual(usage.by_provider[0].turns, 1)
async def test_prod_admin_usage_rejects_runtime_store_fallback(self) -> None:
principal = Principal(
user_id="00000000-0000-0000-0000-000000000008",
role=Role.ADMIN,
cohort_ids=[],
email="admin@twentyoz.kr",
display_name="Admin",
)
with (
environment("prod"),
patch.object(
admin_routes,
"_usage_from_database",
AsyncMock(side_effect=RuntimeError("db unavailable")),
),
):
with self.assertRaises(HTTPException) as caught:
await admin_routes.admin_usage(principal, window_days=7)
self.assertEqual(caught.exception.status_code, 503)
self.assertIn("runtime fallback is disabled in prod", caught.exception.detail)
def test_non_dev_rejects_fixture_runtime_flags(self) -> None:
with self.assertRaises(ValueError) as caught:
Settings(
@ -261,6 +352,7 @@ class RuntimeFallbackPolicyTest(unittest.IsolatedAsyncioTestCase):
oauth_google_client_secret="google-client-secret",
frontend_base_url="https://vignette.chanpaca.net",
cors_origins=["https://vignette.chanpaca.net"],
voice_poc_sample_tts_enabled=False,
)
self.assertEqual(cfg.environment, "staging")
@ -281,6 +373,7 @@ class RuntimeFallbackPolicyTest(unittest.IsolatedAsyncioTestCase):
"api-vnet.18ka.net": "https://vnet.18ka.net",
},
cors_origins=["https://vignette.chanpaca.net", "https://vnet.18ka.net"],
voice_poc_sample_tts_enabled=False,
)
self.assertEqual(cfg.frontend_origin_map["api-vnet.18ka.net"], "https://vnet.18ka.net")
@ -318,6 +411,7 @@ class RuntimeFallbackPolicyTest(unittest.IsolatedAsyncioTestCase):
"http://localhost:5170",
"http://127.0.0.1:5180",
],
voice_poc_sample_tts_enabled=False,
)
self.assertIn("http://localhost:5170", cfg.cors_origins)

View file

@ -2,16 +2,19 @@
from __future__ import annotations
import json
import unittest
from types import SimpleNamespace
from unittest.mock import AsyncMock, patch
from . import turn_runtime
from .deps import Principal, Role
from .engine_client import EngineError
from .routes import sessions
from .routes import voice as voice_routes
from .services import orchestrator, persona as persona_service, state_machine
from .services import memory, orchestrator, persona as persona_service, state_machine
from .services.voice import TTSChunk, TranscriptResult, VoicePreset
from .store import InProcSession, store
from .store import InProcSession, TurnRecord, store
def _principal() -> Principal:
@ -118,11 +121,84 @@ class SessionTurnPersistenceTest(unittest.IsolatedAsyncioTestCase):
self.assertEqual(client_turn.tokens_out, 23)
self.assertEqual(client_turn.cost_usd, 0.012345)
async def test_generate_real_crisis_stops_before_engine_and_returns_109_resource(self) -> None:
principal = _principal()
sess = _session(principal)
async def should_not_generate(*args, **kwargs):
raise AssertionError("engine must not be called for learner_real crisis")
with patch.object(sessions.engine_client, "generate", should_not_generate):
response = await sessions.submit_turn(
sess.session_id,
sessions.TurnRequest(text="저 지금 죽고싶어요. 도와주세요."),
principal,
)
self.assertTrue(response.safety_flagged)
self.assertTrue(response.conversation_stopped)
self.assertEqual(response.crisis_kind, "learner_real")
self.assertIsNotNone(response.crisis_resource)
self.assertEqual(response.crisis_resource.number, "109")
self.assertIsNone(response.client_reply)
self.assertEqual(len(sess.turns), 1)
self.assertEqual(sess.turns[0].speaker, "counselor")
async def test_record_safety_event_writes_teacher_alert_payload(self) -> None:
principal = _principal()
sess = _session(principal)
ctx = orchestrator.prepare_turn(
session_id=sess.session_id,
case_id=sess.case_id,
card=sess.persona,
state=sess.state,
learner_text="저 지금 자살하고 싶어요. 도와주세요.",
theory_mode=sess.theory_mode,
)
result = orchestrator.TurnResult(
turn_seq=ctx.state_after.turn_seq if ctx.state_after else 1,
stage=ctx.state_after.stage.value if ctx.state_after else "라포",
effective_openness=ctx.state_after.effective_openness if ctx.state_after else 0.0,
client_reply=None,
safety_flagged=True,
state_after=ctx.state_after or sess.state,
crisis_kind="learner_real",
crisis_resource={"title": "자살예방상담전화 109", "number": "109"},
conversation_stopped=True,
)
calls: list[tuple[str, tuple[object, ...]]] = []
class FakeConn:
async def execute(self, query: str, *args: object) -> str:
calls.append((query, args))
return "INSERT 0 1"
class FakeAcquire:
async def __aenter__(self) -> FakeConn:
return FakeConn()
async def __aexit__(self, exc_type: object, exc: object, tb: object) -> None:
return None
with patch.object(turn_runtime.db, "acquire", return_value=FakeAcquire()):
await turn_runtime.record_safety_event(sess, ctx, result)
self.assertEqual(len(calls), 1)
query, args = calls[0]
self.assertIn("INSERT INTO app.safety_events", query)
self.assertEqual(args[0], sess.session_id)
self.assertEqual(args[1], "learner_real")
self.assertGreaterEqual(args[2], 4)
detail = json.loads(args[3])
self.assertTrue(detail["conversation_stopped"])
self.assertEqual(detail["crisis_resource"]["number"], "109")
self.assertEqual(detail["alert_status"], "teacher_dashboard")
async def test_stream_turn_persists_client_engine_telemetry(self) -> None:
principal = _principal()
sess = _session(principal)
async def successful_stream(ctx, engine):
async def successful_stream(ctx, engine, **kwargs):
assert ctx.state_after is not None
yield orchestrator.StreamEvent("token", {"text": "괜찮아요."})
yield orchestrator.StreamEvent(
@ -158,6 +234,146 @@ class SessionTurnPersistenceTest(unittest.IsolatedAsyncioTestCase):
self.assertEqual(client_turn.tokens_out, 37)
self.assertEqual(client_turn.cost_usd, 0.023456)
async def test_stream_real_crisis_stops_before_engine_and_persists_learner_only(self) -> None:
principal = _principal()
sess = _session(principal)
def should_not_stream(*args, **kwargs):
raise AssertionError("stream engine must not be called for learner_real crisis")
with patch.object(sessions.engine_client, "stream", should_not_stream):
response = await sessions.stream_turn(
sess.session_id,
sessions.TurnRequest(text="저 지금 자살하고 싶어요. 도와주세요."),
principal,
)
body = await _consume_event_source(response)
rendered = body.decode("utf-8")
self.assertIn("'event': 'safety'", rendered)
self.assertIn("'event': 'done'", rendered)
self.assertIn("109", rendered)
self.assertIn("conversation_stopped", rendered)
self.assertEqual(len(sess.turns), 1)
self.assertEqual(sess.turns[0].speaker, "counselor")
async def test_stream_turn_persists_fast_loop_evaluation_on_learner_turn(self) -> None:
principal = _principal()
sess = _session(principal)
async def successful_stream(ctx, engine, **kwargs):
assert ctx.state_after is not None
yield orchestrator.StreamEvent("token", {"text": "조금 말해볼게요."})
yield orchestrator.StreamEvent(
"done",
{
"session_id": ctx.session_id,
"stage": ctx.state_after.stage.value,
"effective_openness": ctx.state_after.effective_openness,
"turn_seq": ctx.state_after.turn_seq,
"safety_flagged": False,
"llm_provider": "claude_cli",
"model": "gateway-default",
"tokens_in": 9,
"tokens_out": 10,
"cost_usd": 0.001,
},
)
async def fake_eval_hook(ctx, client_reply):
return {
"loop": "fast",
"turn_seq": ctx.state_after.turn_seq,
"stage": ctx.state_after.stage.value,
"appropriateness": "pos",
"appropriateness_note": f"응답 반영: {client_reply}",
}
with patch.object(sessions.orchestrator, "run_turn_stream", successful_stream), patch.object(
sessions.evaluator,
"make_eval_hook",
return_value=fake_eval_hook,
):
response = await sessions.stream_turn(
sess.session_id,
sessions.TurnRequest(text="스트림 평가 발화"),
principal,
)
await _consume_event_source(response)
self.assertEqual(len(sess.turns), 2)
learner_turn, client_turn = sess.turns
self.assertEqual(learner_turn.speaker, "counselor")
self.assertIsNotNone(learner_turn.evaluation)
self.assertEqual(learner_turn.evaluation["appropriateness"], "pos")
self.assertIn("조금 말해볼게요", learner_turn.evaluation["appropriateness_note"])
self.assertIsNone(client_turn.evaluation)
async def test_start_session_uses_stable_case_context_and_seed_recall(self) -> None:
principal = _principal()
card = persona_service.P1
case_context = sessions.session_persistence.CaseContext(
case_id="00000000-0000-0000-0000-00000000ca5e",
last_session_no=1,
)
catalog_persona = SimpleNamespace(
card=card,
persona_id="00000000-0000-0000-0000-0000000000a1",
version=3,
degraded=False,
)
recall = memory.RecallContext(
recall_summary="지난 회기에서 가족 이야기를 열어두었다.",
carry={
"rapport_credit": 0.6,
"resistance": card.base_resistance(),
"ideation_stage": card.ideation_baseline(),
},
)
async def fake_create_session(**kwargs):
self.assertEqual(kwargs["case_id"], case_context.case_id)
self.assertEqual(kwargs["session_no"], 2)
self.assertGreater(kwargs["state"].rapport_credit, 0)
return InProcSession(
session_id="stable-case-session",
case_id=kwargs["case_id"],
learner_id=principal.user_id,
persona_code=card.code,
theory_mode=kwargs["theory_mode"],
persona=card,
state=kwargs["state"],
session_no=kwargs["session_no"],
prev_rapport_credit=kwargs["carry_rapport"],
)
def close_background(coro):
coro.close()
return None
with patch.object(sessions, "get_catalog_persona", AsyncMock(return_value=catalog_persona)), patch.object(
sessions.session_persistence,
"get_case_context",
AsyncMock(return_value=case_context),
), patch.object(
sessions,
"_build_seed_recall",
AsyncMock(return_value=recall),
), patch.object(
sessions.session_persistence,
"create_session",
fake_create_session,
), patch.object(sessions.asyncio, "create_task", close_background):
response = await sessions.start_session(
sessions.SessionStartRequest(persona_code=card.code),
principal,
)
self.assertEqual(response.case_id, case_context.case_id)
self.assertEqual(response.session_no, 2)
self.assertEqual(response.recall_summary, recall.recall_summary)
self.assertIs(sessions._RECALL_CACHE[response.session_id], recall)
async def test_run_turn_stream_parses_gateway_done_telemetry(self) -> None:
class FakeStreamEngine:
engine_mode = "claude_cli"
@ -357,6 +573,90 @@ class SessionTurnPersistenceTest(unittest.IsolatedAsyncioTestCase):
self.assertEqual(client_turn.llm_provider, "claude_cli")
self.assertTrue(any(message.get("type") == "tts_end" for message in websocket.messages))
async def test_review_exposes_voice_nonverbal_events_on_learner_turn(self) -> None:
principal = _principal()
sess = _session(principal)
created_at = sess.created_at
sess.turns.extend(
[
TurnRecord(
turn_seq=1,
speaker="counselor",
stage=sess.state.stage.value,
text="learner voice turn",
text_masked="learner voice turn",
created_at=created_at + 1,
audio_ref="voice:webm:sha256:test",
silence_ms=1234,
speech_rate=420.0,
barge_in=True,
),
TurnRecord(
turn_seq=2,
speaker="client",
stage=sess.state.stage.value,
text="client reply",
text_masked="client reply",
created_at=created_at + 2,
audio_ref="voice:webm:sha256:client",
silence_ms=2500,
speech_rate=180.0,
barge_in=True,
),
]
)
response = await sessions.get_session_review(sess.session_id, principal)
self.assertEqual(len(response.turns), 2)
learner_turn, client_turn = response.turns
self.assertEqual([event.kind for event in learner_turn.nonverbal], ["silence", "pace", "barge_in", "audio"])
self.assertEqual(learner_turn.nonverbal[0].label, "침묵")
self.assertEqual(learner_turn.nonverbal[0].detail, "1.2초")
self.assertEqual(learner_turn.nonverbal[1].detail, "분당 420자")
self.assertEqual(client_turn.nonverbal, [])
async def test_review_includes_case_formulation_worksheet_draft(self) -> None:
principal = _principal()
sess = _session(principal)
created_at = sess.created_at
sess.turns.extend(
[
TurnRecord(
turn_seq=1,
speaker="counselor",
stage=sess.state.stage.value,
text="오늘은 어떤 목표로 이야기해보고 싶으세요?",
text_masked="오늘은 어떤 목표로 이야기해보고 싶으세요?",
created_at=created_at + 1,
),
TurnRecord(
turn_seq=2,
speaker="client",
stage=sess.state.stage.value,
text="요즘 너무 불안하고 친구 관계 스트레스 때문에 잠을 잘 못 자요.",
text_masked="요즘 너무 불안하고 친구 관계 스트레스 때문에 잠을 잘 못 자요.",
created_at=created_at + 2,
),
]
)
response = await sessions.get_session_review(sess.session_id, principal)
worksheet = response.caseWorksheet
self.assertEqual(worksheet.status, "draft_from_transcript")
self.assertGreaterEqual(len(worksheet.sections), 5)
exploration = worksheet.sections[0]
self.assertEqual(exploration.key, "exploration_11")
complaint = next(item for item in exploration.items if item.key == "presenting_complaint")
self.assertEqual(complaint.confidence, "medium")
self.assertEqual(complaint.evidence[0].turnId, "t2")
self.assertIn("불안", complaint.value or "")
risk = next(item for item in exploration.items if item.key == "risk")
self.assertEqual(risk.confidence, "none")
self.assertEqual(risk.evidence, [])
self.assertIn("명시 근거", risk.emptyReason or "")
if __name__ == "__main__":
unittest.main()

View file

@ -0,0 +1,124 @@
"""교수자 대시보드 집계 테스트."""
from __future__ import annotations
import unittest
from unittest.mock import AsyncMock, patch
from .deps import Principal, Role
from .routes import teacher
from .services import state_machine
from .services.persona import P1
from .store import InProcSession, TurnRecord
def _principal() -> Principal:
return Principal(
user_id="00000000-0000-0000-0000-000000000901",
role=Role.TEACHER,
)
def _session(
*,
session_id: str,
session_no: int,
learner_id: str,
score: str,
rapport: float,
technique: str,
created_at: float,
) -> InProcSession:
state = state_machine.init_state(params=P1.openness_params())
state.stage = state_machine.Stage.EXPLORE
return InProcSession(
session_id=session_id,
case_id=session_id,
learner_id=learner_id,
persona_code=P1.code,
theory_mode="humanistic",
persona=P1,
state=state,
session_no=session_no,
created_at=created_at,
ended_at=created_at + 600,
ended=True,
turns=[
TurnRecord(
turn_seq=1,
speaker="counselor",
stage=state.stage.value,
text="상담자 발화",
text_masked="상담자 발화",
evaluation={
"appropriateness": score,
"rapport_signal": rapport,
"techniques": [{"label": technique}],
},
),
TurnRecord(
turn_seq=2,
speaker="client",
stage=state.stage.value,
text="내담자 응답",
text_masked="내담자 응답",
),
],
)
class TeacherDashboardGrowthTest(unittest.IsolatedAsyncioTestCase):
async def test_dashboard_returns_learner_growth_from_turn_evaluations(self) -> None:
learner_id = "00000000-0000-0000-0000-000000000111"
sessions = [
_session(
session_id="00000000-0000-0000-0000-00000000a111",
session_no=1,
learner_id=learner_id,
score="neutral",
rapport=0.1,
technique="reflection",
created_at=1_000.0,
),
_session(
session_id="00000000-0000-0000-0000-00000000a112",
session_no=2,
learner_id=learner_id,
score="pos",
rapport=0.5,
technique="reflection",
created_at=2_000.0,
),
]
principal = _principal()
with (
patch.object(
teacher.session_persistence,
"list_sessions",
AsyncMock(return_value=(sessions, True)),
) as list_sessions,
patch.object(
teacher.session_persistence,
"list_safety_alerts",
AsyncMock(return_value=([], True)),
),
):
response = await teacher.teacher_dashboard(principal)
list_sessions.assert_awaited_once_with(principal, include_turn_evaluation=True)
self.assertEqual(response.total_learners, 1)
self.assertEqual(len(response.learner_growth), 1)
growth = response.learner_growth[0]
self.assertEqual(growth.sessions, 2)
self.assertEqual(growth.ended_sessions, 2)
self.assertEqual(growth.first_score, 0.5)
self.assertEqual(growth.latest_score, 1.0)
self.assertEqual(growth.score_delta, 0.5)
self.assertEqual(growth.trend, "up")
self.assertEqual(growth.top_techniques, ["reflection"])
self.assertEqual([point.session_no for point in growth.points], [1, 2])
if __name__ == "__main__":
unittest.main()

View file

@ -0,0 +1,193 @@
"""REST/WS 공용 턴 런타임 헬퍼.
세션 로드, 오너십 검증, 완료 턴 영속화, 상태 갱신은 REST 세션 라우트와
음성 WebSocket 라우트가 같은 규칙을 공유해야 한다.
"""
from __future__ import annotations
from enum import Enum
import json
from typing import Optional
from . import db, session_persistence
from .deps import Principal
from .runtime_policy import require_runtime_fallback_allowed, runtime_fallback_allowed
from .services import orchestrator, state_machine
from .store import InProcSession, TurnRecord, store
_STAGE_LABELS = {
"RAPPORT": "라포",
"EXPLORE": "탐색",
"INTERVENE": "개입",
"CLOSE": "정리",
}
def stage_label(stage: object) -> str:
"""Stage enum과 문자열 값을 같은 한글 라벨로 정규화한다."""
name = getattr(stage, "name", "")
return _STAGE_LABELS.get(name, str(getattr(stage, "value", stage)))
class SessionAccessError(str, Enum):
NOT_FOUND = "not_found"
FORBIDDEN = "forbidden"
ENDED = "ended"
async def load_owned_session(
session_id: str,
principal: Principal,
*,
allow_ended: bool = False,
include_turn_evaluation: bool = False,
) -> tuple[InProcSession | None, Optional[SessionAccessError]]:
"""DB 우선으로 학습자 소유 세션을 로드하고 접근 오류를 코드로 반환한다."""
sess = await session_persistence.load_session(
session_id,
principal,
allow_ended=True,
include_turn_evaluation=include_turn_evaluation,
)
if sess is not None:
store.put(sess)
elif runtime_fallback_allowed():
sess = store.get(session_id)
if sess is None:
return None, SessionAccessError.NOT_FOUND
if sess.learner_id != principal.user_id:
return None, SessionAccessError.FORBIDDEN
if sess.ended and not allow_ended:
return None, SessionAccessError.ENDED
return sess, None
async def append_completed_turn(
sess: InProcSession,
turn: TurnRecord,
*,
context: str,
) -> None:
"""완료된 턴을 DB와 in-process 미러에 기록한다."""
if await session_persistence.append_turn(
session_id=sess.session_id,
learner_id=sess.learner_id,
turn=turn,
):
sess.turns.append(turn)
store.put(sess)
return
require_runtime_fallback_allowed(context)
store.append_turn(sess.session_id, turn)
async def update_session_state(
sess: InProcSession,
state: state_machine.SessionState,
*,
context: str,
) -> None:
"""working state를 DB와 in-process 미러에 반영한다."""
if await session_persistence.update_state(
session_id=sess.session_id,
learner_id=sess.learner_id,
state=state,
):
sess.state = state
store.put(sess)
return
require_runtime_fallback_allowed(context)
store.update_state(sess.session_id, state)
async def record_completed_turn(
sess: InProcSession,
ctx: orchestrator.TurnContext,
result: orchestrator.TurnResult,
*,
context_prefix: str,
counselor_turn: TurnRecord | None = None,
) -> None:
"""상담자 발화와 내담자 응답을 한 번에 기록하고 상태를 갱신한다."""
assert ctx.state_after is not None
learner_turn = counselor_turn or TurnRecord(
turn_seq=ctx.state_after.turn_seq,
speaker="counselor",
stage=stage_label(ctx.state_after.stage),
text=ctx.learner_text_raw,
text_masked=ctx.learner_text_masked,
evaluation=result.evaluation,
)
await append_completed_turn(
sess,
learner_turn,
context=f"{context_prefix} turn append",
)
if result.client_reply:
await append_completed_turn(
sess,
TurnRecord(
turn_seq=result.turn_seq,
speaker="client",
stage=stage_label(result.state_after.stage),
text=result.client_reply,
text_masked=result.client_reply,
llm_provider=result.llm_provider,
model=result.model,
tokens_in=result.tokens_in,
tokens_out=result.tokens_out,
cost_usd=result.cost_usd,
),
context=f"{context_prefix} turn append",
)
await update_session_state(
sess,
result.state_after,
context=f"{context_prefix} state update",
)
async def record_safety_event(
sess: InProcSession,
ctx: orchestrator.TurnContext,
result: orchestrator.TurnResult,
) -> None:
"""위기 escalate 시 app.safety_events에 교수자 확인용 알림 레코드를 남긴다."""
crisis = getattr(ctx, "crisis", None)
if crisis is None or not getattr(crisis, "escalate", False):
return
kind = getattr(crisis.kind, "value", None) or str(getattr(crisis, "kind", "crisis"))
try:
async with db.acquire() as conn:
await conn.execute(
"""
INSERT INTO app.safety_events
(session_id, trigger_type, ko_risk_level, escalated, detail)
VALUES ($1::uuid, $2, $3, TRUE, $4::jsonb)
""",
sess.session_id,
kind,
int(getattr(crisis, "risk_level", 0) or 0),
json.dumps({
"matched": list(getattr(crisis, "matched", []) or []),
"stage": getattr(result, "stage", None),
"turn_seq": getattr(result, "turn_seq", None),
"conversation_stopped": getattr(result, "conversation_stopped", False),
"crisis_resource": getattr(result, "crisis_resource", None),
"alert_status": "teacher_dashboard",
}),
)
except Exception:
pass
__all__ = [
"SessionAccessError",
"append_completed_turn",
"load_owned_session",
"record_safety_event",
"record_completed_turn",
"stage_label",
"update_session_state",
]