schale 0.1.0__tar.gz

schale-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: Package and contracts
+on: [push, pull_request, workflow_dispatch]
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.12', '3.13']
+    runs-on: ${{ matrix.os }}
+    env:
+      SCHALE_CACHE_DIR: ${{ github.workspace }}/.schale/ci-cache
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked --no-default-groups --group test
+      - run: uv run --no-default-groups --group test pytest tests/test_assets.py tests/test_inventory_onnx.py tests/test_dependency_policy.py tests/test_http_cache.py tests/test_inputs.py tests/test_toolkit.py tests/test_students.py tests/test_students_numeric.py tests/test_students_layout.py tests/test_students_inspector.py tests/test_distribution.py -q
+      - run: uv build --no-sources
+      - run: uv run --no-default-groups python scripts/check_distribution.py dist/schale-0.1.0-py3-none-any.whl dist/schale-0.1.0.tar.gz
+      - run: uvx twine check --strict dist/schale-0.1.0-py3-none-any.whl dist/schale-0.1.0.tar.gz

schale-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 — 최초 공개 버전
+
+- 학생·인벤토리의 공통 ONNX CTC 엔진. 실행용 extras는 Torch/EasyOCR 없이 동작하며 학습은 명시적 `training` 그룹으로 분리.
+- 인벤토리 격자 정합, 카탈로그 아이콘 검증, 수량 실패/축약 구분, 칸별 ROI·후보·판독 근거와 정확도 대조 보고서.
+- SchaleDB 호환 자동화 툴킷: 기준 데이터, 공통 계정 모델, 컬렉션 import/diff/merge/export, 보상 계산.
+- 영상·단일 이미지·폴더·목록·인코딩 bytes·이미지 매니페스트를 받는 공통 추출 API.
+- 이미지 중복 픽셀 제거, 내용 기반 입력 지문, 이미지 순서 기반 감독 보고서.
+- JSON·스킬·초상화·장비 아이콘의 공유 HTTP 캐시: TTL, ETag/Last-Modified, SHA-256, 원자 저장, 내용 중복 제거, 변경 이력.
+- 자동/수동/오프라인 정책, 증분 갱신 CLI, 동시 요청 합치기, 속도 제한, 오류 재시도 유예.
+- 선택형 ONNX 학생 인식, UI 정합·ROI 감독, 모델 설치와 무결성 검사.
+- MIT 및 제3자 고지, API/사용/확장 문서, 테스트·빌드·배포 검사.
+- 코드와 게임 참조·학습 모델의 분리. 로컬 자원 ZIP 설치, SHA-256 검증, 내용별 캐시 저장과 이전 버전 보존.
+
+게임 이미지·UI 참조·학습 모델은 Git 소스 및 Python 배포본에 포함하지 않습니다. 비전 기능은 사용자가 준비한 별도 로컬 자원을 사용합니다.

schale-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# 개발 안내
+
+Python 3.12+와 uv를 사용합니다. [구조와 확장 계약](docs/architecture.md)을 먼저 확인하세요.
+
+```powershell
+# 학습/인벤토리 개발 의존성 없는 회귀 테스트
+uv sync --no-default-groups --group test
+uv run --no-default-groups --group test pytest tests/test_toolkit.py tests/test_students.py tests/test_students_numeric.py tests/test_students_layout.py tests/test_students_inspector.py tests/test_distribution.py -q
+
+# 기본 개발 환경: 학생 ONNX 추론과 테스트, Torch/EasyOCR 제외
+uv sync
+uv run pytest -q
+
+# 학습/CNN 비교 실험을 개발할 때만 (CPU Torch 포함)
+uv run --group training pytest tests/test_students_benchmark.py -q
+
+# 인벤토리 ONNX 계약 (Torch 불필요)
+uv run pytest tests/test_inventory_onnx.py tests/test_scanner.py -q
+```
+
+Torch가 없는 환경에서는 학습 전용 `test_students_benchmark.py` 모듈을 건너뜁니다. 로컬 장비 모델이 없으면 해당 모델 통합 검사도 건너뜁니다. 게임 자원 없는 CI는 생성한 도형·배열로 계약을 검증하며 실제 정확도는 별도 평가합니다. 학습 코드를 수정할 때는 반드시 `training` 그룹을 선택해 해당 테스트를 실행하세요. 학습 모듈을 포함하는 프로젝트 전체 타입 검사는 `uv run --group training pyright`로 수행합니다.
+
+단위 테스트는 최소 fixture로 계약을 검증합니다. fixture 추론 모델은 정확도 평가에 쓰지 않습니다. `test_parsing.py`는 SchaleDB 접속 또는 캐시가 필요합니다. `test_scanner.py`의 일부는 별도 예제 이미지가 없으면 건너뜁니다. 실제 정확도는 동의하에 제공된 영상과 독립 정답으로 검증하고 개인 영상·계정 JSON을 저장소/배포본에 넣지 않습니다.
+
+새 기능에는 Python API, 필요한 CLI, 데이터 보존·실패 테스트, 사용 예시를 함께 추가하세요. 기존 `students` 명령과 `Extraction` 형식은 보존합니다. 의존성은 필요한 extra에만 넣고 코어 import가 비전 런타임을 로드하지 않는지 검사합니다. 변경 파일은 Ruff 검사/포맷을 적용하고 프로젝트 전체 Pyright를 확인합니다.
+
+UI 판독 변경은 원본 영상·미사용 촬영 조건 검증이 필요합니다. 기존 입력 통과를 일반화 보증으로 표현하지 않습니다. [배포 절차](docs/releasing.md)의 실제 모델 검증은 CI의 패키지·회귀 검사와 별개입니다.

schale-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 schale contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

schale-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: schale
+Version: 0.1.0
+Summary: SchaleDB-compatible Blue Archive automation toolkit: data, collections, rewards, and vision
+Keywords: blue-archive,schaledb,automation,collections,computer-vision
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: requests>=2.32.5
+Requires-Dist: typer>=0.15.3
+Requires-Dist: filelock>=3.20.3
+Requires-Dist: opencv-python>=4.10.0 ; extra == 'scanner'
+Requires-Dist: pillow>=10.0 ; extra == 'scanner'
+Requires-Dist: numpy>=1.26.0 ; extra == 'scanner'
+Requires-Dist: onnxruntime>=1.23.2 ; extra == 'scanner'
+Requires-Dist: opencv-python>=4.10.0 ; extra == 'student-ocr'
+Requires-Dist: numpy>=1.26.0 ; extra == 'student-ocr'
+Requires-Dist: pillow>=10.0 ; extra == 'student-ocr'
+Requires-Dist: onnxruntime>=1.23.2 ; extra == 'student-ocr'
+Requires-Dist: opencv-python>=4.10.0 ; extra == 'vision'
+Requires-Dist: numpy>=1.26.0 ; extra == 'vision'
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/c0sogi/schale
+Project-URL: Issues, https://github.com/c0sogi/schale/issues
+Provides-Extra: scanner
+Provides-Extra: student-ocr
+Provides-Extra: vision
+Description-Content-Type: text/markdown
+
+# Schale
+
+**SchaleDB 데이터와 호환되는 Blue Archive 자동화 툴킷.**
+
+게임의 기준 데이터와 사용자의 계정 상태를 연결하고, 반복적인 정보 수집·비교·갱신·계산을 재사용 가능한 Python API와 CLI로 제공합니다. 영상 인식은 여러 입력 방식 중 하나입니다. 새로운 도구도 같은 학생 ID와 공통 데이터 모델을 사용해 기존 도구와 조합할 수 있도록 확장합니다.
+
+## 설계 원칙
+
+- **SchaleDB 호환성:** 기준 ID를 재사용하고, 사이트 저장 형식은 어댑터에서 처리합니다.
+- **관측과 사실의 구분:** 값, 확인 상태, 출처를 함께 보관합니다. 미확인은 0이 아니며, 화면에 없었다고 미보유로 판단하지 않습니다.
+- **조합 가능한 도구:** 데이터 조회, 계정 처리, 보상 계산, 비전 추출을 독립적으로 실행하거나 Python에서 연결합니다.
+- **가벼운 코어:** 일반 데이터 자동화에는 OpenCV·ONNX Runtime·PyTorch가 필요하지 않습니다.
+- **검토 가능한 자동화:** 원본을 보존하고 병합·내보내기의 적용 및 보류 이유를 남깁니다. 사이트 업로드나 게임 조작은 자동 실행하지 않습니다.
+
+## 현재 기능
+
+| 기능 | CLI | 결과 |
+|---|---|---|
+| SchaleDB 기준 데이터 조회 | `data fetch` | 정의 JSON + 출처·내용 해시 |
+| 사이트 육성정보 가져오기 | `collection import` | 공통 `AccountSnapshot` |
+| 영상 추출 결과 연결 | `collection from-extraction` | 19개 육성 필드·상태·시각 근거 |
+| 계정 비교·안전한 갱신 | `collection diff`, `collection merge` | 변경 내역, 병합 결과·보류 보고서 |
+| SchaleDB 호환 내보내기 | `collection export` | 사이트 가져오기 문자열 + 보고서 |
+| 스테이지 보상 기대값 | `rewards calculate` | 서버·조건별 1회 보상 기대값 |
+| 학생 정보 영상·스크린샷 분석 | `students extract`, `students inspect` | 학생별 이미지·판독·감독 화면 |
+| 인벤토리 스캔 | `scan` | 아이템 ID·티어·수량 표기·칸별 판독 근거 |
+
+소재 소요량 계산, 육성 계획 최적화, 새로운 화면/게임 조작 자동화는 향후 확장 대상이며 0.1.0의 구현 기능에 포함하지 않습니다.
+
+## 설치
+
+Python 3.12 이상이 필요합니다.
+
+```powershell
+# CLI: 데이터·계정·보상 도구
+uv tool install "schale==0.1.0"
+# Python 프로젝트에 추가할 때
+uv add "schale==0.1.0"
+```
+
+학생 비전도 사용하려면 위 CLI 설치 대신 다음으로 설치합니다. 기본 설치가 이미 있다면 `uv tool install --reinstall`로 extras를 추가하세요.
+
+```powershell
+uv tool install "schale[student-ocr,scanner]==0.1.0"
+schale assets install ".\my-vision-resources.zip"
+schale students install-model ".\schale-student-numeric-v1.zip"
+schale students doctor
+```
+
+영상 처리에는 별도 설치한 `ffmpeg`와 `ffprobe`가 PATH에 있어야 합니다. 학생 인식은 `student-ocr`, 인벤토리는 `scanner`, 템플릿 전용은 `vision` extra입니다. 학생·인벤토리 문자 인식은 같은 ONNX 엔진과 별도 설치한 문자 모델을 공유합니다.
+
+**PyPI 패키지는 코드만 제공합니다.** 게임 이미지·UI 참조·장비 모델은 포함하지 않으며 자동으로 내려받지 않습니다. 비전 기능에는 사용자가 별도로 준비한 신뢰할 수 있는 로컬 참조 번들과 문자 모델이 필요합니다. 현재 공개 배포하는 게임 참조 번들은 없습니다. 자원 준비 전에도 데이터·계정·보상 기능은 사용할 수 있습니다. [로컬 비전 자원 구성](docs/assets.md)을 확인하세요.
+
+모든 실행용 extras와 기본 개발·테스트 환경은 Torch/EasyOCR를 설치하지 않습니다. 학습·CNN 비교 실험만 `uv run --group training ...`으로 선택하며 CPU Torch를 사용합니다.
+
+## 계정 워크플로
+
+사이트의 기존 컬렉션을 보존하면서 새 영상의 확인된 값만 반영하는 예입니다. 출력 경로는 새 파일/폴더여야 합니다.
+
+```powershell
+schale data fetch students --region kr --output students.json
+schale collection import existing-export.txt --catalog students.json --output account.json
+schale students extract recording.mp4 --output recording-result
+schale collection from-extraction recording-result/results.json --output observed.json
+schale collection diff account.json observed.json --output differences.json
+schale collection merge account.json observed.json --output merged.json
+schale collection export merged.json --base existing-export.txt --output schaledb.txt
+```
+
+비전 없이 사이트 내보내기 두 개를 각각 가져와 비교·병합할 수도 있습니다. 기본 병합은 `confirmed`, `corrected`, `imported` 값만 수용합니다. 미확인 신원/필드는 보고서에 보류하며 원본 관측 파일에 남습니다. 관측 시각으로 자동 정렬하지 않으므로 **incoming은 사용자가 최신 또는 우선할 데이터로 선택**해야 합니다.
+
+SchaleDB 가져오기는 컬렉션 전체를 교체합니다. 기존 사이트 내보내기를 보관하고 `--base`로 전달하세요. 도구는 사이트 계정을 변경하지 않습니다. 장비 자체 레벨은 공통 모델에 남지만 사이트 포맷에 없어 내보내지 못합니다. 잠긴 일반 스킬의 0은 사이트 최소값 1로 변환됩니다.
+
+```powershell
+schale rewards calculate --stage 1011101 --server Global --output rewards.json
+schale rewards calculate --stage 1011101 --condition FirstClear --output first-clear.json
+```
+
+기본은 조건 없는 보상이며 `--condition`은 해당 조건의 보상을 추가합니다. 기대값은 확정 드롭 수량이나 최적 파밍 계획이 아닙니다.
+
+## 유연한 입력
+
+```python
+from pathlib import Path
+from schale import ImageBatch, ImageInput
+from schale.students.extract import extract
+
+extract(Path("recording.mp4"), Path("out-video"))
+extract(Path("screenshots"), Path("out-folder"))
+extract([Path("a.png"), Path("b.webp")], Path("out-list"))
+extract(ImageBatch([ImageInput(Path("a.png").read_bytes(), name="capture")]), Path("out-memory"))
+```
+
+단일 이미지, 디렉터리, 명시적 이미지 목록, 인코딩된 이미지 bytes, JSON 매니페스트를 받습니다. 동일 픽셀은 중복 제거하여 확인 근거를 부풀리지 않습니다. [입력 계약과 예시](docs/inputs.md)를 참고하세요.
+
+## Python API
+
+```python
+from pathlib import Path
+from schale import AccountSnapshot, ReferenceCatalog, StageRewards
+from schale.adapters.schaledb import from_schaledb, to_schaledb
+from schale.collections import compare, merge
+
+catalog = ReferenceCatalog.fetch("students", region="kr")
+base = from_schaledb(Path("existing-export.txt").read_text(), catalog=catalog)
+incoming = AccountSnapshot.model_validate_json(Path("observed.json").read_text())
+changes = compare(base, incoming)
+updated, merge_report = merge(base, incoming)
+encoded, export_report = to_schaledb(updated)
+rewards = StageRewards.from_stages([1011101], server="Global")
+```
+
+학생 추출은 `schale.students.extract.extract`, 보상 계산은 `StageRewards`, 계정 교환은 `schale.adapters`에서 제공합니다. 학생 추출 결과는 `Extraction/results.json`과 원본 판독 근거로 구성됩니다.
+
+## 캐시와 지원 범위
+
+공유 캐시는 사용자 홈의 `.schale/cache`이며 `SCHALE_CACHE_DIR`로 변경합니다. 모든 SchaleDB JSON·이미지는 조건부 HTTP 캐시를 사용합니다. 기본 자동 모드는 사용 시 만료된 항목만 갱신하며, 유효 기간 안에는 HTTP 요청을 하지 않습니다. JSON 7일·이미지 30일 TTL, ETag/Last-Modified 재검증, SHA-256 무결성 확인, 콘텐츠 중복 제거, 프로세스 간 요청 합치기, 요청 간격 제한과 오류 재시도 유예를 제공합니다. 사용자 영상/계정은 캐시에 넣지 않습니다.
+
+```powershell
+schale cache info
+schale cache update                 # 이미 사용한 리소스 중 만료/누락만
+schale cache update --refresh       # 유효한 항목도 조건부 재검증
+schale cache history
+schale cache verify
+schale cache policy --mode manual   # 자동 재검증 끄기 (최초 누락은 받음)
+schale cache policy --mode offline  # 최초 누락도 받지 않음
+schale cache policy --mode auto
+```
+
+캐시는 파일 단위 증분입니다. 서버가 변경을 알리면 해당 JSON/이미지를 다시 받으며, JSON 내부 개별 학생만 전송받는 delta API는 사용하지 않습니다. 실패 시 검증된 이전 버전만 사용하고 오류/재시도 시각을 기록합니다. 숫자 모델은 신뢰할 수 있는 로컬 번들을 별도 설치하며 자동 원격 교체하지 않습니다. [캐시 정책과 트래픽](docs/cache.md)을 참고하세요.
+
+학생 비전은 한국어 16:9 정보 화면용입니다. 위치·균일 배율 차이를 보정하지만 모든 언어·레이아웃·촬영 조건을 지원하지 않습니다. `confirmed`는 다중 관측 일치이며 정답 보증이 아닙니다. Windows에서 배포본의 실제 영상 실행을 검증합니다. 다른 OS는 별도 실행 검증이 필요합니다.
+
+## 문서
+
+- [구조와 확장 계약](docs/architecture.md)
+- [캐시 정책·증분 업데이트](docs/cache.md), [유연한 입력](docs/inputs.md)
+- [로컬 비전 자원 설치·검증·구성](docs/assets.md)
+- [학생 추출·검토·알고리즘 감독](docs/students.md)
+- [인벤토리 판독·정확도 검증](docs/inventory.md)
+- [개발 및 테스트](CONTRIBUTING.md)
+- [배포 절차](docs/releasing.md), [변경 이력](CHANGELOG.md)
+
+자체 코드는 MIT입니다. SchaleDB·Blue Archive의 공식 프로젝트가 아니며 모델·게임 이미지·상표의 권리는 원 권리자에게 있습니다. [제3자 고지](THIRD_PARTY_NOTICES.md)를 확인하세요.

schale-0.1.0/README.md

@@ -0,0 +1,144 @@
+# Schale
+
+**SchaleDB 데이터와 호환되는 Blue Archive 자동화 툴킷.**
+
+게임의 기준 데이터와 사용자의 계정 상태를 연결하고, 반복적인 정보 수집·비교·갱신·계산을 재사용 가능한 Python API와 CLI로 제공합니다. 영상 인식은 여러 입력 방식 중 하나입니다. 새로운 도구도 같은 학생 ID와 공통 데이터 모델을 사용해 기존 도구와 조합할 수 있도록 확장합니다.
+
+## 설계 원칙
+
+- **SchaleDB 호환성:** 기준 ID를 재사용하고, 사이트 저장 형식은 어댑터에서 처리합니다.
+- **관측과 사실의 구분:** 값, 확인 상태, 출처를 함께 보관합니다. 미확인은 0이 아니며, 화면에 없었다고 미보유로 판단하지 않습니다.
+- **조합 가능한 도구:** 데이터 조회, 계정 처리, 보상 계산, 비전 추출을 독립적으로 실행하거나 Python에서 연결합니다.
+- **가벼운 코어:** 일반 데이터 자동화에는 OpenCV·ONNX Runtime·PyTorch가 필요하지 않습니다.
+- **검토 가능한 자동화:** 원본을 보존하고 병합·내보내기의 적용 및 보류 이유를 남깁니다. 사이트 업로드나 게임 조작은 자동 실행하지 않습니다.
+
+## 현재 기능
+
+| 기능 | CLI | 결과 |
+|---|---|---|
+| SchaleDB 기준 데이터 조회 | `data fetch` | 정의 JSON + 출처·내용 해시 |
+| 사이트 육성정보 가져오기 | `collection import` | 공통 `AccountSnapshot` |
+| 영상 추출 결과 연결 | `collection from-extraction` | 19개 육성 필드·상태·시각 근거 |
+| 계정 비교·안전한 갱신 | `collection diff`, `collection merge` | 변경 내역, 병합 결과·보류 보고서 |
+| SchaleDB 호환 내보내기 | `collection export` | 사이트 가져오기 문자열 + 보고서 |
+| 스테이지 보상 기대값 | `rewards calculate` | 서버·조건별 1회 보상 기대값 |
+| 학생 정보 영상·스크린샷 분석 | `students extract`, `students inspect` | 학생별 이미지·판독·감독 화면 |
+| 인벤토리 스캔 | `scan` | 아이템 ID·티어·수량 표기·칸별 판독 근거 |
+
+소재 소요량 계산, 육성 계획 최적화, 새로운 화면/게임 조작 자동화는 향후 확장 대상이며 0.1.0의 구현 기능에 포함하지 않습니다.
+
+## 설치
+
+Python 3.12 이상이 필요합니다.
+
+```powershell
+# CLI: 데이터·계정·보상 도구
+uv tool install "schale==0.1.0"
+# Python 프로젝트에 추가할 때
+uv add "schale==0.1.0"
+```
+
+학생 비전도 사용하려면 위 CLI 설치 대신 다음으로 설치합니다. 기본 설치가 이미 있다면 `uv tool install --reinstall`로 extras를 추가하세요.
+
+```powershell
+uv tool install "schale[student-ocr,scanner]==0.1.0"
+schale assets install ".\my-vision-resources.zip"
+schale students install-model ".\schale-student-numeric-v1.zip"
+schale students doctor
+```
+
+영상 처리에는 별도 설치한 `ffmpeg`와 `ffprobe`가 PATH에 있어야 합니다. 학생 인식은 `student-ocr`, 인벤토리는 `scanner`, 템플릿 전용은 `vision` extra입니다. 학생·인벤토리 문자 인식은 같은 ONNX 엔진과 별도 설치한 문자 모델을 공유합니다.
+
+**PyPI 패키지는 코드만 제공합니다.** 게임 이미지·UI 참조·장비 모델은 포함하지 않으며 자동으로 내려받지 않습니다. 비전 기능에는 사용자가 별도로 준비한 신뢰할 수 있는 로컬 참조 번들과 문자 모델이 필요합니다. 현재 공개 배포하는 게임 참조 번들은 없습니다. 자원 준비 전에도 데이터·계정·보상 기능은 사용할 수 있습니다. [로컬 비전 자원 구성](docs/assets.md)을 확인하세요.
+
+모든 실행용 extras와 기본 개발·테스트 환경은 Torch/EasyOCR를 설치하지 않습니다. 학습·CNN 비교 실험만 `uv run --group training ...`으로 선택하며 CPU Torch를 사용합니다.
+
+## 계정 워크플로
+
+사이트의 기존 컬렉션을 보존하면서 새 영상의 확인된 값만 반영하는 예입니다. 출력 경로는 새 파일/폴더여야 합니다.
+
+```powershell
+schale data fetch students --region kr --output students.json
+schale collection import existing-export.txt --catalog students.json --output account.json
+schale students extract recording.mp4 --output recording-result
+schale collection from-extraction recording-result/results.json --output observed.json
+schale collection diff account.json observed.json --output differences.json
+schale collection merge account.json observed.json --output merged.json
+schale collection export merged.json --base existing-export.txt --output schaledb.txt
+```
+
+비전 없이 사이트 내보내기 두 개를 각각 가져와 비교·병합할 수도 있습니다. 기본 병합은 `confirmed`, `corrected`, `imported` 값만 수용합니다. 미확인 신원/필드는 보고서에 보류하며 원본 관측 파일에 남습니다. 관측 시각으로 자동 정렬하지 않으므로 **incoming은 사용자가 최신 또는 우선할 데이터로 선택**해야 합니다.
+
+SchaleDB 가져오기는 컬렉션 전체를 교체합니다. 기존 사이트 내보내기를 보관하고 `--base`로 전달하세요. 도구는 사이트 계정을 변경하지 않습니다. 장비 자체 레벨은 공통 모델에 남지만 사이트 포맷에 없어 내보내지 못합니다. 잠긴 일반 스킬의 0은 사이트 최소값 1로 변환됩니다.
+
+```powershell
+schale rewards calculate --stage 1011101 --server Global --output rewards.json
+schale rewards calculate --stage 1011101 --condition FirstClear --output first-clear.json
+```
+
+기본은 조건 없는 보상이며 `--condition`은 해당 조건의 보상을 추가합니다. 기대값은 확정 드롭 수량이나 최적 파밍 계획이 아닙니다.
+
+## 유연한 입력
+
+```python
+from pathlib import Path
+from schale import ImageBatch, ImageInput
+from schale.students.extract import extract
+
+extract(Path("recording.mp4"), Path("out-video"))
+extract(Path("screenshots"), Path("out-folder"))
+extract([Path("a.png"), Path("b.webp")], Path("out-list"))
+extract(ImageBatch([ImageInput(Path("a.png").read_bytes(), name="capture")]), Path("out-memory"))
+```
+
+단일 이미지, 디렉터리, 명시적 이미지 목록, 인코딩된 이미지 bytes, JSON 매니페스트를 받습니다. 동일 픽셀은 중복 제거하여 확인 근거를 부풀리지 않습니다. [입력 계약과 예시](docs/inputs.md)를 참고하세요.
+
+## Python API
+
+```python
+from pathlib import Path
+from schale import AccountSnapshot, ReferenceCatalog, StageRewards
+from schale.adapters.schaledb import from_schaledb, to_schaledb
+from schale.collections import compare, merge
+
+catalog = ReferenceCatalog.fetch("students", region="kr")
+base = from_schaledb(Path("existing-export.txt").read_text(), catalog=catalog)
+incoming = AccountSnapshot.model_validate_json(Path("observed.json").read_text())
+changes = compare(base, incoming)
+updated, merge_report = merge(base, incoming)
+encoded, export_report = to_schaledb(updated)
+rewards = StageRewards.from_stages([1011101], server="Global")
+```
+
+학생 추출은 `schale.students.extract.extract`, 보상 계산은 `StageRewards`, 계정 교환은 `schale.adapters`에서 제공합니다. 학생 추출 결과는 `Extraction/results.json`과 원본 판독 근거로 구성됩니다.
+
+## 캐시와 지원 범위
+
+공유 캐시는 사용자 홈의 `.schale/cache`이며 `SCHALE_CACHE_DIR`로 변경합니다. 모든 SchaleDB JSON·이미지는 조건부 HTTP 캐시를 사용합니다. 기본 자동 모드는 사용 시 만료된 항목만 갱신하며, 유효 기간 안에는 HTTP 요청을 하지 않습니다. JSON 7일·이미지 30일 TTL, ETag/Last-Modified 재검증, SHA-256 무결성 확인, 콘텐츠 중복 제거, 프로세스 간 요청 합치기, 요청 간격 제한과 오류 재시도 유예를 제공합니다. 사용자 영상/계정은 캐시에 넣지 않습니다.
+
+```powershell
+schale cache info
+schale cache update                 # 이미 사용한 리소스 중 만료/누락만
+schale cache update --refresh       # 유효한 항목도 조건부 재검증
+schale cache history
+schale cache verify
+schale cache policy --mode manual   # 자동 재검증 끄기 (최초 누락은 받음)
+schale cache policy --mode offline  # 최초 누락도 받지 않음
+schale cache policy --mode auto
+```
+
+캐시는 파일 단위 증분입니다. 서버가 변경을 알리면 해당 JSON/이미지를 다시 받으며, JSON 내부 개별 학생만 전송받는 delta API는 사용하지 않습니다. 실패 시 검증된 이전 버전만 사용하고 오류/재시도 시각을 기록합니다. 숫자 모델은 신뢰할 수 있는 로컬 번들을 별도 설치하며 자동 원격 교체하지 않습니다. [캐시 정책과 트래픽](docs/cache.md)을 참고하세요.
+
+학생 비전은 한국어 16:9 정보 화면용입니다. 위치·균일 배율 차이를 보정하지만 모든 언어·레이아웃·촬영 조건을 지원하지 않습니다. `confirmed`는 다중 관측 일치이며 정답 보증이 아닙니다. Windows에서 배포본의 실제 영상 실행을 검증합니다. 다른 OS는 별도 실행 검증이 필요합니다.
+
+## 문서
+
+- [구조와 확장 계약](docs/architecture.md)
+- [캐시 정책·증분 업데이트](docs/cache.md), [유연한 입력](docs/inputs.md)
+- [로컬 비전 자원 설치·검증·구성](docs/assets.md)
+- [학생 추출·검토·알고리즘 감독](docs/students.md)
+- [인벤토리 판독·정확도 검증](docs/inventory.md)
+- [개발 및 테스트](CONTRIBUTING.md)
+- [배포 절차](docs/releasing.md), [변경 이력](CHANGELOG.md)
+
+자체 코드는 MIT입니다. SchaleDB·Blue Archive의 공식 프로젝트가 아니며 모델·게임 이미지·상표의 권리는 원 권리자에게 있습니다. [제3자 고지](THIRD_PARTY_NOTICES.md)를 확인하세요.

schale-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,48 @@
+# Third-party materials
+
+The MIT license in `LICENSE` applies to the original schale source code. It does
+not relicense third-party models, game artwork, trademarks, or downloaded data.
+
+## Blue Archive and SchaleDB
+
+The Python package contains no game artwork, UI excerpts, derived reference
+descriptors, learned model weights, user recordings, or account exports. Runtime
+skill icons, portraits, and game metadata are fetched from https://schaledb.com/
+and cached locally when the corresponding tool is used. Local vision resources
+must be supplied separately by the user; installation does not grant rights to
+use or redistribute their contents. This project is not an official Blue Archive,
+NEXON, or SchaleDB product.
+
+Source of game materials: Blue Archive, NEXON / NEXON Games.
+See https://bluearchive.nexon.com/ and NEXON's Game IP guide:
+https://member.nexon.com/policy/policywrapper.aspx?policytype=37 .
+No permission to redistribute game materials is represented by this project.
+
+## Optional equipment model
+
+The inventory reader supports a locally installed MobileNetV3-Small ONNX model
+and its class mapping. Neither weights nor training images are distributed in
+the source or wheel. The training code can initialize from TorchVision's
+ImageNet weights. TorchVision's source license does not establish the rights to
+every pretrained weight or its training data; review the terms of the assets you
+choose to use or distribute:
+https://github.com/pytorch/vision/blob/main/docs/source/models.rst .
+
+## Student numeric model
+
+The tested student numeric ONNX model is a separate local bundle, not embedded in
+the Python wheel or source distribution. It was exported from OpenOCR
+(https://github.com/Topdu/OpenOCR), revision
+`0d522801ec6dc1df852c6b6d4ed6a08f5127ed97`.
+The bundle retains `LICENSE-OpenOCR` (Apache-2.0) and `NOTICE.md`, plus source and
+checkpoint hashes in `metadata.json`. The ONNX conversion and confidence-threshold
+calibration were performed for this extraction tool. Use trusted model bundles;
+checking a hash against adjacent metadata detects corruption, not publisher identity.
+
+## Runtime dependencies
+
+OpenCV, ONNX Runtime, NumPy, Pillow, Requests, Pydantic, Typer and their dependencies
+are installed separately and retain their respective licenses. Student and inventory
+inference do not require PyTorch or EasyOCR. PyTorch is confined to the optional
+source training group. FFmpeg and FFprobe must be installed separately; their
+binaries are not redistributed in these artifacts.

schale-0.1.0/docs/architecture.md

@@ -0,0 +1,63 @@
+# 구조와 확장 계약
+
+Schale은 SchaleDB 호환 데이터를 매개로 여러 자동화 도구를 조합합니다. 영상에서 읽는 과정과 계정 상태를 이용하는 과정은 독립적입니다.
+
+```text
+SchaleDB 정의 ── ReferenceCatalog ── 기준 ID·정의
+
+사이트 export ── adapters.schaledb ─────────┐
+영상/이미지 ── students ── adapters.extraction ── AccountSnapshot
+향후 다른 입력 ── 해당 어댑터 ─────────────┘       │
+                                    collections.compare / merge
+                                                   │
+                                       adapters.schaledb ── 사이트 export
+
+스테이지·드롭 정의 ── StageRewards ── 보상 기대값
+```
+
+## 기준 데이터와 사용자 상태
+
+`ReferenceCatalog`는 학생·아이템·장비·스테이지·가구·그룹 정의를 제공하며 계정의 보유/육성 상태를 뜻하지 않습니다. `entries`는 원본 ID-keyed 형식이고 `get(id)`는 복사본입니다. 지역은 언어 데이터 선택이며 계정 서버 판정이 아닙니다. 그룹 정의는 언어 공통입니다.
+
+카탈로그 `sha256`은 키 정렬·UTF-8·공백 없는 JSON 직렬화의 내용 해시입니다. 들여쓰기에 의존하지 않습니다. 기존 `Extraction.catalog_sha256`은 원본 파일 해시 규칙을 유지하므로 두 종류의 해시를 직접 비교하지 않습니다.
+
+`AccountSnapshot`은 `kind="schale.account"`, `schema_version=1`인 공통 계정 JSON입니다. `StudentState`는 SchaleDB `student_id`, 고유 `key`, 이름, 신원 상태, 육성 필드, 출처, 어댑터 확장 속성을 가집니다. 미확인 학생은 ID=null로 유지할 수 있습니다. 중복 ID·key, 지원하지 않는 필드, 범위 밖 값, 정수 대신 bool 입력은 거부합니다.
+
+19개 필드는 성급, 레벨, 인연, EX/기본/강화/서브 스킬, 전용무기 성급·레벨, 애용품 티어, 장비 세 슬롯의 티어·레벨, 체력·공격·치유 능력 개방입니다. 이름과 현재 유효 범위는 `account.GROWTH_BOUNDS`가 기준입니다. 게임 상한 변경 시 모델·어댑터·테스트를 함께 검토합니다.
+
+각 `GrowthValue`는 값, 상태, 출처를 포함합니다. 영상 근거의 시각·ROI·점수·방법도 보존합니다. 파일을 복사/업로드하지 않으므로 근거 이미지와 원본 추출 폴더를 함께 보관하세요. 공통 계정 파일은 원래 감독 보고서의 대체물이 아닙니다.
+
+## 확인 상태와 병합
+
+| 상태 | 의미 | 기본 병합·내보내기 |
+|---|---|---|
+| `unknown` | 알 수 없음, null | 보류 |
+| `conflict` | 관측 충돌, null | 보류 |
+| `observed` | 단일 관측 | 명시적 opt-in만 |
+| `inferred` | 규칙으로 추론 | 명시적 opt-in만 |
+| `confirmed` | 여러 관측 일치 | 수용 |
+| `corrected` | 사람이 교정 | 수용 |
+| `imported` | 외부 파일에 명시 | 수용 |
+
+`imported`는 픽셀로 검증했다는 뜻이 아닙니다. 신뢰할 수 있는 사용자의 컬렉션을 입력으로 선택한다는 계약입니다. `confirmed`도 정답 확률이 아닙니다.
+
+`merge(base, incoming)`은 입력을 수정하지 않고 새 스냅샷과 보고서를 반환합니다. incoming의 수용 가능한 값이 우선하며 불확실한 값은 base를 지우지 않습니다. 안 보인 학생을 삭제하지 않습니다. 미확인 신원/필드는 보고서로 보류하므로 원본 incoming 파일을 보관하세요. 자동 시각 비교는 하지 않으며 최신/우선 자료 선택은 호출자의 책임입니다.
+
+동일 값의 근거를 합치고, 관측 수준의 같은 값이 기존 확인 상태를 낮추지 않도록 합니다. `extensions`의 설정은 base 우선으로 빠진 속성만 채웁니다. `compare`의 `missing_ids`는 새 스냅샷에 없는 ID이지 미보유/삭제 판정이 아닙니다. 값과 확인 상태 변화를 함께 비교합니다.
+
+## 외부 형식과 의존성
+
+SchaleDB 짧은 키, base64, `lock`, 최소 스킬 레벨 규칙은 `adapters.schaledb`에만 둡니다. 장비 자체 레벨은 사이트 형식에 없으므로 내부에 보존하고 변환 손실을 명시합니다. 미지의 사이트 속성은 `extensions.schaledb`에 보존합니다. 누락 값을 기본값으로 채우지 않으며 불완전한 신규 레코드는 내보내기에서 제외·보고합니다.
+
+코어는 Pydantic·Requests·Typer·FileLock을 사용합니다. 공통 계정·컬렉션 모듈은 OpenCV·ONNX·학습 모델에 의존하지 않습니다. 비전 입력 어댑터는 결과 모델만 참조하고 인식기를 import하지 않습니다. 영상·이미지 묶음은 입력 계약으로 정규화하고, 모든 SchaleDB 소비자는 공유 HTTP 캐시를 사용합니다. 상세 계약은 [캐시](cache.md), [입력](inputs.md)을 참고하세요. 인벤토리 도구는 선택 기능입니다.
+
+## 도구 추가 기준
+
+1. 입출력 계약을 먼저 정하고 SchaleDB ID를 유지합니다.
+2. 새 입력 형식은 어댑터에서 변환합니다. 모든 도구가 계정 모델을 쓸 필요는 없습니다. 보상 계산처럼 정의만 필요한 도구는 직접 조회합니다.
+3. 계산은 파일/CLI와 독립적인 함수로 제공하고 CLI는 검증·입출력을 연결합니다.
+4. 실제 필요한 공통 개념이 생길 때만 모델을 확장합니다. 학생 모델에 재료나 스테이지 필드를 억지로 넣지 않습니다.
+5. 불확실성·변환 손실·출처를 드러내고 실패를 성공값으로 대체하지 않습니다.
+6. 성공, 불완전 입력, 데이터 보존, 기존 API, 설치된 배포본 사용을 검증합니다.
+
+런타임 플러그인 시스템·작업 큐·범용 게임 봇 프레임워크는 현재 필요하지 않아 도입하지 않았습니다. 향후 도구는 이 계약 위에 독립 모듈로 추가합니다.

schale-0.1.0/docs/assets.md

@@ -0,0 +1,89 @@
+# 로컬 비전 자원
+
+Schale의 Git 소스·PyPI wheel·sdist에는 게임 이미지, UI 참조, 특징 기술자,
+학습 모델을 넣지 않습니다. 비전 기능은 사용자가 준비한 자원을 사용합니다.
+현재 프로젝트가 공개 배포하는 게임 참조 번들은 없습니다. `schale[scanner]`
+설치만으로 인벤토리를 인식하거나, 빈 캐시에서 학생 화면을 인식하지는 못합니다.
+데이터·계정·보상 도구는 이 자원이 필요하지 않습니다.
+
+## 설치와 점검
+
+```powershell
+uv tool install "schale[student-ocr,scanner]==0.1.0"
+schale assets install my-vision-resources.zip
+schale assets info
+schale students install-model schale-student-numeric-v1.zip
+schale students doctor
+```
+
+게임 참조·장비 모델은 첫 번째 ZIP, 공통 문자 모델은 두 번째 ZIP입니다.
+신뢰하는 출처와 사용 권한을 확인한 자료만 설치하세요. 체크섬은 손상 검사용이며
+제공자의 신원이나 재배포 허락을 보증하지 않습니다. 이 명령은 다운로드하지 않습니다.
+
+자원은 `SCHALE_CACHE_DIR/vision-resources`에 설치하며, 환경 변수가 없으면
+`~/.schale/cache/vision-resources`를 사용합니다. 내용 해시별 `bundles/<hash>`와
+현재 선택을 담은 `current.json`으로 관리합니다. 같은 번들의 재설치는 중복 저장하지
+않고, 변경된 번들은 별도로 저장한 뒤 현재 선택을 원자적으로 바꿉니다. 검증 실패 시
+이전 선택을 유지합니다. 이전 ZIP을 다시 설치하면 해당 버전으로 돌아갑니다.
+설치 작업은 프로세스 잠금으로 직렬화하며 기존 파일을 덮어쓰지 않습니다.
+
+`assets info`는 모든 파일의 SHA-256을 검사합니다. 학생/인벤토리 실행 시에도 필요한
+번들을 검증하고, 없거나 손상됐으면 설치 안내와 함께 실패합니다. 조용히 낮은 정확도의
+다른 알고리즘으로 전환하지 않습니다. HTTP 캐시의 `cache update`는 이 로컬 번들을
+수정하거나 자동 교체하지 않습니다.
+
+## 자신의 자원 번들 만들기
+
+이미 준비한 참조 데이터나 직접 보정·학습한 결과를 아래 구조에 배치합니다.
+`assets pack`은 포장과 무결성 검사를 수행하며 이미지에서 참조를 자동 생성하거나
+모델을 학습하는 명령은 아닙니다. 다른 레이아웃의 자료는 별도 보정과 검증이 필요합니다.
+
+```text
+my-resources/
+  students/
+    labels.json
+    layout_reference.npz
+    header.png
+    empty_gear.png
+    ghost_gloves.png
+    ghost_shoes.png
+    ghost_hat.png
+    potential_hp_25.png
+    potential_attack_25.png
+    <labels.json에서 지정한 마스크 PNG들>
+  inventory/
+    models/
+      equipment_classifier.onnx
+      equipment_classifier.onnx.data  (ONNX가 외부 가중치를 사용하는 경우)
+      class_mapping.json
+    icons/                            (선택: 로컬 참조 이미지)
+      equipment_icon_*.webp
+```
+
+```powershell
+schale assets pack my-resources --output my-vision-resources.zip
+schale assets install my-vision-resources.zip
+```
+
+최소 하나의 완전한 구성요소(`students` 또는 `inventory`)가 필요합니다. 설치는 번들
+전체를 선택하므로 둘 다 사용하려면 둘을 함께 포장하세요. 파일 목록과 SHA-256을 담은
+`manifest.json`은 명령이 생성합니다. 학생 프로필은 한국어 16:9 화면용이며 번들 프로필
+식별자는 `bluearchive-ko-16x9-v1`입니다.
+
+- `labels.json`: `family` (`level`, `tier`, `skill`, `bond`), `value` (정수 또는 `MAX`),
+  `image` (같은 디렉터리 기준 마스크 파일명)를 담은 배열입니다. 마스크는
+  `schale.students.labels.label_mask`의 출력과 같은 40×160 형태입니다.
+- `layout_reference.npz`: 1280×720 기준 좌표의 `left_points`, `right_points` (N×2)와
+  대응하는 OpenCV SIFT `left_descriptors`, `right_descriptors` (N×128)입니다.
+  기준 특징은 움직이지 않는 UI에서 수집해야 합니다. 원본 그림은 포함하지 않아도 됩니다.
+- UI PNG는 `schale.students.vision`의 해당 ROI와 같은 의미의 BGR 참조입니다.
+- 장비 모델 입력은 RGB 정규화 float32 N×3×116×146, 출력은 클래스별 logits입니다.
+  `class_mapping.json`은 `num_classes`, `class_to_name`, `name_to_class`, `categories`를
+  포함하며 학습한 모델의 순서와 일치해야 합니다. 학습·ONNX 내보내기는
+  `schale.scanner.training`에서 제공하며 기본 출력은 사용자 캐시의 `training/equipment`입니다.
+- 장비 아이콘이 없으면 기존 공유 HTTP 캐시에서 읽거나 정책에 따라 SchaleDB에서
+  받습니다. 오프라인 상태의 누락은 결과의 `unavailable_icons`에 기록합니다.
+
+번들은 개인 환경에서 보관하세요. 공개 배포 여부는 각 게임 자료·학습 데이터·모델의
+권리 조건에 따라 별도로 판단해야 합니다. ZIP으로 분리했다는 이유로 재배포가 허용되는
+것은 아닙니다. 문자 모델 번들 구성은 [학생 인식 문서](students.md)를 참고하세요.