moleg-api 0.2.4__tar.gz → 0.3.0__tar.gz

{moleg_api-0.2.4 → moleg_api-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moleg-api
-Version: 0.2.4
+Version: 0.3.0
 Summary: Task-level Python interface for loading Korean legal sources from law.go.kr
 Author: MOLEG-API maintainers
 License-Expression: MIT
@@ -41,7 +41,7 @@ The PyPI package is `moleg-api`; import it as `moleg_api`.
 pip install moleg-api
 ```
 
-Live calls use a law.go.kr OpenAPI credential (the "OC" — a free, non-secret account id). The package ships a shared default, so calls work out of the box with **no registration required**. To use your own OC (recommended for heavy use), register at law.go.kr and set `MOLEG_OC`, or pass `oc=` to `LawGoKrClient`. See [Installation](wiki/Installation.md).
+Live calls use a law.go.kr OpenAPI credential (the "OC" — a free, non-secret account id). The package ships a shared default, so calls work out of the box with **no registration required**. To use your own OC (recommended for heavy use), register at law.go.kr and set `MOLEG_OC`, or pass `oc=` to `LawGoKrClient`. See [Installation](docs/wiki/Installation.md).
 
 ## Quickstart
 
@@ -65,7 +65,7 @@ python -m moleg_api get-article --law 001248 제3조    # load the current artic
 python -m moleg_api get-article --law 001248 --as-of 2021-01-01 제3조  # the version in force then
 ```
 
-The CLI exposes 27 task subcommands plus `catalog`; `catalog` is the source of truth for the command list, routing rules, and result `kind` values.
+The CLI exposes every interface as a subcommand plus `catalog`; `catalog` is the source of truth for the command list, routing rules, and result `kind` values. Each envelope carries the `version` that produced it.
 
 Public dataclasses serialize recursively with `to_dict()` / `to_json_string()` (raw payloads omitted unless `include_raw=True`).
 
@@ -77,19 +77,23 @@ Public dataclasses serialize recursively with `to_dict()` / `to_json_string()` (
 - Delegated rules, legal hierarchy, and administrative rules (고시·훈령·예규)
 - Law and administrative-rule annex/form bodies (별표·서식)
 - MOLEG and ministry legal interpretations, Supreme Court cases, and Constitutional Court (헌재) decisions
+- Amendment rationale — the 「개정이유 및 주요내용」 text for a specific statute version
+- Committee decisions from twelve regulators (개인정보보호위·공정위·금융위·인권위·노동위 등) and 행정심판 재결례 including four special tribunals — the record of an agency applying the law it administers, kept distinct from precedent
 - Query expansion, comparable-mechanism discovery, and staged context bundles with executable follow-up lookups
 
-Out of scope: legal advice, National Assembly bill data (status, votes, minutes), and latest statistics/news.
+Context budgeting: `get-law --toc` returns a statute's article map without the text (276KB → 19KB on 개인정보 보호법), `--brief` returns a decision's 요지 without the full body, and `flags.large_payload` warns when a narrowing option was available.
+
+Out of scope: legal advice, National Assembly bill data (status, votes, minutes), legislative pre-announcement (입법예고 — a separate 국민참여입법센터 source), and latest statistics/news.
 
 ## Documentation
 
-Full documentation is in the [`wiki/`](wiki/Home.md) folder:
+Full documentation is in the [`docs/wiki/`](docs/wiki/Home.md) folder:
 
-- [Installation](wiki/Installation.md) · [Quickstart](wiki/Quickstart.md) · [Core Concepts](wiki/Core-Concepts.md)
-- [CLI Reference](wiki/CLI-Reference.md) · [API Reference](wiki/API-Reference.md)
-- [Historical Versions](wiki/Historical-Versions.md) · [Sources & Coverage](wiki/Sources-and-Coverage.md)
-- [Gotchas](wiki/Gotchas.md) · [Error Handling](wiki/Error-Handling.md)
-- [Maintainer Notes](wiki/Maintainer-Notes.md)
+- [Installation](docs/wiki/Installation.md) · [Quickstart](docs/wiki/Quickstart.md) · [Core Concepts](docs/wiki/Core-Concepts.md)
+- [CLI Reference](docs/wiki/CLI-Reference.md) · [API Reference](docs/wiki/API-Reference.md)
+- [Historical Versions](docs/wiki/Historical-Versions.md) · [Sources & Coverage](docs/wiki/Sources-and-Coverage.md)
+- [Gotchas](docs/wiki/Gotchas.md) · [Error Handling](docs/wiki/Error-Handling.md)
+- [Maintainer Notes](docs/wiki/Maintainer-Notes.md)
 
 ## Status
 

{moleg_api-0.2.4 → moleg_api-0.3.0}/README.md

@@ -12,7 +12,7 @@ The PyPI package is `moleg-api`; import it as `moleg_api`.
 pip install moleg-api
 ```
 
-Live calls use a law.go.kr OpenAPI credential (the "OC" — a free, non-secret account id). The package ships a shared default, so calls work out of the box with **no registration required**. To use your own OC (recommended for heavy use), register at law.go.kr and set `MOLEG_OC`, or pass `oc=` to `LawGoKrClient`. See [Installation](wiki/Installation.md).
+Live calls use a law.go.kr OpenAPI credential (the "OC" — a free, non-secret account id). The package ships a shared default, so calls work out of the box with **no registration required**. To use your own OC (recommended for heavy use), register at law.go.kr and set `MOLEG_OC`, or pass `oc=` to `LawGoKrClient`. See [Installation](docs/wiki/Installation.md).
 
 ## Quickstart
 
@@ -36,7 +36,7 @@ python -m moleg_api get-article --law 001248 제3조    # load the current artic
 python -m moleg_api get-article --law 001248 --as-of 2021-01-01 제3조  # the version in force then
 ```
 
-The CLI exposes 27 task subcommands plus `catalog`; `catalog` is the source of truth for the command list, routing rules, and result `kind` values.
+The CLI exposes every interface as a subcommand plus `catalog`; `catalog` is the source of truth for the command list, routing rules, and result `kind` values. Each envelope carries the `version` that produced it.
 
 Public dataclasses serialize recursively with `to_dict()` / `to_json_string()` (raw payloads omitted unless `include_raw=True`).
 
@@ -48,19 +48,23 @@ Public dataclasses serialize recursively with `to_dict()` / `to_json_string()` (
 - Delegated rules, legal hierarchy, and administrative rules (고시·훈령·예규)
 - Law and administrative-rule annex/form bodies (별표·서식)
 - MOLEG and ministry legal interpretations, Supreme Court cases, and Constitutional Court (헌재) decisions
+- Amendment rationale — the 「개정이유 및 주요내용」 text for a specific statute version
+- Committee decisions from twelve regulators (개인정보보호위·공정위·금융위·인권위·노동위 등) and 행정심판 재결례 including four special tribunals — the record of an agency applying the law it administers, kept distinct from precedent
 - Query expansion, comparable-mechanism discovery, and staged context bundles with executable follow-up lookups
 
-Out of scope: legal advice, National Assembly bill data (status, votes, minutes), and latest statistics/news.
+Context budgeting: `get-law --toc` returns a statute's article map without the text (276KB → 19KB on 개인정보 보호법), `--brief` returns a decision's 요지 without the full body, and `flags.large_payload` warns when a narrowing option was available.
+
+Out of scope: legal advice, National Assembly bill data (status, votes, minutes), legislative pre-announcement (입법예고 — a separate 국민참여입법센터 source), and latest statistics/news.
 
 ## Documentation
 
-Full documentation is in the [`wiki/`](wiki/Home.md) folder:
+Full documentation is in the [`docs/wiki/`](docs/wiki/Home.md) folder:
 
-- [Installation](wiki/Installation.md) · [Quickstart](wiki/Quickstart.md) · [Core Concepts](wiki/Core-Concepts.md)
-- [CLI Reference](wiki/CLI-Reference.md) · [API Reference](wiki/API-Reference.md)
-- [Historical Versions](wiki/Historical-Versions.md) · [Sources & Coverage](wiki/Sources-and-Coverage.md)
-- [Gotchas](wiki/Gotchas.md) · [Error Handling](wiki/Error-Handling.md)
-- [Maintainer Notes](wiki/Maintainer-Notes.md)
+- [Installation](docs/wiki/Installation.md) · [Quickstart](docs/wiki/Quickstart.md) · [Core Concepts](docs/wiki/Core-Concepts.md)
+- [CLI Reference](docs/wiki/CLI-Reference.md) · [API Reference](docs/wiki/API-Reference.md)
+- [Historical Versions](docs/wiki/Historical-Versions.md) · [Sources & Coverage](docs/wiki/Sources-and-Coverage.md)
+- [Gotchas](docs/wiki/Gotchas.md) · [Error Handling](docs/wiki/Error-Handling.md)
+- [Maintainer Notes](docs/wiki/Maintainer-Notes.md)
 
 ## Status
 

{moleg_api-0.2.4 → moleg_api-0.3.0}/moleg_api/__init__.py

@@ -1,5 +1,6 @@
 """Public MOLEG-API interface."""
 
+from ._version import __version__
 from .errors import (
     AmbiguousLawError,
     AsOfBeforeCoverageError,
@@ -13,6 +14,9 @@ from .errors import (
 )
 from .laws import MolegApi
 from .models import (
+    AdjudicationHit,
+    AdjudicationIdentity,
+    AdjudicationText,
     AdministrativeRuleArticleText,
     AdministrativeRuleContext,
     AdministrativeRuleHit,
@@ -63,6 +67,9 @@ from .models import (
     LawStructure,
     LawStructureNode,
     LawText,
+    LawToc,
+    LawTocEntry,
+    RevisionReason,
     SupplementaryProvision,
     StructuredTableData,
 )
@@ -120,7 +127,13 @@ __all__ = [
     "LawIdentity",
     "LawStructure",
     "LawStructureNode",
+    "AdjudicationHit",
+    "AdjudicationIdentity",
+    "AdjudicationText",
     "LawText",
+    "LawToc",
+    "LawTocEntry",
+    "RevisionReason",
     "MolegApi",
     "MolegApiError",
     "NoResultError",
@@ -132,4 +145,5 @@ __all__ = [
     "SupplementaryProvision",
     "StructuredTableData",
     "UnsupportedFormatError",
+    "__version__",
 ]

moleg_api-0.3.0/moleg_api/_cli/brief_mode.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from dataclasses import MISSING, fields, replace
+from typing import Any
+
+# A decision detail ships the same reasoning twice over: `text` and `full_text`
+# are different sections of the document, not duplicates, but between them they
+# are ~82% of the payload (29,321 of 35,866 characters on decision 193332). The
+# structured extract — 판시사항, 결정요지, referenced authority — is what a reader
+# needs to decide whether the decision is even on point. Loading 82,700 bytes to
+# find out costs more than the answer is worth.
+#
+# Brief mode drops the full-body fields and keeps the extract. It does *not* drop
+# `summary`: 요지 is the entire reason to ask for a brief, and cutting it would
+# shrink the payload further while removing the only thing brief mode is for.
+_BRIEF_DROPPED_FIELDS = ("text", "full_text", "reasoning")
+
+
+def to_brief(result: Any) -> Any:
+    """Blank the full-body fields on a loaded authority document.
+
+    Returns the same type rather than a narrower one, so the model, the kind, and
+    every consumer's field access stay valid — the difference is signalled on the
+    envelope, not encoded in a second shape of the same thing.
+    """
+    # Reset each field to its declared default rather than to a blanket "" or
+    # None. `text: str = ""` and `reasoning: str | None = None` mean different
+    # things by absence, and blanking a nullable field to "" turns "not loaded"
+    # into "loaded and empty" — a distinction a caller reads as a fact about the
+    # document rather than about the request.
+    defaults = {f.name: f.default for f in fields(result)}
+    blanked = {
+        name: defaults[name]
+        for name in _BRIEF_DROPPED_FIELDS
+        if name in defaults and defaults[name] is not MISSING
+    }
+    return replace(result, **blanked) if blanked else result
+
+
+def brief_dropped(result: Any) -> list[str]:
+    """Which full-body fields this document actually carried, for the flag.
+
+    Reported rather than assumed: a decision with no `full_text` on file must not
+    claim brief mode withheld one, or the caller will go looking for a section
+    that never existed.
+    """
+    return [
+        name
+        for name in _BRIEF_DROPPED_FIELDS
+        if getattr(result, name, None)
+    ]
+
+__all__ = [name for name in globals() if not name.startswith("__")]

{moleg_api-0.2.4 → moleg_api-0.3.0}/moleg_api/_cli/catalog.py

@@ -6,20 +6,23 @@ CATALOG = {
     "convention": [
         "kind 접미사가 후보≠본문을 구조로 표시: *_hit/*_candidate/*_planning = 검색 후보(인용 불가), *_text/*_context/*_identity = 로드된 본문.",
         "인용은 항상 로드된 본문에서만 — search/expand/find-comparable 결과는 '다음에 무엇을 로드할지의 메뉴'일 뿐.",
-        "출처 권위 보존: 법제처 법령 > 법제처 해석 > 부처 해석 ≠ 판례 ≠ 헌재. flags.source_type/라벨을 답에 반영.",
-        "0건·호출 실패 ≠ 부재. 종료코드로 구분: 0 ok(0건 포함) · 2 모호 · 3 소스접근실패 · 4 no-result · 5 usage/순서위반.",
+        "출처 권위 보존: 법제처 법령 > 법제처 해석 > 부처 해석 ≠ 판례 ≠ 헌재 ≠ 위원회 결정 ≠ 행정심판 재결. flags.source_type/source_authority를 답에 반영하고 평탄화 금지 — 위원회 결정·행정심판 재결은 행정기관의 판단이라 행정소송으로 뒤집힐 수 있고 판례가 아니다.",
+        "0건·호출 실패 ≠ 부재. 종료코드로 구분: 0 ok(0건 포함) · 2 모호 · 3 소스 접근·응답 문제 · 4 no-result · 5 usage/순서위반.",
+        "exit 3의 두 얼굴을 kind로 갈라라 — source_access_error=진짜 일시 장애(타임아웃·429·5xx)라 재시도가 맞고, parse_error=인식 불가 응답이라 재시도해도 그대로다(식별자 오류부터 의심). 불량 식별자로 본문이 없으면 exit 3이 아니라 no_result(exit 4)로 온다 — '일시 장애'로 읽지 마라.",
         "load 계열에 법령명을 주면 needs_search_first(exit 5) — 먼저 search-laws로 law_id를 얻어라.",
         "deferred는 data.deferred[i]를 load-followup --json -로 파이프(손타이핑 금지).",
+        "컨텍스트 예산: 큰 법 전체 로드(get-law) 전에 --toc로 조문 지도부터, 판결·헌재·해석은 --brief로 요지부터. flags.large_payload가 뜨면 범위를 좁힐 인자가 있다는 신호다(검색은 후보 반환이 설계라 예외).",
         "로더(get-law/get-article)는 기본이 현행 통합본, --as-of <날짜>(YYYY-MM-DD/YYYYMMDD만)면 그 시점 시행 버전을 로드한다. 반환 effective_date를 오늘과 대조해 현행/미시행을 판정하라 — flags.not_effective_as_of=공포됐으나 미시행(미래 시행일, 현행 인용 금지), version_mismatch={requested,loaded}=요청 시점과 반환 버전 시행일 불일치, version_request_unfulfilled=요청보다 이후 버전이 반환됨. 요청 시점이 통합본 커버리지보다 이르면 kind:version_request_unfulfilled+earliest_available(→trace-law-history).",
         "검색 스코프 뉘앙스: 헌재·판례는 기본이 제목(사건명) 검색이라 doctrine·본문 키워드는 --search-body(본문 전체)라야 매칭(0건이면 next가 재시도 제시). 별표는 --search-scope title(별표 제목)/source(소관 법령명, 토큰 근접)이라 0건이면 반대 스코프로. 부처 해석은 --source all_ministries(법제처+부처 혼합)로만 나오고, 부처 본문 로드는 --source ministry --ministry <기관> 필수(검색 hit의 follow_up.filters를 그대로 로더 인자로).",
         "개정 전후 델타=compare-law-versions는 소스가 주는 최근 두 버전만 비교하고 changes[].article은 본문에서 파싱한 실제 조문번호(매핑 불가 시 null). 임의 두 시점 델타는 get-article --as-of를 전후 날짜로 두 번 로드해 대조.",
     ],
     "routing_rules": [
         "본문 로드: 살아있는 조문=get-article / 이동·삭제 가능성 있는 조문=load-article-context(기본이 이동추적).",
-        "개정: 무엇이 바뀌었나(전후 문구 델타)=compare-law-versions / 어떤 개정들이 있었나(연혁)=trace-law-history.",
+        "개정 3분해: 왜 바뀌었나(제안 취지 원문)=get-revision-reason / 무엇이 바뀌었나(전후 문구 델타)=compare-law-versions / 어떤 개정들이 있었나(연혁)=trace-law-history. 연혁 이벤트의 identity.mst가 곧 get-revision-reason --mst 입력이다.",
         "이 법 아래 무엇이 있나: 계층 조망=get-law-structure(위임 증명 아님) / 조문 단위 위임 규정=find-delegated-rules.",
         "넓은 탐색: 넓은 질의의 용어·관련법 조사계획=expand-legal-query / 유사 제도(비슷한 기제)를 가진 법 후보(설계용)=find-comparable-mechanisms.",
         "묶음 로더 — authority=특정 조문의 해석/판례/헌재 권위 / bundle=진입점 모를 때 단일법·넓은 질문(--mode) / institutional=명시된 다법령 집합(--statute 반복) / delegated=단일법의 하위규칙·별표 집행기준 본문.",
+        "감독기관이 실제로 판단했나(견제): 규제기관의 처분·의결서=search-committee-decisions --committee <ppc|ftc|fsc|sfc|kcc|nhrck|acr|nlrc|eiac|iaciac|oclt|ecc> / 그 처분에 불복한 재결=search-administrative-appeals --tribunal <decc|acr|adap|tt|kmst>. 둘 다 0건이어도 부재의 증명이 아니다(비공개·미접수 가능).",
         "별표 금액·기준표: 위임된 시행령·시행규칙의 별표를 search-annex-forms --search-scope source <법령명> → get-annex-form-body --id(=--annex-id)로 로드. 표 파싱이 무너지면 structured_data.parsing_confidence=low — 금액은 text를 1차로 인용하라. bare id 로드는 소관법령ID·pdf_link 등 링크 메타를 복구하지 못하니 현행성은 모법 버전으로 확인.",
     ],
     "commands": {
@@ -27,21 +30,25 @@ CATALOG = {
             "search-laws", "resolve-promulgated-law", "search-administrative-rules", "search-annex-forms",
             "search-interpretations", "search-cases", "search-constitutional-decisions",
             "expand-legal-query", "find-comparable-mechanisms",
+            "search-committee-decisions", "search-administrative-appeals",
         ],
         "본문 로드": [
             "get-law", "get-article", "load-article-context", "get-administrative-rule",
             "load-administrative-rule-context", "get-annex-form-body", "get-interpretation",
             "get-case", "get-constitutional-decision",
+            "get-committee-decision", "get-administrative-appeal",
         ],
-        "연혁·체계·위임": ["trace-law-history", "compare-law-versions", "find-delegated-rules", "get-law-structure"],
+        "연혁·체계·위임": ["trace-law-history", "get-revision-reason", "compare-law-versions", "find-delegated-rules", "get-law-structure"],
         "권위·묶음": ["load-authority-context", "load-legal-context-bundle", "load-institutional-system", "load-delegated-criteria", "load-followup"],
     },
     "kinds": [
         "law_hit_list", "admin_rule_hit_list", "annex_form_hit_list", "interpretation_hit_list",
         "case_hit_list", "constitutional_hit_list", "comparable_planning_list", "query_expansion_planning",
+        "committee_decision_hit_list", "administrative_appeal_hit_list",
+        "committee_decision_text", "administrative_appeal_text",
         "law_text", "article_text", "article_context", "admin_rule_text", "admin_rule_context",
         "annex_form_text", "interpretation_text", "case_text", "constitutional_text", "law_identity",
-        "law_history", "law_diff", "delegation_graph", "law_structure_hierarchy_only",
+        "law_history", "revision_reason_text", "law_toc_map", "law_diff", "delegation_graph", "law_structure_hierarchy_only",
         "legal_context_bundle", "authority_context",
         "ambiguous", "source_access_error", "parse_error", "no_result",
         "needs_search_first", "usage_error", "unsupported", "error",

{moleg_api-0.2.4 → moleg_api-0.3.0}/moleg_api/_cli/constants.py

@@ -4,8 +4,11 @@ from .foundation import *
 
 EXIT_OK = 0            # includes a zero-hit search (ok:true, count:0)
 EXIT_AMBIGUOUS = 2     # multiple plausible identities — surface, don't pick
-EXIT_SOURCE = 3        # transient source access failure (rate limit / retry / source)
-EXIT_NO_RESULT = 4     # a load found no source text for a valid identifier
+EXIT_SOURCE = 3        # source could not be read OR could not be parsed — kind splits it:
+                       #   source_access_error = transient (rate limit / retry / 5xx), retry is right
+                       #   parse_error         = unrecognized response shape, retry won't help
+EXIT_NO_RESULT = 4     # a well-formed lookup found no source text — includes a bad identifier,
+                       # which law.go.kr signals with an empty detail body (see unwrap_service_payload)
 EXIT_USAGE = 5         # bad arguments, or a loader was handed a law name (search first)
 
 # Public MolegApi methods reachable through load-followup rehydration. Guards the
@@ -54,6 +57,8 @@ SEARCH_COMMANDS = frozenset(
         "search-interpretations",
         "search-cases",
         "search-constitutional-decisions",
+        "search-committee-decisions",
+        "search-administrative-appeals",
     }
 )
 

{moleg_api-0.2.4 → moleg_api-0.3.0}/moleg_api/_cli/dispatch.py

@@ -3,9 +3,22 @@ from __future__ import annotations
 from .foundation import *
 from .constants import CliError, EXIT_USAGE, FOLLOWUP_HANDOFFS, FOLLOWUP_INTERFACES
 from .data import _statute_args
+from .brief_mode import brief_dropped, to_brief
 from .signals_meta import parse_as_of
 
 def _call(api: MolegApi, args: argparse.Namespace) -> Any:
+    result = _dispatch(api, args)
+    if getattr(args, "brief", False):
+        # Record what was actually withheld *before* blanking it. Signals only
+        # sees the trimmed result, and "empty because brief" must stay
+        # distinguishable from "empty because the source had none" — otherwise a
+        # caller goes hunting for a section that never existed.
+        args.brief_dropped = brief_dropped(result)
+        return to_brief(result)
+    return result
+
+
+def _dispatch(api: MolegApi, args: argparse.Namespace) -> Any:
     c = args.command
     # Strictly validate --as-of once, for every command that carries it, so a
     # malformed date is a usage error rather than a silent wrong-version load.
@@ -31,11 +44,21 @@ def _call(api: MolegApi, args: argparse.Namespace) -> Any:
     if c == "search-constitutional-decisions":
         return api.search_constitutional_decisions(args.query, search_body=args.search_body,
                                                     decided_on=args.decided_on, case_number=args.case_number, display=args.display)
+    if c == "search-committee-decisions":
+        return api.search_committee_decisions(args.query, committee=args.committee, display=args.display)
+    if c == "get-committee-decision":
+        return api.get_committee_decision(args.identifier, committee=args.committee)
+    if c == "search-administrative-appeals":
+        return api.search_administrative_appeals(args.query, tribunal=args.tribunal, display=args.display)
+    if c == "get-administrative-appeal":
+        return api.get_administrative_appeal(args.identifier, tribunal=args.tribunal)
     if c == "expand-legal-query":
         return api.expand_legal_query(args.query, display=args.display, include_websearch_hint=not args.no_websearch_hint)
     if c == "find-comparable-mechanisms":
         return api.find_comparable_mechanisms(args.concept, display=args.display)
     if c == "get-law":
+        if args.toc:
+            return api.get_law_toc(args.law, as_of=args.as_of, basis=args.basis)
         return api.get_law(args.law, as_of=args.as_of, basis=args.basis,
                            articles=args.article or None, include_metadata=not args.no_metadata)
     if c == "get-article":
@@ -60,6 +83,8 @@ def _call(api: MolegApi, args: argparse.Namespace) -> Any:
     if c == "trace-law-history":
         date_range = (args.date_from, args.date_to) if (args.date_from and args.date_to) else None
         return api.trace_law_history(args.law, date_range=date_range, article=args.article)
+    if c == "get-revision-reason":
+        return api.get_revision_reason(args.law, mst=args.mst, as_of=args.as_of)
     if c == "compare-law-versions":
         return api.compare_law_versions(args.law, article=args.article)
     if c == "find-delegated-rules":

{moleg_api-0.2.4 → moleg_api-0.3.0}/moleg_api/_cli/foundation.py

@@ -4,7 +4,6 @@ import argparse
 import json
 import sys
 from datetime import date, datetime
-from importlib.metadata import PackageNotFoundError, version as _dist_version
 from typing import Any
 
 from ..errors import (
@@ -21,10 +20,4 @@ from ..laws import MolegApi
 from ..models import DeferredLookup
 
 
-def _pkg_version() -> str:
-    try:
-        return _dist_version("moleg-api")
-    except PackageNotFoundError:
-        return "unknown"
-
 __all__ = [name for name in globals() if not name.startswith("__")]

{moleg_api-0.2.4 → moleg_api-0.3.0}/moleg_api/_cli/main.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from .foundation import *
+from .._version import __version__
 from .catalog import CATALOG
 from .constants import (
     CliError,
@@ -14,10 +15,22 @@ from .constants import (
 from .data import _to_data
 from .dispatch import _call
 from .parser import build_parser
+from .payload_size import large_payload_signals
 from .signals import signals_for
 
 def _emit(payload: dict[str, Any]) -> None:
-    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    # Stamped here rather than at each call site so no envelope — success, error,
+    # or catalog — can ship without it. A consumer that cannot tell which version
+    # answered cannot tell whether a missing field means "not supported yet" or
+    # "the call failed", which is how a stale install reads as a data gap.
+    stamped: dict[str, Any] = {}
+    for key, value in payload.items():
+        stamped[key] = value
+        if key == "command":
+            stamped["version"] = __version__
+    if "version" not in stamped:
+        stamped["version"] = __version__
+    print(json.dumps(stamped, ensure_ascii=False, indent=2))
 
 
 def main(argv: list[str] | None = None, *, api: MolegApi | None = None) -> int:
@@ -66,7 +79,8 @@ def main(argv: list[str] | None = None, *, api: MolegApi | None = None) -> int:
         return EXIT_NO_RESULT
     except ParseFailureError as exc:
         _emit({"ok": False, "command": args.command, "kind": "parse_error", "error": str(exc),
-               "discipline": ["소스 응답을 정규화하지 못함(소스접근 실패·법령 부재 아님) — 다른 경로/커맨드로 확인하라."]})
+               "discipline": ["소스가 인식 불가한 형태의 응답을 줌 — 같은 호출을 재시도해도 대개 그대로다(일시 장애와 다름).",
+                              "식별자 오류 가능성을 먼저 배제하라(search-*로 신원 재확인). 그래도 같으면 다른 경로/커맨드로 확인하고, 부재로 단정하지 마라."]})
         return EXIT_SOURCE
     except NoResultError as exc:
         msg = str(exc)
@@ -84,7 +98,8 @@ def main(argv: list[str] | None = None, *, api: MolegApi | None = None) -> int:
             return EXIT_USAGE
         else:
             _emit({"ok": False, "command": args.command, "kind": "no_result", "error": msg,
-                   "discipline": ["이 식별자·조회로 소스 본문 없음 — 검색어·범위를 밝히고 대체 경로를 시도하기 전 부재로 단정 금지."]})
+                   "discipline": ["이 식별자·조회로 소스 본문 없음 — 일시 장애가 아니니 재시도는 무의미하다. 식별자가 틀렸을 수 있으니 search-* 계열로 신원을 재확인하라.",
+                                  "검색어·범위를 밝히고 대체 경로를 시도하기 전 부재로 단정 금지."]})
             return EXIT_NO_RESULT
     except UnsupportedFormatError as exc:
         _emit({"ok": False, "command": args.command, "kind": "unsupported", "error": str(exc),
@@ -105,6 +120,16 @@ def main(argv: list[str] | None = None, *, api: MolegApi | None = None) -> int:
     if "count" in sig:
         envelope["count"] = sig["count"]
     envelope["data"] = _to_data(result, include_raw=include_raw)
+    # Measured on the serialized data, after every narrowing option has had its
+    # effect — a guess from a row count would fire on 139 short articles and stay
+    # quiet on 20 long ones, and would need updating for every command added later.
+    size_flags, size_discipline = large_payload_signals(
+        args.command,
+        len(json.dumps(envelope["data"], ensure_ascii=False)),
+        {"articles": len(result.articles)} if isinstance(getattr(result, "articles", None), list) else None,
+    )
+    sig["flags"].update(size_flags)
+    sig["discipline"].extend(size_discipline)
     if sig["flags"]:
         envelope["flags"] = sig["flags"]
     if sig["discipline"]:

{moleg_api-0.2.4 → moleg_api-0.3.0}/moleg_api/_cli/parser.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from .foundation import *
+from .._version import __version__
 from .signals_meta import parse_as_of
 
 def _add_law(p: argparse.ArgumentParser, required: bool = True) -> None:
@@ -19,6 +20,11 @@ def _add_articles(p: argparse.ArgumentParser, required: bool = False) -> None:
     p.add_argument("--article", dest="article", action="append", default=[], required=required, help="조문(예: 제3조). 반복 지정 가능.")
 
 
+def _add_brief(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--brief", action="store_true",
+                   help="전문(text/full_text) 없이 요지·판시사항·참조 관계만. 인용은 전문 로드 후.")
+
+
 def _add_budget(p: argparse.ArgumentParser) -> None:
     p.add_argument("--budget", choices=["minimal", "standard", "broad"], default="standard")
 
@@ -32,12 +38,12 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "--version",
         action="version",
-        version=f"moleg-api {_pkg_version()}",
-        help="설치된 moleg-api 버전을 출력하고 종료.",
+        version=f"moleg-api {__version__}",
+        help="실행 중인 moleg-api 버전을 출력하고 종료(엔벨로프의 version과 같은 값).",
     )
     sub = parser.add_subparsers(dest="command", metavar="<command>")
 
-    sub.add_parser("catalog", help="27개 서브커맨드·규약·kind 목록을 한 번에.")
+    sub.add_parser("catalog", help="전체 서브커맨드·규약·kind 목록을 한 번에.")
 
     # ---- searches / planning ------------------------------------------- #
     p = sub.add_parser("search-laws", help="현행/공포 법령 신원 후보 검색.")
@@ -89,6 +95,28 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--case-number", dest="case_number", default=None)
     p.add_argument("--display", type=int, default=20)
 
+    p = sub.add_parser("search-committee-decisions", help="위원회 결정문 검색(개보위·공정위·금융위·인권위 등 12종).")
+    p.add_argument("query", nargs="?", default=None, help="안건명·사건명 키워드(생략 시 최신 목록).")
+    p.add_argument("--committee", required=True,
+                   help="기관 코드: ppc(개인정보보호위) ftc(공정위) fsc(금융위) sfc(증선위) kcc(방통위) nhrck(인권위) acr(권익위) nlrc(노동위) eiac(고용보험심사위) iaciac(산재재심사위) oclt(중앙토지수용위) ecc(중앙환경분쟁조정위).")
+    p.add_argument("--display", type=int, default=20)
+
+    p = sub.add_parser("get-committee-decision", help="위원회 결정문 본문 로드(--brief면 요지만).")
+    p.add_argument("--id", dest="identifier", required=True, help="decision_id(검색이 준 값).")
+    p.add_argument("--committee", required=True, help="검색에 쓴 기관 코드와 동일해야 한다.")
+    _add_brief(p)
+
+    p = sub.add_parser("search-administrative-appeals", help="행정심판 재결례 검색(일반 + 특별심판 4종).")
+    p.add_argument("query", nargs="?", default=None, help="사건명 키워드(생략 시 최신 목록).")
+    p.add_argument("--tribunal", default="decc",
+                   help="decc(일반 행정심판위) acr(권익위 특별) adap(소청심사위) tt(조세심판원) kmst(해양안전심판원).")
+    p.add_argument("--display", type=int, default=20)
+
+    p = sub.add_parser("get-administrative-appeal", help="행정심판 재결 본문 로드(--brief면 요지만).")
+    p.add_argument("--id", dest="identifier", required=True)
+    p.add_argument("--tribunal", default="decc", help="검색에 쓴 심판기관 코드와 동일해야 한다.")
+    _add_brief(p)
+
     p = sub.add_parser("expand-legal-query", help="질의 확장·관련법/용어/조문 조사 계획.")
     p.add_argument("query"); p.add_argument("--display", type=int, default=5)
     p.add_argument("--no-websearch-hint", dest="no_websearch_hint", action="store_true")
@@ -97,9 +125,11 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("concept"); p.add_argument("--display", type=int, default=5)
 
     # ---- loaders -------------------------------------------------------- #
-    p = sub.add_parser("get-law", help="법령 본문 로드.")
+    p = sub.add_parser("get-law", help="법령 본문 로드(--toc면 본문 없이 조문 목차만).")
     _add_law(p); _add_as_of(p); _add_basis(p); _add_articles(p)
     p.add_argument("--no-metadata", dest="no_metadata", action="store_true")
+    p.add_argument("--toc", action="store_true",
+                   help="본문 대신 조문 목차(장·절 표제 + 조번호·조제목 + 삭제/이동)만. 큰 법의 지도를 수 KB로.")
 
     p = sub.add_parser("get-article", help="조문 하나 로드.")
     _add_law(p); p.add_argument("article"); _add_as_of(p); _add_basis(p)
@@ -124,19 +154,22 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--no-metadata", dest="no_metadata", action="store_true")
     p.add_argument("--no-structuring", dest="no_structuring", action="store_true")
 
-    p = sub.add_parser("get-interpretation", help="법령해석례 본문 로드.")
+    p = sub.add_parser("get-interpretation", help="법령해석례 본문 로드(--brief면 질의·회답만).")
     p.add_argument("--id", dest="identifier", required=True)
     p.add_argument("--source", choices=["moleg", "ministry", "all", "all_ministries"], default=None)
     p.add_argument("--ministry", default=None)
     p.add_argument("--no-metadata", dest="no_metadata", action="store_true")
+    _add_brief(p)
 
-    p = sub.add_parser("get-case", help="판례 본문 로드.")
+    p = sub.add_parser("get-case", help="판례 본문 로드(--brief면 요지만).")
     p.add_argument("--id", dest="identifier", required=True)
     p.add_argument("--no-metadata", dest="no_metadata", action="store_true")
+    _add_brief(p)
 
-    p = sub.add_parser("get-constitutional-decision", help="헌재 결정 본문 로드.")
+    p = sub.add_parser("get-constitutional-decision", help="헌재 결정 본문 로드(--brief면 요지만).")
     p.add_argument("--id", dest="identifier", required=True)
     p.add_argument("--no-metadata", dest="no_metadata", action="store_true")
+    _add_brief(p)
 
     # ---- history / structure / delegation ------------------------------ #
     p = sub.add_parser("trace-law-history", help="개정 연혁 이벤트.")
@@ -144,6 +177,11 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--date-from", dest="date_from", default=None)
     p.add_argument("--date-to", dest="date_to", default=None)
 
+    p = sub.add_parser("get-revision-reason", help="특정 버전의 「개정이유 및 주요내용」·공포문 원문.")
+    _add_law(p)
+    p.add_argument("--mst", default=None, help="버전 MST(trace-law-history 이벤트의 identity.mst). 미지정이면 최신 버전.")
+    p.add_argument("--as-of", dest="as_of", default=None, help="그 시점 시행 버전의 개정이유(YYYY-MM-DD/YYYYMMDD).")
+
     p = sub.add_parser("compare-law-versions", help="개정 전후 조문 문구 비교(소스 제공 전후 쌍).")
     _add_law(p); p.add_argument("--article", default=None)
 

moleg_api-0.3.0/moleg_api/_cli/payload_size.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from .foundation import *
+
+# Measured on 2026-07-19 against live law.go.kr (bytes of the emitted envelope):
+#
+#   load-delegated-criteria --budget standard   513,570
+#   load-institutional-system --budget standard 396,609
+#   get-law (139 articles, no --article)        276,748
+#   get-case (one decision)                      82,700
+#   load-legal-context-bundle --budget broad      37,822
+#   load-authority-context                         6,889
+#   get-article                                    2,280
+#
+# The threshold is in *characters*, not bytes, because characters track token
+# cost and Korean text is three bytes each — measuring bytes would make the same
+# amount of reading look three times worse in Korean than in English. 20,000
+# characters is roughly 10–13k tokens: enough that a caller who could have
+# narrowed the request should be told they didn't.
+LARGE_PAYLOAD_CHARS = 20_000
+
+# Searches are exempt. They return candidate identities by design — that breadth
+# is what resolves ambiguity, and 20 hits costs ~18,000 characters, close enough
+# to the line that including them would make the signal fire on the one command
+# where the size is the intended behaviour.
+_EXEMPT_PREFIXES = ("search-", "resolve-", "expand-", "find-comparable")
+
+_ADVICE = {
+    "get-law": "전체 로드 대신 --toc로 조문 지도를 먼저 받고, 필요한 조문만 --article로 표적 로드하라.",
+    "get-case": "--brief로 요지(판시사항·결정요지)만 먼저 받고, 전문은 인용이 필요할 때만 로드하라.",
+    "get-constitutional-decision": "--brief로 요지만 먼저 받고, 전문은 인용이 필요할 때만 로드하라.",
+    "get-interpretation": "--brief로 질의·회답만 먼저 받고, 전문은 인용이 필요할 때만 로드하라.",
+    "load-delegated-criteria": "--budget minimal로 좁히거나, 기준이 걸린 조문만 --article로 지정하라.",
+    "load-institutional-system": "--budget minimal로 좁히거나, 실제로 볼 법령만 --statute으로 지정하라.",
+    "load-legal-context-bundle": "--budget minimal로 좁히거나, 진입 조문을 --article로 지정하라.",
+}
+
+_DEFAULT_ADVICE = "이 응답은 컨텍스트를 크게 차지한다 — 범위를 좁힐 인자(--article·--budget·--brief 등)가 있는지 확인하라."
+
+
+def large_payload_signals(command: str, data_chars: int, extra: dict[str, Any] | None = None) -> tuple[dict[str, Any], list[str]]:
+    """Flag a response big enough that the caller should have narrowed it.
+
+    Conditional like every other signal here: a small statute loads silently, so
+    the flag firing means something. Measured on the serialized data rather than
+    guessed from a row count, because the same number of articles can differ by
+    an order of magnitude in length — and because a size check written against
+    the actual output keeps working for commands added later.
+    """
+    if data_chars < LARGE_PAYLOAD_CHARS or any(command.startswith(p) for p in _EXEMPT_PREFIXES):
+        return {}, []
+    flags: dict[str, Any] = {"large_payload": {"chars": data_chars}}
+    if extra:
+        flags["large_payload"].update(extra)
+    return flags, [_ADVICE.get(command, _DEFAULT_ADVICE)]
+
+__all__ = [name for name in globals() if not name.startswith("__")]