uspto-oa-cli 0.1.0__tar.gz

uspto_oa_cli-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# data
+file/
+
+# AI Coding Assistants configs & logs
+.antigravitycli/
+.claude/
+
+# secrets
+.env
+
+# temp
+temp/
+test/

uspto_oa_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

uspto_oa_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,84 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 프로젝트 개요
+
+USPTO ODP(Open Data Portal) API를 통해 미국 특허 심사과정 문서를 다운로드하고, XML 파싱을 거쳐 구조화된 Markdown으로 변환하는 CLI 도구. AI 에이전트(Claude Code, Gemini CLI)가 생성된 MD 파일을 읽고 심사 전략을 분석하는 워크플로우를 목표로 한다. LLM API 직접 호출은 최소화하고 AI 코딩 에이전트에게 분석을 위임하는 방식을 지향한다.
+
+## 실행 명령
+
+```bash
+# 의존성 설치
+uv sync
+
+# API 키 설정 (최초 1회) → ~/.oa-cli.toml 에 저장
+uv run uspto-oa configure
+
+# 문서 다운로드
+uv run uspto-oa download 16330077
+
+# XML 파싱 → MD 생성 (file/{app_num}/{app_num}_prosecution.md)
+uv run uspto-oa extract 16330077
+
+# 특허번호 입력 (출원번호 자동 변환)
+uv run uspto-oa download US12228644B2
+
+# 특정 문서 코드만 다운로드
+uv run uspto-oa download 16330077 --doc-codes CTNF,CTFR,NOA
+
+# 강제 재다운로드
+uv run uspto-oa download 16330077 --force
+
+# 상세 로그
+uv run uspto-oa -v download 16330077
+
+# PyPI 배포 (빌드 → 업로드)
+uv build && uv run twine upload dist/*
+```
+
+**API 키 우선순위**: `--api-key` 옵션 > `USPTO_API_KEY` 환경변수 > `~/.oa-cli.toml` (개발 시 `.env` 자동 로드)
+
+## 소스 구조
+
+```
+src/oa_cli/                 # PyPI 배포 패키지 (hatchling wheel 타겟)
+├── __init__.py             # __version__
+├── __main__.py             # python -m oa_cli 지원
+├── cli.py                  # click 진입점 (configure / download / extract 커맨드)
+├── config.py               # API 키 우선순위 관리, ~/.oa-cli.toml 읽기/쓰기
+├── uspto/                  # USPTO ODP API 저수준 클라이언트 (도메인 무관)
+│   ├── client.py           # make_api_request() — GET + 재시도/백오프
+│   ├── documents.py        # get_application_documents() — 문서 목록 API
+│   └── download.py         # download_file() / download_bytes()
+└── prosecution/            # 심사과정 분석 도메인 로직
+    ├── collect.py          # 문서 필터링 + XML 우선 일괄 다운로드
+    └── extract.py          # XML 파싱 → prosecution.md 생성
+file/
+└── {app_num}/              # 다운로드 파일 + 생성된 MD 저장 위치
+```
+
+## 아키텍처 핵심 사항
+
+**레이어 분리**: `src/uspto/`는 API 통신만 담당(도메인 무관), `src/prosecution/`은 심사과정 비즈니스 로직 담당. `cli.py`는 두 레이어를 연결하는 진입점.
+
+**서버사이드 필터 미사용**: USPTO API의 `documentCodes` 파라미터가 500 오류를 유발하므로, 전건 조회 후 클라이언트에서 필터링한다(`collect.py`의 `PROSECUTION_CODES_EXACT` / `PROSECUTION_CODE_PREFIXES`).
+
+**파일명 규칙**: `{날짜}_{코드}_{문서ID}.{ext}` — 날짜 오름차순 정렬, 확장자는 실제 포맷 반영.
+
+**다운로드 우선순위**: XML > PDF (MS_WORD 제외). XML은 tar 아카이브로 전달되므로 압축 해제 후 저장하며, tar 내 `.xml` 없거나 오류 시 PDF로 자동 폴백.
+
+**XML 구조 (USPTO ST96 스키마)**: CTNF/CTFR는 `FormParagraph[07-21-aia]`에 거절 항목, NOA/NACT는 `FormParagraph[12-151-07]`에 허여 청구항, `FormParagraph[13-03]`에 Examiner's Statement 포함.
+
+**PDF 특이사항**: USPTO OA PDF는 전 페이지 이미지 구성 → pypdf 텍스트 추출 불가. PDF 전용 문서(Amendment 등)는 MD에 경로만 참조로 포함하고 AI 에이전트가 필요 시 직접 읽도록 한다.
+
+**생성 MD 구조** (`{app_num}_prosecution.md`):
+- 타임라인 표 (전체 문서, XML/PDF 형식 표시)
+- Office Action 상세 (CTNF/CTFR 거절 항목 전문)
+- Notice of Allowance 상세 (허여 청구항 + Examiner's Statement)
+- PDF 전용 문서 목록 (AI 에이전트 직접 전달용)
+
+## 다음 구현 단계
+
+- `--step summary/detail/prior-art/strategy` — 생성된 prosecution.md를 AI 에이전트에 넘기는 분석 진입점 (LLM API 직접 호출 없이 Claude Code / Gemini CLI에 위임)
+- `--no-download` — 이미 다운로드된 파일 기준으로 `--extract` 바로 수행

uspto_oa_cli-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,126 @@
+# 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/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "uspto-oa-cli"
+version = "0.1.0"
+description = "USPTO 특허 심사과정 분석 CLI — 문서 다운로드 · XML 파싱 · MD 생성"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.13"
+keywords = ["uspto", "patent", "office-action", "prosecution", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Legal Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+]
+dependencies = [
+    "click>=8.0",
+    "pypdf>=6.11.0",
+    "requests>=2.34.2",
+    "rich>=15.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/noaa/uspto-oa-cli"
+
+[project.scripts]
+uspto-oa = "oa_cli.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oa_cli"]
+
+[dependency-groups]
+dev = [
+    "python-dotenv>=1.0",
+    "hatchling>=1.29.0",
+    "twine>=6.0",
+    "pytest>=8.0",
+    "ruff>=0.4",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]

uspto_oa_cli-0.1.0/src/oa_cli/__init__.py

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

uspto_oa_cli-0.1.0/src/oa_cli/__main__.py

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

uspto_oa_cli-0.1.0/src/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}")