capabilities 디스커버리 마크다운 엔드포인트 (#62) #63

Merged

xhh merged 1 commit from issue-62-meta-capabilities into main

2026-04-26 13:09:39 +09:00

xhh commented

2026-04-26 04:47:09 +09:00

Owner

Closes #62.

요약

Claude 스킬이 시작 시점에 한 번 fetch 해 "이 플랫폼이 어떤 데이터를 줄 수 있는지" 한 번에 흡수하기 위한 LLM 친화 마크다운 디스커버리 엔드포인트. 통합 로드맵 Phase 1 의 스킬 통합 시발점.

curl -s https://stock.xhhan.com/api/meta/capabilities

응답은 text/markdown — JSON 파싱 단계 없이 그대로 LLM 컨텍스트로 흡수.

구현 포인트

routers/system.py::meta_capabilities 신규 — Request 주입으로 app.routes 를 직접 스캔해 마크다운 생성
새 라우트/심볼/데이터가 추가되면 capabilities 도 자동 반영 (정적 템플릿 X)
self / 도큐먼트 라우트 (/, /scalar, /api/version, /api/health, /api/meta/capabilities) 는 본문 안내가 따로 있어 디스커버리 목록에서 제외
응답 본문 ~3KB (목표 < 800 토큰 만족)
OpenAPI 에 text/markdown 응답 schema 명시
짝꿍 #15 (POST /api/meta/data-gaps) 안내 텍스트 포함 (미구현 시 무시 안내)

본문 구성 (동적)

데이터 소스 표 — indicators.yaml 의 FRED/Equity/Crypto 카테고리별 심볼 수
테이블 커버리지 — _COVERAGE_TABLES 의 행수 + 최신일
엔드포인트 — app.routes 에서 APIRoute 만 스캔, include_in_schema=True 필터
사용 규칙 — 인증, CompactSeries, data-gaps 짝꿍 안내

테스트

tests/api/test_meta_capabilities.py 신규 6 case:

text/markdown + 200 반환
주요 라우트 (/api/meta/symbols, /api/prices/, /api/indicators, /api/analysis/liquidity-snapshot) 가 자동으로 잡히는지
self/문서 라우트 제외
DB 에 행 추가 후 행수/최신일이 갱신되는지 (동적 생성 검증)
페이로드 6KB 미만
data-gaps 짝꿍 안내 노출

전체: 111 passed, ruff clean.

README

"Claude 스킬 통합 — capabilities 부터 시작" 섹션 신규 (#62 본문에 명시된 "스킬 통합 진입 가이드 1단락"). Sprint 1 엔드포인트 목록에도 추가.

후속

#6 (유동성 분석 스킬 시범 전환) — 이 엔드포인트가 있으니 스킬 프롬프트에 한 줄 추가해 호출 가능
#15 (data_gaps 피드백 루프) — capabilities 가 read, data_gaps 가 write. 짝으로 결합 시 "능력 광고 + 빈틈 수집" 양면 완성

Test plan

uv run pytest tests/api/test_meta_capabilities.py -v (6 passed)
uv run pytest (111 passed)
uv run ruff check
배포 후 curl https://stock.xhhan.com/api/meta/capabilities 로 실제 응답 확인

Closes #62. ## 요약 Claude 스킬이 시작 시점에 한 번 fetch 해 "이 플랫폼이 어떤 데이터를 줄 수 있는지" 한 번에 흡수하기 위한 LLM 친화 마크다운 디스커버리 엔드포인트. 통합 로드맵 Phase 1 의 스킬 통합 시발점. ```bash curl -s https://stock.xhhan.com/api/meta/capabilities ``` 응답은 `text/markdown` — JSON 파싱 단계 없이 그대로 LLM 컨텍스트로 흡수. ## 구현 포인트 - `routers/system.py::meta_capabilities` 신규 — `Request` 주입으로 `app.routes` 를 직접 스캔해 마크다운 생성 - 새 라우트/심볼/데이터가 추가되면 capabilities 도 자동 반영 (정적 템플릿 X) - self / 도큐먼트 라우트 (`/`, `/scalar`, `/api/version`, `/api/health`, `/api/meta/capabilities`) 는 본문 안내가 따로 있어 디스커버리 목록에서 제외 - 응답 본문 ~3KB (목표 < 800 토큰 만족) - OpenAPI 에 `text/markdown` 응답 schema 명시 - 짝꿍 #15 (`POST /api/meta/data-gaps`) 안내 텍스트 포함 (미구현 시 무시 안내) ## 본문 구성 (동적) 1. 데이터 소스 표 — indicators.yaml 의 FRED/Equity/Crypto 카테고리별 심볼 수 2. 테이블 커버리지 — `_COVERAGE_TABLES` 의 행수 + 최신일 3. 엔드포인트 — `app.routes` 에서 `APIRoute` 만 스캔, `include_in_schema=True` 필터 4. 사용 규칙 — 인증, CompactSeries, data-gaps 짝꿍 안내 ## 테스트 `tests/api/test_meta_capabilities.py` 신규 6 case: - `text/markdown` + 200 반환 - 주요 라우트 (`/api/meta/symbols`, `/api/prices/`, `/api/indicators`, `/api/analysis/liquidity-snapshot`) 가 자동으로 잡히는지 - self/문서 라우트 제외 - DB 에 행 추가 후 행수/최신일이 갱신되는지 (동적 생성 검증) - 페이로드 6KB 미만 - data-gaps 짝꿍 안내 노출 전체: 111 passed, ruff clean. ## README "Claude 스킬 통합 — capabilities 부터 시작" 섹션 신규 (#62 본문에 명시된 "스킬 통합 진입 가이드 1단락"). Sprint 1 엔드포인트 목록에도 추가. ## 후속 - #6 (유동성 분석 스킬 시범 전환) — 이 엔드포인트가 있으니 스킬 프롬프트에 한 줄 추가해 호출 가능 - #15 (data_gaps 피드백 루프) — capabilities 가 read, data_gaps 가 write. 짝으로 결합 시 "능력 광고 + 빈틈 수집" 양면 완성 ## Test plan - [x] `uv run pytest tests/api/test_meta_capabilities.py -v` (6 passed) - [x] `uv run pytest` (111 passed) - [x] `uv run ruff check` - [ ] 배포 후 `curl https://stock.xhhan.com/api/meta/capabilities` 로 실제 응답 확인

xhh added 1 commit

2026-04-26 04:47:10 +09:00

feat: /api/meta/capabilities 디스커버리 마크다운 엔드포인트 (#62 )

Tests (PR) / pytest (pull_request) Successful in 27s

Details

80faaf8491

스킬이 시작 시점에 fetch 해 '이 플랫폼이 어떤 데이터를 줄 수 있는지'
한 번에 흡수하기 위한 LLM 친화 마크다운 응답.

- 라우터: 등록된 APIRoute 를 자동 스캔 (include_in_schema=True 만)
  → 새 엔드포인트가 추가되면 capabilities 응답이 자동 반영
- 데이터 소스: indicators.yaml 카테고리별 심볼 수
- 테이블 커버리지: COVERAGE_TABLES 의 행수 + 최신일
- 응답: text/markdown; charset=utf-8 (JSON 파싱 단계 불필요)
- OpenAPI: text/markdown 응답 명시
- 짝꿍 #15 (data-gaps) 안내 텍스트 포함

self / 도큐먼트 라우트 (/, /scalar, /api/version, /api/health,
/api/meta/capabilities) 는 본문 안내가 따로 있어 디스커버리
목록에서 제외.

회귀 테스트 6개:
- 200 + text/markdown 반환
- 핵심 라우트 (/api/meta/symbols, /api/prices/, /api/indicators,
  /api/analysis/liquidity-snapshot) 자동 노출
- self/문서 제외
- DB 행 추가 시 행수/최신일 반영 (동적 생성 검증)
- 페이로드 < 6KB (~800 토큰)
- data-gaps 짝꿍 안내 노출

README: 'Claude 스킬 통합 — capabilities 부터 시작' 섹션 추가
및 Sprint 1 엔드포인트 목록에 /api/meta/capabilities 명시.

Closes #62

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>