schale 0.1.0__py3-none-any.whl

schale/__init__.py

@@ -0,0 +1,25 @@
+from .account import AccountSnapshot, GrowthValue, SourceReference, StudentState
+from .cache import CacheSettings, HttpCache
+from .inputs import ImageBatch, ImageInput, VideoInput
+from .reference import ReferenceCatalog
+from .stage_rewards import (
+    RewardExpectation,
+    RewardMultipliers,
+    StageRewards,
+)
+
+__all__ = [
+    "CacheSettings",
+    "HttpCache",
+    "ImageBatch",
+    "ImageInput",
+    "VideoInput",
+    "AccountSnapshot",
+    "GrowthValue",
+    "SourceReference",
+    "StudentState",
+    "ReferenceCatalog",
+    "RewardExpectation",
+    "RewardMultipliers",
+    "StageRewards",
+]

schale/__main__.py

@@ -0,0 +1,5 @@
+"""Support python -m schale in addition to the console command."""
+
+from .cli import app
+
+app()

schale/account.py

@@ -0,0 +1,93 @@
+"""Source-independent player state. Game definitions live in reference catalogs."""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, StrictInt, model_validator
+
+GROWTH_BOUNDS = {
+    "star": (1, 5),
+    "level": (1, 100),
+    "bond": (1, 100),
+    "ex": (1, 5),
+    "basic": (0, 10),
+    "passive": (0, 10),
+    "sub": (0, 10),
+    "weapon_star": (0, 4),
+    "weapon_level": (0, 100),
+    "gear": (0, 2),
+    **{f"equipment{i}": (0, 20) for i in range(1, 4)},
+    **{f"equipment{i}_level": (0, 100) for i in range(1, 4)},
+    **{f"potential_{s}": (0, 25) for s in ("hp", "attack", "heal")},
+}
+Status = Literal[
+    "unknown", "observed", "inferred", "confirmed", "corrected", "conflict", "imported"
+]
+
+
+class SourceReference(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    kind: str
+    uri: str
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class GrowthValue(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    value: StrictInt | None = None
+    status: Status = "unknown"
+    sources: list[SourceReference] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def coherent_status(self):
+        if self.status in {"unknown", "conflict"} and self.value is not None:
+            raise ValueError("Unknown/conflicting values must remain null")
+        if self.value is None and self.status not in {"unknown", "conflict"}:
+            raise ValueError("A known status requires a value")
+        return self
+
+
+class StudentState(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    key: str
+    student_id: StrictInt | None = Field(default=None, gt=0)
+    name: str = ""
+    identity_status: Status = "unknown"
+    fields: dict[str, GrowthValue] = Field(default_factory=dict)
+    sources: list[SourceReference] = Field(default_factory=list)
+    # Adapter-owned attributes such as a website's lock flag, not game state.
+    extensions: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def valid_fields(self):
+        for name, reading in self.fields.items():
+            if name not in GROWTH_BOUNDS:
+                raise ValueError(f"Unsupported growth field: {name}")
+            lo, hi = GROWTH_BOUNDS[name]
+            if reading.value is not None and not lo <= reading.value <= hi:
+                raise ValueError(f"Out-of-range growth field: {name}={reading.value}")
+        if self.student_id is None and self.identity_status not in {
+            "unknown",
+            "conflict",
+        }:
+            raise ValueError("An identified student needs a SchaleDB ID")
+        return self
+
+
+class AccountSnapshot(BaseModel):
+    """Portable schema v1; missing observations do not imply missing ownership."""
+
+    model_config = ConfigDict(extra="forbid")
+    schema_version: Literal[1] = 1
+    kind: Literal["schale.account"] = "schale.account"
+    sources: list[SourceReference] = Field(default_factory=list)
+    students: list[StudentState] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def unique_students(self):
+        ids = [s.student_id for s in self.students if s.student_id is not None]
+        keys = [s.key for s in self.students]
+        if len(ids) != len(set(ids)) or len(keys) != len(set(keys)):
+            raise ValueError(
+                "Duplicate student IDs or keys; resolve identity before merging"
+            )
+        return self

schale/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters translate external formats into the shared account model."""

schale/adapters/extraction.py

@@ -0,0 +1,58 @@
+"""Visual extraction is one input adapter, not the common state representation."""
+
+from ..account import AccountSnapshot, GrowthValue, SourceReference, StudentState
+from ..students.models import Extraction
+
+
+def from_extraction(result: Extraction) -> AccountSnapshot:
+    students = []
+    for student in result.students:
+        students.append(
+            StudentState.model_validate(
+                {
+                    "key": student.key,
+                    "student_id": student.student_id,
+                    "name": student.name,
+                    "identity_status": student.identity_status,
+                    "fields": {
+                        name: GrowthValue.model_validate(
+                            {
+                                "value": value.value,
+                                "status": value.status,
+                                "sources": [
+                                    SourceReference(
+                                        kind="visual-observation",
+                                        uri=e.image,
+                                        details=e.model_dump(exclude={"image"}),
+                                    )
+                                    for e in value.evidence
+                                ],
+                            }
+                        )
+                        for name, value in student.fields.items()
+                    },
+                    "sources": [
+                        SourceReference(
+                            kind="extraction",
+                            uri=result.source,
+                            details={"key": student.key, "visits": student.visits},
+                        )
+                    ],
+                }
+            )
+        )
+    return AccountSnapshot(
+        students=students,
+        sources=[
+            SourceReference(
+                kind="reference-catalog",
+                uri=result.catalog_url,
+                details={"dataset": "students", "sha256": result.catalog_sha256},
+            ),
+            SourceReference(
+                kind="extraction",
+                uri=result.source,
+                details={"revision": result.diagnostics.get("revision")},
+            ),
+        ],
+    )

schale/adapters/schaledb.py

@@ -0,0 +1,160 @@
+"""SchaleDB collection wire format isolated from the common account schema."""
+
+import base64
+import hashlib
+import json
+
+from ..account import (
+    AccountSnapshot,
+    GROWTH_BOUNDS,
+    GrowthValue,
+    SourceReference,
+    StudentState,
+)
+from ..reference import ReferenceCatalog
+
+KEYS = {
+    "star": "s",
+    "level": "l",
+    "bond": "b",
+    "ex": "s1",
+    "basic": "s2",
+    "passive": "s3",
+    "sub": "s4",
+    "equipment1": "e1",
+    "equipment2": "e2",
+    "equipment3": "e3",
+    "gear": "e4",
+    "weapon_star": "ws",
+    "weapon_level": "wl",
+    "potential_hp": "pm",
+    "potential_attack": "pa",
+    "potential_heal": "ph",
+}
+
+
+def decode_collection(text: str) -> dict:
+    try:
+        data = json.loads(base64.b64decode(text.strip(), validate=True))
+    except (ValueError, UnicodeDecodeError) as error:
+        raise ValueError("Invalid SchaleDB base64 JSON export") from error
+    if not isinstance(data, dict) or not all(
+        str(k).isdigit() and isinstance(v, dict) for k, v in data.items()
+    ):
+        raise ValueError("Unsupported SchaleDB collection structure")
+    for fields in data.values():
+        for key, value in fields.items():
+            if key in KEYS.values() and (
+                type(value) is not int or value < 0 or value > 100
+            ):
+                raise ValueError("Invalid numeric value in baseline collection")
+    return data
+
+
+def from_schaledb(
+    text: str,
+    *,
+    source: str = "schaledb-export",
+    catalog: ReferenceCatalog | None = None,
+) -> AccountSnapshot:
+    if catalog is not None and catalog.dataset != "students":
+        raise ValueError("A student reference catalog is required")
+    data = decode_collection(text)
+    reference = SourceReference(
+        kind="schaledb-collection",
+        uri=source,
+        details={"sha256": hashlib.sha256(text.strip().encode()).hexdigest()},
+    )
+    students = []
+    for sid, record in data.items():
+        name = str(catalog.get(int(sid)).get("Name", "")) if catalog else ""
+        students.append(
+            StudentState(
+                key=f"student_{int(sid)}",
+                student_id=int(sid),
+                name=name,
+                identity_status="imported",
+                fields={
+                    field: GrowthValue(
+                        value=record[key], status="imported", sources=[reference]
+                    )
+                    for field, key in KEYS.items()
+                    if key in record
+                },
+                sources=[reference],
+                extensions={
+                    "schaledb": {
+                        k: v for k, v in record.items() if k not in KEYS.values()
+                    }
+                },
+            )
+        )
+    sources = [reference]
+    if catalog:
+        sources.append(
+            SourceReference(
+                kind="reference-catalog",
+                uri=catalog.source,
+                details={"sha256": catalog.sha256, "dataset": catalog.dataset},
+            )
+        )
+    return AccountSnapshot(students=students, sources=sources)
+
+
+def to_schaledb(
+    snapshot: AccountSnapshot,
+    baseline: dict | None = None,
+    *,
+    allow_observed: bool = False,
+) -> tuple[str, dict]:
+    collection = json.loads(json.dumps(baseline or {}))
+    accepted = {"confirmed", "corrected", "imported"}
+    if allow_observed:
+        accepted.update(("observed", "inferred"))
+    skipped, updated = [], []
+    for student in snapshot.students:
+        if student.student_id is None or student.identity_status not in accepted:
+            skipped.append({"key": student.key, "reason": "identity not confirmed"})
+            continue
+        record = dict(collection.get(str(student.student_id), {}))
+        extras = student.extensions.get("schaledb", {})
+        if not isinstance(extras, dict):
+            raise ValueError("SchaleDB extension must be an object")
+        for key, value in extras.items():
+            if key not in KEYS.values():
+                record.setdefault(key, value)
+        for field, key in KEYS.items():
+            reading = student.fields.get(field)
+            if (
+                reading is None
+                or reading.value is None
+                or reading.status not in accepted
+            ):
+                continue
+            if not GROWTH_BOUNDS[field][0] <= reading.value <= GROWTH_BOUNDS[field][1]:
+                raise ValueError(f"Out-of-range extracted value: {student.key}/{field}")
+            value = reading.value
+            if field in ("basic", "passive", "sub") and value == 0:
+                value = 1
+            record[key] = value
+        missing = sorted(set(KEYS.values()) - record.keys())
+        if missing:
+            skipped.append(
+                {"key": student.key, "reason": "incomplete record", "missing": missing}
+            )
+            continue
+        record.setdefault("lock", False)
+        collection[str(student.student_id)] = record
+        updated.append(student.student_id)
+    if not updated:
+        raise ValueError(
+            "No complete confirmed records to export. Review missing fields or supply a baseline export."
+        )
+    raw = json.dumps(collection, separators=(",", ":"), ensure_ascii=True)
+    return base64.b64encode(raw.encode()).decode(), {
+        "updated": updated,
+        "skipped": skipped,
+        "total": len(collection),
+        "baseline_used": baseline is not None,
+        "warning": "SchaleDB import replaces the collection; use --base to preserve unscanned students.",
+    }

schale/assets.py

@@ -0,0 +1,215 @@
+"""Local, checksum-verified vision resources; no bundled game art or downloads."""
+
+import hashlib
+import json
+import os
+from pathlib import Path, PurePosixPath
+import re
+import shutil
+import stat
+import tempfile
+from zipfile import BadZipFile, ZIP_DEFLATED, ZipFile
+
+from filelock import FileLock
+
+from .cache import cache_directory
+
+PROFILE = "bluearchive-ko-16x9-v1"
+MAX_BYTES = 512 * 1024 * 1024
+REQUIRED = {
+    "students": {
+        "labels.json",
+        "header.png",
+        "empty_gear.png",
+        "ghost_gloves.png",
+        "ghost_shoes.png",
+        "ghost_hat.png",
+        "potential_hp_25.png",
+        "potential_attack_25.png",
+        "layout_reference.npz",
+    },
+    "inventory": {"models/equipment_classifier.onnx", "models/class_mapping.json"},
+}
+
+
+def resource_directory() -> Path:
+    return cache_directory() / "vision-resources"
+
+
+def _safe_name(name: str) -> bool:
+    parts = PurePosixPath(name).parts
+    return bool(
+        parts
+        and re.fullmatch(r"[A-Za-z0-9_./-]+", name)
+        and not name.startswith("/")
+        and "//" not in name
+        and all(p not in {".", ".."} and not p.endswith(".") for p in name.split("/"))
+        and all(
+            p.split(".")[0].upper()
+            not in {
+                "CON",
+                "PRN",
+                "AUX",
+                "NUL",
+                *[f"COM{i}" for i in range(10)],
+                *[f"LPT{i}" for i in range(10)],
+            }
+            for p in parts
+        )
+    )
+
+
+def _hash(path: Path) -> str:
+    with path.open("rb") as stream:
+        return hashlib.file_digest(stream, "sha256").hexdigest()
+
+
+def _inventory(directory: Path) -> dict[str, str]:
+    files = {}
+    size = 0
+    for path in sorted(directory.rglob("*")):
+        if path.is_symlink():
+            raise ValueError("Resource bundles cannot contain symbolic links")
+        if not path.is_file() or path == directory / "manifest.json":
+            continue
+        name = path.relative_to(directory).as_posix()
+        if not _safe_name(name) or name.split("/")[0] not in REQUIRED:
+            raise ValueError(f"Invalid resource path: {name}")
+        if path.suffix not in {".png", ".webp", ".json", ".npz", ".onnx", ".data"}:
+            raise ValueError(f"Unsupported resource file: {name}")
+        size += path.stat().st_size
+        files[name] = _hash(path)
+    if not files or len(files) > 4096 or size > MAX_BYTES:
+        raise ValueError("Resource bundle must contain 1..4096 files, at most 512 MiB")
+    if len({name.casefold() for name in files}) != len(files):
+        raise ValueError("Case-colliding resource paths")
+    for component in {name.split("/")[0] for name in files}:
+        missing = {f"{component}/{n}" for n in REQUIRED[component]} - files.keys()
+        if missing:
+            raise ValueError(f"Missing {component} resources: {sorted(missing)}")
+    if "students/labels.json" in files:
+        labels = json.loads(
+            (directory / "students/labels.json").read_text(encoding="utf-8")
+        )
+        if not isinstance(labels, list):
+            raise ValueError("Student labels must be a list")
+        for label in labels:
+            name = label.get("image") if isinstance(label, dict) else None
+            if (
+                not isinstance(name, str)
+                or not _safe_name(name)
+                or f"students/{name}" not in files
+            ):
+                raise ValueError("Student label references a missing or unsafe image")
+    return files
+
+
+def validate_resources(directory: Path) -> dict:
+    manifest = json.loads((directory / "manifest.json").read_text(encoding="utf-8"))
+    if (
+        not isinstance(manifest, dict)
+        or manifest.get("schema_version") != 1
+        or manifest.get("profile") != PROFILE
+    ):
+        raise ValueError("Unsupported vision resource profile")
+    if manifest.get("files") != _inventory(directory):
+        raise ValueError("Vision resource checksum or file inventory mismatch")
+    return manifest
+
+
+def pack_resources(source: Path, output: Path) -> None:
+    """Package a user's own reference directory; never infer redistribution rights."""
+    source, output = source.resolve(), output.resolve()
+    files = _inventory(source)
+    manifest = {"schema_version": 1, "profile": PROFILE, "files": files}
+    output.parent.mkdir(parents=True, exist_ok=True)
+    # Exclusive create: preserve any existing bundle.
+    with output.open("xb") as stream, ZipFile(stream, "w", ZIP_DEFLATED) as archive:
+        archive.writestr(
+            "manifest.json", json.dumps(manifest, sort_keys=True, indent=2)
+        )
+        for name in files:
+            archive.write(source / name, name)
+
+
+def install_resources(source: Path) -> Path:
+    """Install immutable content-addressed resources and atomically select them."""
+    root = resource_directory()
+    root.mkdir(parents=True, exist_ok=True)
+    with (
+        FileLock(str(root / "install.lock")),
+        tempfile.TemporaryDirectory(prefix=".install-", dir=root) as temporary,
+    ):
+        stage = Path(temporary) / "bundle"
+        stage.mkdir()
+        try:
+            with ZipFile(source) as archive:
+                members = archive.infolist()
+                if (
+                    not members
+                    or len(members) > 4097
+                    or len({m.filename.casefold() for m in members}) != len(members)
+                    or sum(m.file_size for m in members) > MAX_BYTES + 1024 * 1024
+                    or any(
+                        m.orig_filename != m.filename
+                        or not _safe_name(m.filename)
+                        or m.is_dir()
+                        or stat.S_ISLNK(m.external_attr >> 16)
+                        for m in members
+                    )
+                ):
+                    raise ValueError("Unsafe or oversized resource ZIP")
+                for member in members:
+                    path = stage / member.filename
+                    path.parent.mkdir(parents=True, exist_ok=True)
+                    with archive.open(member) as incoming, path.open("xb") as outgoing:
+                        shutil.copyfileobj(incoming, outgoing)
+        except BadZipFile as error:
+            raise ValueError("Resources must be a valid ZIP bundle") from error
+        manifest = validate_resources(stage)
+        digest = hashlib.sha256(
+            json.dumps(manifest, sort_keys=True).encode()
+        ).hexdigest()
+        target = root / "bundles" / digest
+        target.parent.mkdir(exist_ok=True)
+        if target.exists():
+            validate_resources(target)
+        else:
+            stage.rename(target)
+        pointer = Path(temporary) / "current.json"
+        pointer.write_text(json.dumps({"bundle": digest}), encoding="utf-8")
+        os.replace(pointer, root / "current.json")
+    return target
+
+
+def resolve_resources(component: str, *, verify: bool = True) -> Path:
+    if component not in REQUIRED:
+        raise ValueError(f"Unknown resource component: {component}")
+    root = resource_directory()
+    try:
+        selection = json.loads((root / "current.json").read_text(encoding="utf-8"))
+        digest = selection.get("bundle") if isinstance(selection, dict) else None
+        if not isinstance(digest, str) or re.fullmatch(r"[0-9a-f]{64}", digest) is None:
+            raise ValueError("Invalid resource selection")
+        directory = root / "bundles" / digest
+        if verify:
+            validate_resources(directory)
+        if not (directory / component).is_dir():
+            raise ValueError(f"Bundle has no {component} resources")
+        return directory / component
+    except (OSError, ValueError) as error:
+        raise ValueError(
+            f"Vision resources unavailable for {component}: {error}. "
+            "Install your trusted local bundle with 'schale assets install BUNDLE.zip'."
+        ) from error
+
+
+def resource_report() -> dict:
+    report: dict = {"cache": str(resource_directory()), "components": {}}
+    for component in REQUIRED:
+        try:
+            path = resolve_resources(component)
+            report["components"][component] = {"valid": True, "path": str(path)}
+        except ValueError as error:
+            report["components"][component] = {"valid": False, "error": str(error)}
+    return report

schale/assets_cli.py

@@ -0,0 +1,49 @@
+"""Manage private local vision resources without importing vision runtimes."""
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from .assets import install_resources, pack_resources, resource_report
+
+assets_app = typer.Typer(
+    help="Install and verify your local vision resources; no downloads"
+)
+
+
+@assets_app.command("pack")
+def pack(
+    source: Annotated[Path, typer.Argument(exists=True, file_okay=False)],
+    output: Annotated[Path, typer.Option("--output", "-o")],
+) -> None:
+    """Build a ZIP from your reference directory; this grants no distribution rights."""
+    try:
+        pack_resources(source, output)
+    except (OSError, ValueError) as error:
+        typer.echo(f"Resource packaging failed: {error}", err=True)
+        raise typer.Exit(1) from error
+    typer.echo(f"Created: {output.resolve()}")
+
+
+@assets_app.command("install")
+def install(
+    source: Annotated[Path, typer.Argument(exists=True, dir_okay=False)],
+) -> None:
+    """Verify and activate a trusted local ZIP. Previous versions are retained."""
+    try:
+        installed = install_resources(source)
+    except (OSError, ValueError) as error:
+        typer.echo(f"Resource installation failed: {error}", err=True)
+        raise typer.Exit(1) from error
+    typer.echo(f"Installed: {installed}")
+
+
+@assets_app.command("info")
+def info() -> None:
+    """Check all installed reference files against their SHA-256 manifest."""
+    report = resource_report()
+    typer.echo(json.dumps(report, ensure_ascii=False, indent=2))
+    if not all(row["valid"] for row in report["components"].values()):
+        raise typer.Exit(1)