uspto-oa-cli 0.1.0__py3-none-any.whl

oa_cli/__init__.py

@@ -0,0 +1,3 @@
+"""odp-oa-cli: USPTO 특허 심사과정 분석 CLI."""
+
+__version__ = "0.1.0"

oa_cli/__main__.py

@@ -0,0 +1,4 @@
+from oa_cli.cli import main
+
+if __name__ == "__main__":
+    main()

oa_cli/cli.py

@@ -0,0 +1,180 @@
+"""USPTO 특허 심사과정 분석 CLI."""
+
+import logging
+import sys
+from pathlib import Path
+from typing import Optional
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from oa_cli import __version__
+from oa_cli import config as cfg
+
+console = Console()
+
+
+@click.group(invoke_without_command=True)
+@click.version_option(__version__, prog_name="uspto-oa")
+@click.option("--verbose", "-v", is_flag=True, default=False, help="상세 로그 출력.")
+@click.pass_context
+def main(ctx: click.Context, verbose: bool) -> None:
+    """USPTO 특허 심사과정 분석 CLI.
+
+    \b
+    빠른 시작:
+      uspto-oa configure                    # API 키 저장
+      uspto-oa download 16330077            # 문서 다운로드
+      uspto-oa extract 16330077             # XML 파싱 → MD 생성
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["verbose"] = verbose
+    level = logging.DEBUG if verbose else logging.WARNING
+    logging.basicConfig(stream=sys.stderr, level=level, format="%(levelname)s  %(message)s")
+    if ctx.invoked_subcommand is None:
+        click.echo(f"uspto-oa v{__version__}")
+        click.echo(ctx.get_help())
+
+
+# ── configure ────────────────────────────────────────────────────────────────
+
+@main.command()
+@click.option("--show", is_flag=True, default=False, help="현재 설정만 표시하고 종료.")
+def configure(show: bool) -> None:
+    """API 키와 기본 설정을 저장합니다.
+
+    \b
+    설정 파일: ~/.oa-cli.toml
+    Enter 입력 시 기존 값 유지.
+    """
+    existing = cfg.load()
+    auth_cfg = existing.get("auth", {})
+
+    click.echo("OA CLI — 설정")
+    click.echo("─" * 40)
+    click.echo(f"설정 파일: {cfg.CONFIG_PATH}")
+    click.echo()
+
+    current_key = auth_cfg.get("api_key", "")
+
+    if show:
+        click.echo(f"  auth.api_key = {cfg.mask_key(current_key)}")
+        return
+
+    new_key = click.prompt(
+        f"USPTO API 키 [{cfg.mask_key(current_key)}]",
+        default="",
+        show_default=False,
+    ).strip()
+
+    final_key = new_key if new_key else current_key
+    if not final_key:
+        click.echo("\n경고: API 키가 없습니다. 나중에 다시 실행하세요.", err=True)
+        return
+
+    cfg.save({"auth": {"api_key": final_key}})
+    click.echo(f"\n설정 저장: {cfg.CONFIG_PATH}")
+    click.echo(f"  auth.api_key = {cfg.mask_key(final_key)}")
+
+
+# ── download ─────────────────────────────────────────────────────────────────
+
+@main.command()
+@click.argument("application")
+@click.option("--doc-codes", default=None, metavar="CODES",
+              help="쉼표 구분 문서 코드 (예: CTNF,CTFR,NOA). 생략 시 전체 수집 대상.")
+@click.option("--output-dir", default=None, metavar="DIR", help="저장 경로 (기본: file/{app_num}/).")
+@click.option("--force", is_flag=True, default=False, help="기존 파일도 재다운로드.")
+@click.option("--api-key", default=None, help="API 키 (설정 파일·환경변수보다 우선).")
+@click.pass_context
+def download(
+    ctx: click.Context,
+    application: str,
+    doc_codes: Optional[str],
+    output_dir: Optional[str],
+    force: bool,
+    api_key: Optional[str],
+) -> None:
+    """심사과정 문서를 다운로드합니다 (XML 우선, PDF 폴백).
+
+    \b
+    예시:
+      oa download 16330077
+      oa download US12228644B2
+      oa download 16330077 --doc-codes CTNF,CTFR,NOA
+      oa download 16330077 --force
+    """
+    from oa_cli.prosecution.collect import download_docs, normalize_app_number, resolve_patent_number
+
+    key = cfg.require_api_key(api_key)
+    raw = application
+
+    if raw.upper().startswith("US") and any(c.isalpha() for c in raw[2:]):
+        console.print(f"[dim]특허번호 '{raw}' → 출원번호 조회 중...[/dim]")
+        app_num = resolve_patent_number(raw, key)
+        console.print(f"[dim]출원번호: {app_num}[/dim]")
+    else:
+        app_num = normalize_app_number(raw)
+
+    out_dir = output_dir or str(Path.cwd() / "file" / app_num)
+    codes = doc_codes.split(",") if doc_codes else None
+
+    console.print(f"[bold]출원번호[/] {app_num}  →  [bold]{out_dir}[/]")
+    console.print()
+
+    results = download_docs(
+        app_number=app_num,
+        api_key=key,
+        doc_codes=codes,
+        output_dir=out_dir,
+        force=force,
+    )
+
+    if not results:
+        console.print("[yellow]다운로드된 문서가 없습니다.[/yellow]")
+        return
+
+    table = Table(title=f"다운로드 결과 — {app_num}", show_lines=False)
+    table.add_column("날짜", style="cyan", no_wrap=True)
+    table.add_column("코드", style="magenta")
+    table.add_column("형식", justify="center")
+    table.add_column("파일명")
+    table.add_column("상태", justify="center")
+
+    downloaded = skipped = 0
+    for r in results:
+        status = "[dim]스킵[/dim]" if r["skipped"] else "[green]완료[/green]"
+        skipped += r["skipped"]
+        downloaded += not r["skipped"]
+        fmt = r.get("fmt", "pdf").upper()
+        fmt_display = f"[green]{fmt}[/green]" if fmt == "XML" else fmt
+        table.add_row(r["date"], r["code"], fmt_display, Path(r["path"]).name, status)
+
+    console.print(table)
+    console.print(f"\n[bold green]{downloaded}개 다운로드[/] / [dim]{skipped}개 스킵[/]")
+
+
+# ── extract ──────────────────────────────────────────────────────────────────
+
+@main.command()
+@click.argument("application")
+@click.option("--output-dir", default=None, metavar="DIR", help="파일 디렉토리 (기본: file/{app_num}/).")
+def extract(application: str, output_dir: Optional[str]) -> None:
+    """다운로드된 XML 파일을 파싱해 prosecution.md 를 생성합니다.
+
+    \b
+    예시:
+      oa extract 16330077
+      # 결과: file/16330077/16330077_prosecution.md
+    """
+    from oa_cli.prosecution.extract import extract as do_extract
+    from oa_cli.prosecution.collect import normalize_app_number
+
+    app_num = normalize_app_number(application)
+    file_dir = output_dir or str(Path.cwd() / "file" / app_num)
+    out_path = str(Path(file_dir) / f"{app_num}_prosecution.md")
+
+    console.print(f"[bold]출원번호[/] {app_num}  →  [bold]{out_path}[/]")
+    do_extract(app_num, file_dir=file_dir, output_path=out_path)
+    console.print(f"[bold green]완료[/] {out_path}")

oa_cli/config.py

@@ -0,0 +1,103 @@
+"""
+설정 파일 관리 및 API 키 우선순위 처리.
+
+우선순위 (높은 순):
+  1. CLI --api-key 옵션 (일회성 override)
+  2. USPTO_API_KEY 환경변수 (CI/CD, shell profile)
+  3. ~/.oa-cli.toml [auth] api_key  (oa configure 로 저장)
+
+개발 환경에서는 python-dotenv가 설치된 경우 .env를 자동 로드해
+환경변수(2번)로 처리된다. 배포 환경에서는 dotenv 없이도 정상 동작.
+"""
+
+import os
+import sys
+import tomllib
+from pathlib import Path
+from typing import Optional
+
+CONFIG_PATH = Path.home() / ".oa-cli.toml"
+
+
+def load() -> dict:
+    """~/.oa-cli.toml 을 읽어 dict 반환. 파일 없으면 빈 dict."""
+    if not CONFIG_PATH.exists():
+        return {}
+    with open(CONFIG_PATH, "rb") as f:
+        return tomllib.load(f)
+
+
+def save(config: dict) -> None:
+    """config dict 를 ~/.oa-cli.toml 에 저장."""
+    CONFIG_PATH.write_text(_dump_toml(config), encoding="utf-8")
+
+
+def resolve_api_key(cli_key: Optional[str] = None) -> str:
+    """API 키를 우선순위에 따라 결정해 반환. 없으면 빈 문자열."""
+    if cli_key:
+        return cli_key
+
+    _try_load_dotenv()
+    env_key = os.getenv("USPTO_API_KEY", "")
+    if env_key:
+        return env_key
+
+    cfg = load()
+    return cfg.get("auth", {}).get("api_key", "")
+
+
+def require_api_key(cli_key: Optional[str] = None) -> str:
+    """API 키를 반환. 없으면 오류 메시지 출력 후 종료."""
+    key = resolve_api_key(cli_key)
+    if not key:
+        import click
+        click.echo(
+            "오류: USPTO API 키가 설정되지 않았습니다.\n"
+            "\n"
+            "다음 중 하나로 설정하세요:\n"
+            "  uspto-oa configure             # 설정 파일에 저장 (권장)\n"
+            "  export USPTO_API_KEY=..        # 환경변수\n"
+            "  uspto-oa download --api-key KEY <app_number>  # 일회성 옵션",
+            err=True,
+        )
+        sys.exit(1)
+    return key
+
+
+def mask_key(key: str) -> str:
+    """API 키를 마스킹하여 반환 (끝 4자리만 표시)."""
+    if not key:
+        return "(없음)"
+    if len(key) <= 4:
+        return "****"
+    return "****" + key[-4:]
+
+
+def _try_load_dotenv() -> None:
+    """python-dotenv 가 설치된 경우(개발 환경)에만 .env 를 로드."""
+    try:
+        from dotenv import load_dotenv
+        load_dotenv()
+    except ImportError:
+        pass
+
+
+def _dump_toml(config: dict) -> str:
+    """config dict 를 TOML 문자열로 직렬화 (tomllib 은 read-only 라 직접 구현)."""
+    lines: list[str] = []
+    for section, values in config.items():
+        if not isinstance(values, dict):
+            continue
+        lines.append(f"[{section}]")
+        for key, val in values.items():
+            if val is None or val == "":
+                continue
+            if isinstance(val, bool):
+                lines.append(f"{key} = {'true' if val else 'false'}")
+            elif isinstance(val, (int, float)):
+                lines.append(f"{key} = {val}")
+            else:
+                escaped = str(val).replace("\\", "\\\\").replace('"', '\\"')
+                lines.append(f'{key} = "{escaped}"')
+        lines.append("")
+    return "\n".join(lines)

oa_cli/prosecution/collect.py

@@ -0,0 +1,198 @@
+"""출원 문서 목록 필터링 및 일괄 다운로드 (XML 우선, PDF 폴백)."""
+
+import io
+import logging
+import tarfile
+from pathlib import Path
+from typing import Optional
+
+from oa_cli.uspto.client import make_api_request
+from oa_cli.uspto.download import download_file, download_bytes
+
+logger = logging.getLogger(__name__)
+
+BASE_URL = "https://api.uspto.gov/api/v1/patent"
+DOWNLOAD_BASE = "https://api.uspto.gov"
+
+# 심사 과정 분석에 필요한 문서 코드 (정확 일치)
+PROSECUTION_CODES_EXACT = {
+    "CTNF",   # Non-Final Rejection
+    "CTFR",   # Final Rejection
+    "REM",    # Remarks
+    "NACT",   # Notice of Allowance (구형식)
+    "NOA",    # Notice of Allowance (신형식)
+    "ABN",    # Abandonment
+    "SRNT",   # Search Report (National)
+    "SRFW",   # Search Report (Foreign)
+    "N271",   # 271 Notice
+    "EXIN",   # Examiner Interview
+    "RCE",    # Request for Continued Examination (구형식)
+    "RCEX",   # Request for Continued Examination (신형식)
+    "CTAV",   # Advisory Action
+    "892",    # Prior Art reference (Examiner)
+    "1449",   # Information Disclosure Statement
+    "IDS",    # Information Disclosure Statement
+}
+
+# 이 접두사로 시작하는 코드는 모두 포함 (Amendment 변형들)
+# 실제 응답 예: A, A..., A.NE, A.NE.AFCP, A.NE.AFCP.D, A.PE, AMSB, ANE.I
+PROSECUTION_CODE_PREFIXES = ("A",)
+
+
+def normalize_app_number(raw: str) -> str:
+    """출원번호 정규화 — 하이픈·슬래시·공백 제거."""
+    return raw.replace("/", "").replace("-", "").replace(" ", "")
+
+
+def resolve_patent_number(patent_number: str, api_key: str) -> str:
+    """특허번호(예: US12228644B2) → 출원번호 변환."""
+    digits = "".join(filter(str.isdigit, patent_number))
+    data = make_api_request(f"{BASE_URL}/applications", api_key, params={"patentNumber": digits})
+    bag = data.get("patentApplicationNumberBag") or data.get("results") or []
+    if bag:
+        first = bag[0]
+        raw = first.get("patentApplicationNumber") or first.get("applicationNumber", "") \
+              if isinstance(first, dict) else str(first)
+        return normalize_app_number(raw)
+    raise ValueError(f"특허번호 '{patent_number}'를 출원번호로 변환하지 못했습니다.")
+
+
+def fetch_document_list(app_number: str, api_key: str) -> list[dict]:
+    """전체 문서 목록 조회 (서버사이드 필터 미사용 — 500 오류 유발)."""
+    url = f"{BASE_URL}/applications/{app_number}/documents"
+    data = make_api_request(url, api_key)
+    return (
+        data.get("documentBag")
+        or data.get("patentDocumentFiles")
+        or data.get("documents")
+        or []
+    )
+
+
+MIME_PRIORITY = ["XML", "PDF"]  # MS_WORD 제외
+
+
+def _is_prosecution_doc(code: str, allowed: set[str] | None) -> bool:
+    if allowed is not None:
+        return code in allowed
+    if code in PROSECUTION_CODES_EXACT:
+        return True
+    return any(code.startswith(p) for p in PROSECUTION_CODE_PREFIXES)
+
+
+def _best_option(doc: dict, app_number: str) -> tuple[str, str] | None:
+    """우선순위(XML > PDF)에 따라 (url, ext) 반환."""
+    options: dict[str, str] = {}
+    for opt in doc.get("downloadOptionBag") or []:
+        mime = (opt.get("mimeTypeIdentifier") or "").upper()
+        url = opt.get("downloadUrl") or opt.get("url") or ""
+        if mime in MIME_PRIORITY and url:
+            options[mime] = url if url.startswith("http") else DOWNLOAD_BASE + url
+
+    for mime in MIME_PRIORITY:
+        if mime in options:
+            ext = mime.lower()
+            return options[mime], ext
+
+    doc_id = doc.get("documentIdentifier")
+    if doc_id:
+        return f"{DOWNLOAD_BASE}/api/v1/download/applications/{app_number}/{doc_id}.pdf", "pdf"
+
+    return None
+
+
+def _pdf_fallback_url(doc: dict, app_number: str) -> Optional[str]:
+    """PDF 다운로드 URL만 추출 (XML 실패 시 폴백용)."""
+    for opt in doc.get("downloadOptionBag") or []:
+        if (opt.get("mimeTypeIdentifier") or "").upper() == "PDF":
+            url = opt.get("downloadUrl") or opt.get("url") or ""
+            if url:
+                return url if url.startswith("http") else DOWNLOAD_BASE + url
+    doc_id = doc.get("documentIdentifier")
+    if doc_id:
+        return f"{DOWNLOAD_BASE}/api/v1/download/applications/{app_number}/{doc_id}.pdf"
+    return None
+
+
+def _save_xml_from_tar(raw: bytes, save_path: str):
+    """tar 아카이브에서 첫 번째 .xml 파일을 꺼내 save_path에 저장."""
+    with tarfile.open(fileobj=io.BytesIO(raw)) as tf:
+        for member in tf.getmembers():
+            if member.name.endswith(".xml"):
+                f = tf.extractfile(member)
+                if f:
+                    Path(save_path).write_bytes(f.read())
+                    return
+    raise ValueError("tar 아카이브에 .xml 파일이 없습니다.")
+
+
+def download_docs(
+    app_number: str,
+    api_key: str,
+    doc_codes: Optional[list[str]] = None,
+    output_dir: Optional[str] = None,
+    force: bool = False,
+) -> list[dict]:
+    """
+    심사 관련 문서를 XML 우선(없으면 PDF)으로 다운로드하고 메타데이터 목록을 반환.
+
+    Returns:
+        [{"code": str, "date": str, "doc_id": str, "fmt": str, "path": str, "skipped": bool}, ...]
+    """
+    allowed = set(doc_codes) if doc_codes else None
+    if output_dir is None:
+        output_dir = str(Path.cwd() / "file" / app_number)
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+
+    all_docs = fetch_document_list(app_number, api_key)
+    if not all_docs:
+        logger.warning(f"{app_number}: 문서 없음")
+        return []
+
+    docs = [d for d in all_docs
+            if _is_prosecution_doc(d.get("documentCode") or d.get("code") or "", allowed)]
+    logger.info(f"전체 {len(all_docs)}개 중 심사 관련 {len(docs)}개")
+
+    results = []
+    for doc in docs:
+        code = doc.get("documentCode") or doc.get("code") or "UNKNOWN"
+        date = (doc.get("officialDate") or doc.get("mailDate") or "").split("T")[0]
+        doc_id = doc.get("documentIdentifier") or doc.get("documentId") or ""
+
+        option = _best_option(doc, app_number)
+        if not option:
+            logger.warning(f"  {code} ({date}): 다운로드 URL 없음")
+            continue
+        url, ext = option
+
+        filename = f"{date}_{code}_{doc_id}.{ext}".replace(" ", "_")
+        save_path = str(Path(output_dir) / filename)
+        entry = {"code": code, "date": date, "doc_id": doc_id, "fmt": ext, "path": save_path, "skipped": False}
+
+        if not force and Path(save_path).exists():
+            entry["skipped"] = True
+            results.append(entry)
+            continue
+
+        try:
+            if ext == "xml":
+                try:
+                    raw = download_bytes(url, api_key)
+                    _save_xml_from_tar(raw, save_path)
+                except (ValueError, Exception) as xml_err:
+                    logger.warning(f"  {code} ({date}) XML 실패({xml_err}), PDF로 폴백")
+                    pdf_url = _pdf_fallback_url(doc, app_number)
+                    if not pdf_url:
+                        logger.error(f"  {code} ({date}) PDF 폴백 URL도 없음")
+                        continue
+                    save_path = save_path.removesuffix(".xml") + ".pdf"
+                    entry["fmt"] = "pdf"
+                    entry["path"] = save_path
+                    download_file(pdf_url, api_key, save_path)
+            else:
+                download_file(url, api_key, save_path)
+            results.append(entry)
+        except Exception as e:
+            logger.error(f"  {code} ({date}) 다운로드 실패: {e}")
+
+    return results

oa_cli/prosecution/extract.py

@@ -0,0 +1,224 @@
+"""다운로드된 XML 파일 파싱 → 심사과정 분석 MD 생성."""
+
+import re
+import logging
+from pathlib import Path
+from typing import Optional
+import xml.etree.ElementTree as ET
+
+logger = logging.getLogger(__name__)
+
+USCOM = "{urn:us:gov:doc:uspto:common}"
+
+CODE_LABELS = {
+    "CTNF": "Non-Final Rejection",
+    "CTFR": "Final Rejection",
+    "NOA":  "Notice of Allowance",
+    "NACT": "Notice of Allowance",
+    "IDS":  "Information Disclosure Statement",
+    "REM":  "Remarks",
+    "ABST": "Abstract",
+    "CLM":  "Claims",
+    "SPEC": "Specification",
+}
+
+# FormParagraph 번호 분류
+_FP_REJECTION      = "07-21-aia"   # 거절 항목 (CTNF/CTFR)
+_FP_FINAL_FLAG     = "07-39"       # Final Action 선언
+_FP_ALLOWED_CLAIMS = "12-151-07"   # 허여 청구항
+_FP_ALLOW_REASON   = "13-03"       # 허여 이유 (Examiner's Statement)
+
+
+# ── 텍스트 정규화 ────────────────────────────────────────────────
+
+def _fp_text(fp_el) -> str:
+    """FormParagraph 요소의 텍스트를 정규화해서 반환."""
+    raw = " ".join(fp_el.itertext())
+    text = re.sub(r"\s+", " ", raw).strip()
+    text = re.sub(r"^[\w\.\-]+ (?:AIA )?", "", text, count=1)
+    return text
+
+
+def _all_text(root) -> str:
+    """루트 하위 전체 텍스트 추출 및 정규화."""
+    return re.sub(r"\s+", " ", " ".join(root.itertext())).strip()
+
+
+# ── 문서 타입별 파서 ─────────────────────────────────────────────
+
+def _fp_iter(root, number: str):
+    for fp in root.iter(f"{USCOM}FormParagraph"):
+        num_el = fp.find(f"{USCOM}FormParagraphNumber")
+        if num_el is not None and (num_el.text or "").strip() == number:
+            yield fp
+
+
+def _parse_oa(root) -> dict:
+    """CTNF / CTFR: 거절 항목 파싱."""
+    rejections = [_fp_text(fp) for fp in _fp_iter(root, _FP_REJECTION)]
+    is_final = any(True for _ in _fp_iter(root, _FP_FINAL_FLAG))
+    return {
+        "is_final": is_final,
+        "rejections": rejections,
+    }
+
+
+def _parse_noa(root) -> dict:
+    """NOA: 허여 청구항 + 허여 이유 파싱."""
+    allowed = next((_fp_text(fp) for fp in _fp_iter(root, _FP_ALLOWED_CLAIMS)), "")
+    reason  = next((_fp_text(fp) for fp in _fp_iter(root, _FP_ALLOW_REASON)),   "")
+    return {
+        "allowed_claims": allowed,
+        "reason": reason,
+    }
+
+
+# ── 파일 단위 파서 ────────────────────────────────────────────────
+
+def parse_xml_file(xml_path: Path) -> Optional[dict]:
+    """
+    XML 파일 1개를 파싱해 구조화된 dict로 반환.
+
+    Returns None if the file is not a parseable prosecution document.
+    """
+    stem_parts = xml_path.stem.split("_", 2)
+    if len(stem_parts) < 2:
+        return None
+    date, code = stem_parts[0], stem_parts[1]
+    doc_id = stem_parts[2] if len(stem_parts) > 2 else ""
+
+    try:
+        tree = ET.parse(xml_path)
+        root = tree.getroot()
+    except ET.ParseError as e:
+        logger.warning(f"XML 파싱 실패 {xml_path.name}: {e}")
+        return None
+
+    base = {
+        "date":   date,
+        "code":   code,
+        "doc_id": doc_id,
+        "label":  CODE_LABELS.get(code, code),
+        "path":   str(xml_path),
+        "fmt":    "xml",
+    }
+
+    if code in ("CTNF", "CTFR"):
+        return {**base, **_parse_oa(root)}
+    if code in ("NOA", "NACT"):
+        return {**base, **_parse_noa(root)}
+
+    return None
+
+
+# ── 타임라인 조합 ────────────────────────────────────────────────
+
+def build_timeline(app_number: str, file_dir: Optional[str] = None) -> list[dict]:
+    """
+    file_dir 내 모든 파일(.xml / .pdf)을 날짜순으로 정리해 타임라인 리스트를 반환.
+    XML 파싱 가능 문서는 파싱 결과를 포함하고, PDF는 경로 참조만 포함한다.
+    """
+    if file_dir is None:
+        file_dir = str(Path.cwd() / "file" / app_number)
+
+    base_dir = Path(file_dir)
+    entries: dict[str, dict] = {}
+
+    for f in sorted(base_dir.glob("*.pdf")):
+        stem_parts = f.stem.split("_", 2)
+        if len(stem_parts) < 2:
+            continue
+        date, code = stem_parts[0], stem_parts[1]
+        doc_id = stem_parts[2] if len(stem_parts) > 2 else ""
+        key = f"{date}_{code}_{doc_id}"
+        entries[key] = {
+            "date": date, "code": code, "doc_id": doc_id,
+            "label": CODE_LABELS.get(code, code),
+            "path": str(f), "fmt": "pdf",
+        }
+
+    for f in sorted(base_dir.glob("*.xml")):
+        stem_parts = f.stem.split("_", 2)
+        if len(stem_parts) < 2:
+            continue
+        date, code = stem_parts[0], stem_parts[1]
+        doc_id = stem_parts[2] if len(stem_parts) > 2 else ""
+        key = f"{date}_{code}_{doc_id}"
+        parsed = parse_xml_file(f)
+        if parsed:
+            entries[key] = parsed
+        else:
+            entries[key] = {
+                "date": date, "code": code, "doc_id": doc_id,
+                "label": CODE_LABELS.get(code, code),
+                "path": str(f), "fmt": "xml",
+            }
+
+    return sorted(entries.values(), key=lambda x: x["date"])
+
+
+# ── MD 렌더러 ─────────────────────────────────────────────────────
+
+def render_md(app_number: str, timeline: list[dict]) -> str:
+    lines: list[str] = []
+
+    lines += [f"# 심사과정 분석 — {app_number}", ""]
+
+    lines += ["## 타임라인", ""]
+    lines += ["| 날짜 | 문서 | 형식 | 파일 |"]
+    lines += ["|------|------|:----:|------|"]
+    for e in timeline:
+        lines.append(
+            f"| {e['date']} | {e['label']} (`{e['code']}`) "
+            f"| {e['fmt'].upper()} | `{Path(e['path']).name}` |"
+        )
+    lines += [""]
+
+    oa_docs = [e for e in timeline if e["code"] in ("CTNF", "CTFR") and "rejections" in e]
+    if oa_docs:
+        lines += ["---", "## Office Action 상세", ""]
+        for doc in oa_docs:
+            oa_type = "Final Rejection" if doc.get("is_final") else "Non-Final Rejection"
+            lines += [f"### {oa_type} — {doc['date']}", ""]
+            for i, rej in enumerate(doc["rejections"], 1):
+                lines += [f"**거절 {i}**", "", rej, ""]
+
+    noa_docs = [e for e in timeline if e["code"] in ("NOA", "NACT") and "allowed_claims" in e]
+    if noa_docs:
+        lines += ["---", "## Notice of Allowance 상세", ""]
+        for doc in noa_docs:
+            lines += [f"### {doc['date']}", ""]
+            if doc.get("allowed_claims"):
+                lines += ["**허여 청구항**", "", doc["allowed_claims"], ""]
+            if doc.get("reason"):
+                lines += ["**허여 이유 (Examiner's Statement)**", "", doc["reason"], ""]
+
+    pdf_only = [e for e in timeline if e["fmt"] == "pdf" and "rejections" not in e and "allowed_claims" not in e]
+    if pdf_only:
+        lines += ["---", "## PDF 전용 문서 (텍스트 추출 불가)", ""]
+        lines += ["아래 파일은 이미지 PDF로 구성되어 자동 파싱이 불가합니다. AI 에이전트에 직접 전달하세요.", ""]
+        lines += ["| 날짜 | 문서 | 파일 |"]
+        lines += ["|------|------|------|"]
+        for e in pdf_only:
+            lines.append(f"| {e['date']} | {e['label']} (`{e['code']}`) | `{Path(e['path']).name}` |")
+        lines += [""]
+
+    return "\n".join(lines)
+
+
+# ── 진입점 ────────────────────────────────────────────────────────
+
+def extract(
+    app_number: str,
+    file_dir: Optional[str] = None,
+    output_path: Optional[str] = None,
+) -> str:
+    """다운로드된 파일을 파싱해 MD 문자열을 반환하고, output_path가 지정되면 파일로 저장."""
+    timeline = build_timeline(app_number, file_dir)
+    md = render_md(app_number, timeline)
+
+    if output_path:
+        Path(output_path).write_text(md, encoding="utf-8")
+        logger.info(f"저장 완료: {output_path}")
+
+    return md

oa_cli/uspto/client.py

@@ -0,0 +1,40 @@
+"""USPTO ODP API HTTP 클라이언트 (재시도/백오프 포함)."""
+
+import time
+import logging
+import requests
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def make_api_request(
+    url: str,
+    api_key: str,
+    params: Optional[Dict[str, Any]] = None,
+    timeout: int = 30,
+    retries: int = 3,
+    backoff_factor: float = 1.0,
+) -> Dict[str, Any]:
+    headers = {
+        "X-API-KEY": api_key,
+        "accept": "application/json",
+    }
+    for i in range(retries):
+        try:
+            logger.debug(f"GET {url}  params={params}")
+            resp = requests.get(url, headers=headers, params=params, timeout=timeout)
+            resp.raise_for_status()
+            return resp.json()
+        except requests.HTTPError as e:
+            if e.response.status_code in (429, 500, 502, 503, 504) and i < retries - 1:
+                wait = backoff_factor * (2 ** i)
+                logger.warning(f"HTTP {e.response.status_code}, {wait:.0f}초 후 재시도...")
+                time.sleep(wait)
+            else:
+                logger.error(f"API 요청 실패: {e}")
+                raise
+        except requests.RequestException as e:
+            logger.error(f"API 요청 실패: {e}")
+            raise
+    raise RuntimeError("재시도 횟수 초과")

oa_cli/uspto/documents.py

@@ -0,0 +1,20 @@
+"""출원 문서 목록 조회 엔드포인트 래퍼."""
+
+import logging
+from typing import Any, Dict
+
+from oa_cli.uspto.client import make_api_request
+
+logger = logging.getLogger(__name__)
+
+BASE_URL = "https://api.uspto.gov/api/v1/patent"
+
+
+def get_application_documents(
+    api_key: str,
+    application_number: str,
+    timeout: int = 30,
+) -> Dict[str, Any]:
+    """출원번호에 해당하는 전체 문서 목록을 반환."""
+    url = f"{BASE_URL}/applications/{application_number}/documents"
+    return make_api_request(url, api_key, timeout=timeout)

oa_cli/uspto/download.py

@@ -0,0 +1,80 @@
+"""파일 스트리밍 다운로드 유틸 (재시도/백오프 포함)."""
+
+import time
+import logging
+from pathlib import Path
+from typing import Optional
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+def download_bytes(
+    url: str,
+    api_key: str,
+    retries: int = 5,
+    backoff_factor: float = 1.0,
+    timeout: int = 120,
+) -> bytes:
+    """URL에서 파일을 다운로드해 bytes로 반환 (tar 등 중간 처리가 필요한 경우)."""
+    headers = {"x-api-key": api_key}
+    for attempt in range(retries):
+        try:
+            resp = requests.get(url, headers=headers, timeout=timeout, allow_redirects=True)
+            resp.raise_for_status()
+            return resp.content
+        except requests.HTTPError as e:
+            if e.response.status_code in (429, 500, 502, 503, 504) and attempt < retries - 1:
+                wait = backoff_factor * (2 ** attempt)
+                logger.warning(f"HTTP {e.response.status_code}, {wait:.0f}초 후 재시도...")
+                time.sleep(wait)
+            else:
+                raise
+        except requests.RequestException as e:
+            if attempt < retries - 1:
+                wait = backoff_factor * (2 ** attempt)
+                logger.warning(f"요청 오류 ({e}), {wait:.0f}초 후 재시도...")
+                time.sleep(wait)
+            else:
+                raise
+    raise RuntimeError(f"다운로드 재시도 횟수 초과: {url}")
+
+
+def download_file(
+    url: str,
+    api_key: str,
+    save_path: str,
+    retries: int = 5,
+    backoff_factor: float = 1.0,
+    timeout: int = 120,
+) -> str:
+    """URL에서 파일을 다운로드해 save_path에 저장하고 경로를 반환."""
+    Path(save_path).parent.mkdir(parents=True, exist_ok=True)
+    headers = {"x-api-key": api_key}
+
+    for attempt in range(retries):
+        try:
+            resp = requests.get(url, headers=headers, stream=True, timeout=timeout, allow_redirects=True)
+            resp.raise_for_status()
+            with open(save_path, "wb") as f:
+                for chunk in resp.iter_content(chunk_size=8192):
+                    f.write(chunk)
+            logger.debug(f"저장 완료: {save_path}")
+            return save_path
+        except requests.HTTPError as e:
+            if e.response.status_code in (429, 500, 502, 503, 504) and attempt < retries - 1:
+                wait = backoff_factor * (2 ** attempt)
+                logger.warning(f"HTTP {e.response.status_code}, {wait:.0f}초 후 재시도...")
+                time.sleep(wait)
+            else:
+                raise
+        except requests.RequestException as e:
+            if attempt < retries - 1:
+                wait = backoff_factor * (2 ** attempt)
+                logger.warning(f"요청 오류 ({e}), {wait:.0f}초 후 재시도...")
+                time.sleep(wait)
+            else:
+                raise
+
+    raise RuntimeError(f"다운로드 재시도 횟수 초과: {url}")

uspto_oa_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: uspto-oa-cli
+Version: 0.1.0
+Summary: USPTO 특허 심사과정 분석 CLI — 문서 다운로드 · XML 파싱 · MD 생성
+Project-URL: Homepage, https://github.com/noaa/uspto-oa-cli
+License: MIT
+Keywords: cli,office-action,patent,prosecution,uspto
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Legal Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.13
+Requires-Dist: click>=8.0
+Requires-Dist: pypdf>=6.11.0
+Requires-Dist: requests>=2.34.2
+Requires-Dist: rich>=15.0.0
+Description-Content-Type: text/markdown
+
+# odp-oa-cli
+
+USPTO ODP(Open Data Portal) API를 통해 미국 특허 심사과정 문서를 다운로드하고, XML 파싱을 거쳐 구조화된 Markdown으로 변환하는 CLI 도구.
+
+생성된 MD 파일을 Claude Code, Gemini CLI 등 AI 에이전트에게 전달하여 심사 전략 분석을 수행하는 워크플로우를 지원한다.
+
+## 요구사항
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/)
+- USPTO API 키 ([ODP 포털](https://developer.uspto.gov/)에서 발급)
+
+## 설치
+
+```bash
+# 로컬 개발
+uv sync
+
+# PyPI에서 설치
+pip install odp-oa-cli
+```
+
+## API 키 설정
+
+```bash
+# 대화형 설정 (권장) — ~/.oa-cli.toml 에 저장
+uspto-oa configure
+
+# 현재 설정 확인
+uspto-oa configure --show
+```
+
+또는 환경변수로 지정:
+
+```bash
+export USPTO_API_KEY=your_api_key_here
+```
+
+## 사용법
+
+```bash
+# 1. 문서 다운로드 (file/{app_num}/ 에 저장)
+uspto-oa download 16330077
+
+# 2. XML 파싱 → prosecution.md 생성
+uspto-oa extract 16330077
+# 결과: file/16330077/16330077_prosecution.md
+
+# 특허번호 입력 (출원번호 자동 변환)
+uspto-oa download US12228644B2
+
+# 특정 문서 코드만 다운로드
+uspto-oa download 16330077 --doc-codes CTNF,CTFR,NOA
+
+# 강제 재다운로드 (기존 파일 덮어쓰기)
+uspto-oa download 16330077 --force
+
+# 상세 로그
+uspto-oa -v download 16330077
+
+# 일회성 API 키 지정
+uspto-oa download 16330077 --api-key YOUR_KEY
+```
+
+### 커맨드 옵션
+
+**`uspto-oa download <application>`**
+
+| 옵션 | 설명 |
+|------|------|
+| `--doc-codes CODES` | 쉼표 구분 문서 코드 (예: `CTNF,CTFR,NOA`). 생략 시 전체 수집 대상 |
+| `--output-dir DIR` | 저장 경로 (기본: `file/{app_num}/`) |
+| `--force` | 기존 파일도 재다운로드 |
+| `--api-key TEXT` | API 키 (설정 파일·환경변수보다 우선) |
+
+**`uspto-oa extract <application>`**
+
+| 옵션 | 설명 |
+|------|------|
+| `--output-dir DIR` | 파일 디렉토리 (기본: `file/{app_num}/`) |
+
+## 워크플로우
+
+```
+uspto-oa download {app_num}
+    └─ file/{app_num}/ 에 XML / PDF 저장
+
+uspto-oa extract {app_num}
+    └─ file/{app_num}/{app_num}_prosecution.md 생성
+         └─ AI 에이전트 (Claude Code / Gemini CLI)
+              └─ 심사 전략 분석, 요약, 질의응답
+```
+
+## 수집 대상 문서 코드
+
+| 코드 | 의미 |
+|------|------|
+| `CTNF` | Non-Final Office Action |
+| `CTFR` | Final Office Action |
+| `NOA` / `NACT` | Notice of Allowance |
+| `REM` | Remarks (의견서) |
+| `ABN` | Abandonment |
+| `SRNT` / `SRFW` | Search Report |
+| `EXIN` | Examiner Interview |
+| `RCE` / `RCEX` | Request for Continued Examination |
+| `CTAV` | Advisory Action |
+| `892` / `1449` / `IDS` | Prior Art / IDS |
+| `A*` | Amendment 계열 전체 |
+
+## 생성 파일 구조
+
+`file/{app_num}/{app_num}_prosecution.md`:
+
+| 섹션 | 내용 |
+|------|------|
+| 타임라인 | 전체 문서 날짜순 표 (XML/PDF 형식 표시) |
+| Office Action 상세 | CTNF/CTFR 거절 항목 전문 |
+| Notice of Allowance 상세 | 허여 청구항 + Examiner's Statement |
+| PDF 전용 문서 | Amendment 등 이미지 PDF 목록 (AI 에이전트 직접 전달용) |
+
+## PyPI 배포
+
+```bash
+uv build
+uv run twine upload dist/*
+```

uspto_oa_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+oa_cli/__init__.py,sha256=Tz-z_JrYhmQMHHjU-Q97aHHHNHCXt6iiaWwclYeWj38,79
+oa_cli/__main__.py,sha256=6MqQj8hojdWpAWJpV-K8aTvt68GacvVuUOsidQUKwoM,67
+oa_cli/cli.py,sha256=EgRmGiYydzibqBAQCYa25HEsgbo_o3H5kR3KJ_zEXAE,6683
+oa_cli/config.py,sha256=RK5L9uV9dhgoOToSiugGOtvft4iD-ef7_F7xYHej1Ng,3218
+oa_cli/prosecution/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oa_cli/prosecution/collect.py,sha256=KePpLRw4UI_FrP5TEOBu0rnMTNTSsn_jMRhXxKE1NTY,7645
+oa_cli/prosecution/extract.py,sha256=MuAGrPjUpxRX9Ec5Irsf0NrtKczuO6gBssc31RY43_4,8332
+oa_cli/uspto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oa_cli/uspto/client.py,sha256=Ia4I03uTZtSC0olzBXsozeJDOKQBkXqjVZtj1Ftwb4M,1303
+oa_cli/uspto/documents.py,sha256=_KGmav2TAb2Zy-udMAzgf-5Tp9WTblzmZZDYdL42OR8,563
+oa_cli/uspto/download.py,sha256=7BIuNonUqyLiQuMEMqZKpn-RwSF2xRPB5vW1mX8CTa4,2943
+uspto_oa_cli-0.1.0.dist-info/METADATA,sha256=MgN6wwKHkalVQ2VlqBIam338TYdnup3lfwpv6NgyY6I,4069
+uspto_oa_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+uspto_oa_cli-0.1.0.dist-info/entry_points.txt,sha256=XOUMittc-2rOkgd1hPa4S0tZyJHSgoOy5QLX1HPDi9E,45
+uspto_oa_cli-0.1.0.dist-info/RECORD,,

uspto_oa_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

uspto_oa_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+uspto-oa = oa_cli.cli:main