open-gil 0.1.0__tar.gz

open_gil-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+- Initial MVP CLI package.
+- Added TMAP-backed public-transit route planning.
+- Added `open-gil config set-key` and `open-gil plan`.
+- Added JSON input/output for agent integrations.
+- Added in-repository `skills/open-gil` agent instructions.
+- Added Kakao Local coordinate fallback for place-name lookup.
+- Moved `open-gil` into the `packages/open-gil` monorepo package layout.
+- Added fixture/mock tests and optional live TMAP test.

open_gil-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 open-gil 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.
+

open_gil-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include CHANGELOG.md
+include LICENSE
+include README.md
+recursive-include skills *.md
+recursive-include tests *.py *.json

open_gil-0.1.0/PKG-INFO

@@ -0,0 +1,313 @@
+Metadata-Version: 2.4
+Name: open-gil
+Version: 0.1.0
+Summary: API-backed public transit departure planner for Seoul, Gyeonggi, and Incheon.
+Author: open-gil contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/doul735/open_tools
+Project-URL: Repository, https://github.com/doul735/open_tools
+Project-URL: Issues, https://github.com/doul735/open_tools/issues
+Project-URL: Changelog, https://github.com/doul735/open_tools/blob/main/packages/open-gil/CHANGELOG.md
+Keywords: transit,tmap,cli,korea,route-planning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Natural Language :: Korean
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# open-gil
+
+TMAP API로 계산하고, LLM이 지어내지 못하게 막는 대중교통 출발시간 CLI.
+
+`open-gil`은 “몇 시에 출발해야 하지?”라는 질문에 대해 출발지, 목적지, 일정 시각을 받아 대중교통 경로와 추천 출발 시간을 계산합니다. Codex, Claude Code 같은 LLM은 자연어를 구조화하고 확인 질문을 하는 데만 쓰고, 출발시각, 환승, 소요시간, 도착시각은 TMAP 대중교통 API 응답으로만 만듭니다.
+
+초기 MVP 범위는 서울, 경기, 인천입니다.
+
+## Why
+
+LLM은 길찾기 질문에 그럴듯한 답을 만들 수 있지만, 실제 대중교통 시간표와 환승 경로를 보장하지 못합니다. `open-gil`은 이 부분을 분리합니다.
+
+- LLM: “사용자가 말한 시간이 일정 시작인지, 도착 마감인지, 출발 시간인지” 확인
+- CLI: 장소 검색, 좌표 확정, TMAP 경로 조회, 출발시각 계산
+- 사용자: 네이버지도와 카카오맵 링크로 최종 확인
+
+핵심 원칙은 단순합니다. 모르면 추측하지 않고, API가 준 것만 말합니다.
+
+개발 과정, 시행착오, 현재 한계, 다음 개선 방향은 [open-gil Development Story](https://github.com/doul735/open_tools/blob/main/docs/open-gil-development-story.md)에 정리되어 있습니다.
+
+## Quick Start
+
+Until the first PyPI release is live, install from this repository:
+
+```bash
+pipx install "git+https://github.com/doul735/open_tools.git#subdirectory=packages/open-gil"
+```
+
+After PyPI release:
+
+```bash
+pipx install open-gil
+```
+
+Configure your TMAP key:
+
+```bash
+open-gil config set-key
+```
+
+그 다음 바로 물어볼 수 있습니다.
+
+```bash
+open-gil plan \
+  --origin "송도달빛축제공원역" \
+  --destination "올림픽공원 올림픽홀" \
+  --event-at "2026-06-06 13:00"
+```
+
+`--event-at`은 일정 시작 시각입니다. open-gil은 기본적으로 15분 전 도착을 목표로 출발시각을 추천합니다.
+
+## What You Get
+
+하루 10회 수준의 낮은 API 호출 제한을 고려해, 기본 모드는 TMAP 경로 조회 1회로 총 소요시간을 받아 목표 도착시각에서 출발시각을 역산합니다.
+
+이 방식은 API 호출을 아끼지만, “가장 늦은 출발”과 “이전/다음 수단”을 전수 검증하지는 않습니다. TMAP에 도착시각 기준 검색이 별도로 제공되지 않는 한, 그 기능은 여러 출발시각을 반복 조회해야 하므로 기본 MVP에서는 실행하지 않습니다.
+
+예시 출력은 이런 형태입니다.
+
+```text
+송도달빛축제공원역 -> 올림픽공원 올림픽홀
+기준: 2026-06-06 13:00 일정 시작, 목표 도착 2026-06-06 12:45
+
+추천: 2026-06-06 11:29 출발 -> 2026-06-06 12:45 도착 / 소요 1시간 16분 / 목표 도착 가능
+  경로: 도보 -> 지하철 인천1호선 -> 지하철 7호선 -> 도보
+
+추천 경로 상세
+- 도보: 출발지 -> 송도달빛축제공원역
+- 버스 광역:M6450: 송도달빛축제공원역 승차 -> 선릉역 하차
+- 같은 정류장 환승: 선릉역에서 버스 광역:M6450 하차 후 버스 간선:360 탑승
+- 버스 간선:360: 선릉역 승차 -> 잠실트리지움아파트앞 하차
+- 같은 정류장 환승: 잠실트리지움아파트앞에서 버스 간선:360 하차 후 버스 지선:3323 탑승
+- 버스 지선:3323: 잠실트리지움아파트앞 승차 -> 올림픽베어스타운아파트앞 하차
+- 도보: 올림픽베어스타운아파트앞 -> 올림픽홀
+
+탐색 방식: 하루 호출 제한을 고려해 TMAP 경로 조회 1회로 총 소요시간을 받아 목표 도착시각에서 역산했습니다. 이전/다음 수단 전수 탐색은 실행하지 않았습니다.
+
+확인 링크
+지도앱은 같은 출발/도착 좌표로 다시 길찾기하므로 위 TMAP 경로와 다를 수 있습니다.
+- 네이버지도: nmap://route/public?...
+- 카카오맵: http://m.map.kakao.com/scheme/route?...
+
+TMAP API 응답 기준입니다. 현장 지연, 운행 중단, 행사장 혼잡은 실제와 다를 수 있습니다.
+```
+
+위 출력은 형식 예시입니다. 실제 시간과 경로는 실행 시점의 TMAP API 응답에 따라 달라집니다.
+
+## Time Modes
+
+세 가지 시간 의도를 명확히 나눕니다.
+
+```bash
+# 일정 시작 시각. 15분 전 도착 목표.
+open-gil plan --origin "강남역" --destination "서울역" --event-at "2026-06-06 19:00"
+
+# 특정 시각까지 도착. 추가 버퍼 없음.
+open-gil plan --origin "강남역" --destination "서울역" --arrive-by "2026-06-06 18:30"
+
+# 특정 시각에 출발.
+open-gil plan --origin "강남역" --destination "서울역" --depart-at "2026-06-06 09:00"
+```
+
+날짜 없이 `09:00`처럼 입력하면 직접 CLI 사용에서는 오늘 날짜로 해석합니다. LLM 스킬 흐름에서는 날짜를 사용자에게 확인해야 합니다.
+
+## JSON for Agents
+
+Codex나 Claude Code 같은 에이전트는 JSON을 쓰는 편이 안전합니다.
+
+```bash
+cat <<'JSON' | open-gil plan --json
+{
+  "origin": {"name": "송도달빛축제공원역"},
+  "destination": {"name": "올림픽공원 올림픽홀"},
+  "event_at": "2026-06-06 13:00"
+}
+JSON
+```
+
+성공 응답은 항상 envelope 형태입니다.
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "time_mode": "event_at",
+    "arrival_buffer_minutes": 15,
+    "search_strategy": "quota_safe_target_arrival_single_lookup",
+    "route_api_calls_used": 1,
+    "candidates": []
+  }
+}
+```
+
+오류도 구조화됩니다.
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "OPEN_GIL_AUTH_INVALID",
+    "message": "TMAP API 키가 유효하지 않습니다.",
+    "remediation": "TMAP_API_KEY 값 또는 open-gil config set-key로 저장한 키를 확인하세요."
+  }
+}
+```
+
+장소 후보가 애매하면 `OPEN_GIL_PLACE_AMBIGUOUS`와 후보 목록을 반환합니다. 에이전트는 이때 임의로 고르지 말고 사용자에게 선택을 물어야 합니다.
+
+403 Forbidden처럼 키는 전달됐지만 호출 권한이 거절되면 `OPEN_GIL_AUTH_FORBIDDEN`으로 반환합니다. 이 경우 TMAP 앱키에 해당 API 상품/권한이 활성화되어 있는지, 요금제/도메인/IP 제한이 있는지 확인해야 합니다.
+
+호출 한도 초과는 `OPEN_GIL_QUOTA_EXCEEDED`로 반환합니다. 이 경우 자동 재시도하지 말고 TMAP 한도 초기화나 요금제/쿼터를 확인해야 합니다.
+
+## Natural-Language Agent Flow
+
+`$open-gil` 같은 에이전트 스킬은 자연어를 구조화한 뒤 CLI를 호출합니다.
+
+정확한 상태는 다음과 같습니다.
+
+- 장소명 검색과 경로 계산이 모두 성공하면 그대로 답변합니다.
+- TMAP POI 장소명 검색이 `OPEN_GIL_AUTH_FORBIDDEN`, `OPEN_GIL_PLACE_NOT_FOUND`, `OPEN_GIL_QUOTA_EXCEEDED`로 실패하고 `KAKAO_REST_API_KEY`가 있으면 Kakao Local 주소/키워드 검색으로 좌표를 보조 확인합니다.
+- 좌표가 확정되면 `open-gil plan --json`을 좌표 입력으로 다시 실행합니다. 이때 경로, 출발시각, 요금, 환승 정보는 TMAP Transit API 결과만 사용합니다.
+- Kakao Local 후보가 애매하거나 민감한 장소면 에이전트가 임의로 고르지 않고 사용자에게 선택 또는 좌표 제공을 요청해야 합니다.
+- TMAP Transit API 자체가 권한 오류, 한도 초과, 경로 없음으로 실패하면 경로 계산은 불가능합니다.
+
+즉 “자연어 스킬”은 좌표가 확정되고 Transit API가 성공하면 동작합니다. Kakao Local은 좌표화 fallback일 뿐이며, 경로 계산 source of truth는 항상 TMAP Transit API입니다.
+
+## Coordinates
+
+이미 장소를 확정했다면 좌표를 직접 넣을 수 있습니다. 좌표가 있으면 장소명 검색보다 우선합니다.
+
+```bash
+open-gil plan \
+  --origin-lat 37.407722 --origin-lon 126.625572 --origin-label "송도달빛축제공원역" \
+  --destination-lat 37.516289 --destination-lon 127.117314 --destination-label "올림픽홀" \
+  --event-at "2026-06-06 13:00"
+```
+
+## API Keys
+
+TMAP API 키는 필수입니다.
+
+1. SK Open API에서 앱을 만들고 appKey를 발급합니다.
+2. TMAP 대중교통 API와 POI 검색 API 사용 권한을 확인합니다.
+3. 환경변수나 로컬 설정 파일로 키를 설정합니다.
+
+환경변수가 우선입니다.
+
+```bash
+export TMAP_API_KEY="발급받은_appKey"
+```
+
+로컬 파일에 저장할 수도 있습니다.
+
+```bash
+open-gil config set-key
+```
+
+Kakao Local fallback은 선택이지만 자연어 장소명 품질을 크게 올립니다. Kakao Developers에서 REST API 키를 발급하고 Local API 사용을 확인한 뒤 설정합니다.
+
+```bash
+export KAKAO_REST_API_KEY="발급받은_REST_API_key"
+```
+
+또는 로컬 파일에 저장합니다.
+
+```bash
+open-gil config set-kakao-key
+```
+
+설정 파일은 `~/.config/open-gil/config.json`에 평문으로 저장됩니다. POSIX 환경에서는 `0600` 권한으로 맞춥니다.
+
+공식 문서:
+
+- TMAP 대중교통 API: https://transit.tmapmobility.com/docs/routes
+- TMAP POI 검색 API: https://tmap-skopenapi.readme.io/reference/%EC%9E%A5%EC%86%8C%ED%86%B5%ED%95%A9%EA%B2%80%EC%83%89
+- Kakao Local API: https://developers.kakao.com/docs/latest/ko/local/dev-guide
+- NAVER Maps URL Scheme: https://guide.ncloud-docs.com/docs/en/maps-url-scheme
+- KakaoMap URL Scheme: https://apis.map.kakao.com/ios_v2/docs/getting-started/urlscheme/
+
+## Install from Source
+
+```bash
+git clone https://github.com/doul735/open_tools.git
+cd open_tools
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e "./packages/open-gil[dev]"
+```
+
+## Tests
+
+기본 테스트는 fixture/mock 기반이라 API 키가 없어도 실행됩니다.
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 python -m pytest packages/open-gil/tests -p no:cacheprovider
+```
+
+실제 TMAP API 테스트는 `TMAP_API_KEY`가 있을 때만 실행됩니다.
+
+```bash
+export TMAP_API_KEY="발급받은_appKey"
+PYTHONDONTWRITEBYTECODE=1 python -m pytest packages/open-gil/tests/test_live_tmap.py -p no:cacheprovider
+```
+
+## Release Prep
+
+이 저장소는 GitHub Actions CI와 PyPI Trusted Publishing용 워크플로를 포함합니다.
+
+- CI: `.github/workflows/ci.yml`
+- PyPI publish: `.github/workflows/publish.yml`
+- Dependabot: `.github/dependabot.yml`
+
+로컬 배포 산출물 검증:
+
+```bash
+python -m pip install -e "./packages/open-gil[dev]"
+python -m build packages/open-gil
+```
+
+PyPI에 실제 배포하려면 PyPI에서 Trusted Publisher를 이 저장소와 `publish.yml` 워크플로에 연결하세요.
+
+Pending publisher 값:
+
+```text
+Project name: open-gil
+Owner: doul735
+Repository name: open_tools
+Workflow name: publish.yml
+Environment name: pypi
+```
+
+## Limits
+
+- 현재 MVP 범위는 서울, 경기, 인천입니다.
+- 계산 근거는 TMAP 대중교통 API입니다.
+- 목표 도착 모드는 기본적으로 경로 조회 1회로 출발시각을 역산합니다. 낮은 호출 제한 때문에 이전/추천/다음 수단 전수 탐색은 기본 제공하지 않습니다.
+- 네이버지도와 카카오맵 링크는 확인용이며 계산 근거가 아닙니다.
+- 네이버지도와 카카오맵 링크는 같은 출발/도착 좌표로 앱 자체 길찾기를 다시 실행하므로 TMAP 추천 경로와 다를 수 있습니다.
+- 별도 실시간 지연, 운행 중단, 행사장 혼잡 정보를 보장하지 않습니다.
+- 원문 자연어 프롬프트는 외부 API로 보내거나 캐시하지 않습니다.

open_gil-0.1.0/README.md

@@ -0,0 +1,280 @@
+# open-gil
+
+TMAP API로 계산하고, LLM이 지어내지 못하게 막는 대중교통 출발시간 CLI.
+
+`open-gil`은 “몇 시에 출발해야 하지?”라는 질문에 대해 출발지, 목적지, 일정 시각을 받아 대중교통 경로와 추천 출발 시간을 계산합니다. Codex, Claude Code 같은 LLM은 자연어를 구조화하고 확인 질문을 하는 데만 쓰고, 출발시각, 환승, 소요시간, 도착시각은 TMAP 대중교통 API 응답으로만 만듭니다.
+
+초기 MVP 범위는 서울, 경기, 인천입니다.
+
+## Why
+
+LLM은 길찾기 질문에 그럴듯한 답을 만들 수 있지만, 실제 대중교통 시간표와 환승 경로를 보장하지 못합니다. `open-gil`은 이 부분을 분리합니다.
+
+- LLM: “사용자가 말한 시간이 일정 시작인지, 도착 마감인지, 출발 시간인지” 확인
+- CLI: 장소 검색, 좌표 확정, TMAP 경로 조회, 출발시각 계산
+- 사용자: 네이버지도와 카카오맵 링크로 최종 확인
+
+핵심 원칙은 단순합니다. 모르면 추측하지 않고, API가 준 것만 말합니다.
+
+개발 과정, 시행착오, 현재 한계, 다음 개선 방향은 [open-gil Development Story](https://github.com/doul735/open_tools/blob/main/docs/open-gil-development-story.md)에 정리되어 있습니다.
+
+## Quick Start
+
+Until the first PyPI release is live, install from this repository:
+
+```bash
+pipx install "git+https://github.com/doul735/open_tools.git#subdirectory=packages/open-gil"
+```
+
+After PyPI release:
+
+```bash
+pipx install open-gil
+```
+
+Configure your TMAP key:
+
+```bash
+open-gil config set-key
+```
+
+그 다음 바로 물어볼 수 있습니다.
+
+```bash
+open-gil plan \
+  --origin "송도달빛축제공원역" \
+  --destination "올림픽공원 올림픽홀" \
+  --event-at "2026-06-06 13:00"
+```
+
+`--event-at`은 일정 시작 시각입니다. open-gil은 기본적으로 15분 전 도착을 목표로 출발시각을 추천합니다.
+
+## What You Get
+
+하루 10회 수준의 낮은 API 호출 제한을 고려해, 기본 모드는 TMAP 경로 조회 1회로 총 소요시간을 받아 목표 도착시각에서 출발시각을 역산합니다.
+
+이 방식은 API 호출을 아끼지만, “가장 늦은 출발”과 “이전/다음 수단”을 전수 검증하지는 않습니다. TMAP에 도착시각 기준 검색이 별도로 제공되지 않는 한, 그 기능은 여러 출발시각을 반복 조회해야 하므로 기본 MVP에서는 실행하지 않습니다.
+
+예시 출력은 이런 형태입니다.
+
+```text
+송도달빛축제공원역 -> 올림픽공원 올림픽홀
+기준: 2026-06-06 13:00 일정 시작, 목표 도착 2026-06-06 12:45
+
+추천: 2026-06-06 11:29 출발 -> 2026-06-06 12:45 도착 / 소요 1시간 16분 / 목표 도착 가능
+  경로: 도보 -> 지하철 인천1호선 -> 지하철 7호선 -> 도보
+
+추천 경로 상세
+- 도보: 출발지 -> 송도달빛축제공원역
+- 버스 광역:M6450: 송도달빛축제공원역 승차 -> 선릉역 하차
+- 같은 정류장 환승: 선릉역에서 버스 광역:M6450 하차 후 버스 간선:360 탑승
+- 버스 간선:360: 선릉역 승차 -> 잠실트리지움아파트앞 하차
+- 같은 정류장 환승: 잠실트리지움아파트앞에서 버스 간선:360 하차 후 버스 지선:3323 탑승
+- 버스 지선:3323: 잠실트리지움아파트앞 승차 -> 올림픽베어스타운아파트앞 하차
+- 도보: 올림픽베어스타운아파트앞 -> 올림픽홀
+
+탐색 방식: 하루 호출 제한을 고려해 TMAP 경로 조회 1회로 총 소요시간을 받아 목표 도착시각에서 역산했습니다. 이전/다음 수단 전수 탐색은 실행하지 않았습니다.
+
+확인 링크
+지도앱은 같은 출발/도착 좌표로 다시 길찾기하므로 위 TMAP 경로와 다를 수 있습니다.
+- 네이버지도: nmap://route/public?...
+- 카카오맵: http://m.map.kakao.com/scheme/route?...
+
+TMAP API 응답 기준입니다. 현장 지연, 운행 중단, 행사장 혼잡은 실제와 다를 수 있습니다.
+```
+
+위 출력은 형식 예시입니다. 실제 시간과 경로는 실행 시점의 TMAP API 응답에 따라 달라집니다.
+
+## Time Modes
+
+세 가지 시간 의도를 명확히 나눕니다.
+
+```bash
+# 일정 시작 시각. 15분 전 도착 목표.
+open-gil plan --origin "강남역" --destination "서울역" --event-at "2026-06-06 19:00"
+
+# 특정 시각까지 도착. 추가 버퍼 없음.
+open-gil plan --origin "강남역" --destination "서울역" --arrive-by "2026-06-06 18:30"
+
+# 특정 시각에 출발.
+open-gil plan --origin "강남역" --destination "서울역" --depart-at "2026-06-06 09:00"
+```
+
+날짜 없이 `09:00`처럼 입력하면 직접 CLI 사용에서는 오늘 날짜로 해석합니다. LLM 스킬 흐름에서는 날짜를 사용자에게 확인해야 합니다.
+
+## JSON for Agents
+
+Codex나 Claude Code 같은 에이전트는 JSON을 쓰는 편이 안전합니다.
+
+```bash
+cat <<'JSON' | open-gil plan --json
+{
+  "origin": {"name": "송도달빛축제공원역"},
+  "destination": {"name": "올림픽공원 올림픽홀"},
+  "event_at": "2026-06-06 13:00"
+}
+JSON
+```
+
+성공 응답은 항상 envelope 형태입니다.
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "time_mode": "event_at",
+    "arrival_buffer_minutes": 15,
+    "search_strategy": "quota_safe_target_arrival_single_lookup",
+    "route_api_calls_used": 1,
+    "candidates": []
+  }
+}
+```
+
+오류도 구조화됩니다.
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "OPEN_GIL_AUTH_INVALID",
+    "message": "TMAP API 키가 유효하지 않습니다.",
+    "remediation": "TMAP_API_KEY 값 또는 open-gil config set-key로 저장한 키를 확인하세요."
+  }
+}
+```
+
+장소 후보가 애매하면 `OPEN_GIL_PLACE_AMBIGUOUS`와 후보 목록을 반환합니다. 에이전트는 이때 임의로 고르지 말고 사용자에게 선택을 물어야 합니다.
+
+403 Forbidden처럼 키는 전달됐지만 호출 권한이 거절되면 `OPEN_GIL_AUTH_FORBIDDEN`으로 반환합니다. 이 경우 TMAP 앱키에 해당 API 상품/권한이 활성화되어 있는지, 요금제/도메인/IP 제한이 있는지 확인해야 합니다.
+
+호출 한도 초과는 `OPEN_GIL_QUOTA_EXCEEDED`로 반환합니다. 이 경우 자동 재시도하지 말고 TMAP 한도 초기화나 요금제/쿼터를 확인해야 합니다.
+
+## Natural-Language Agent Flow
+
+`$open-gil` 같은 에이전트 스킬은 자연어를 구조화한 뒤 CLI를 호출합니다.
+
+정확한 상태는 다음과 같습니다.
+
+- 장소명 검색과 경로 계산이 모두 성공하면 그대로 답변합니다.
+- TMAP POI 장소명 검색이 `OPEN_GIL_AUTH_FORBIDDEN`, `OPEN_GIL_PLACE_NOT_FOUND`, `OPEN_GIL_QUOTA_EXCEEDED`로 실패하고 `KAKAO_REST_API_KEY`가 있으면 Kakao Local 주소/키워드 검색으로 좌표를 보조 확인합니다.
+- 좌표가 확정되면 `open-gil plan --json`을 좌표 입력으로 다시 실행합니다. 이때 경로, 출발시각, 요금, 환승 정보는 TMAP Transit API 결과만 사용합니다.
+- Kakao Local 후보가 애매하거나 민감한 장소면 에이전트가 임의로 고르지 않고 사용자에게 선택 또는 좌표 제공을 요청해야 합니다.
+- TMAP Transit API 자체가 권한 오류, 한도 초과, 경로 없음으로 실패하면 경로 계산은 불가능합니다.
+
+즉 “자연어 스킬”은 좌표가 확정되고 Transit API가 성공하면 동작합니다. Kakao Local은 좌표화 fallback일 뿐이며, 경로 계산 source of truth는 항상 TMAP Transit API입니다.
+
+## Coordinates
+
+이미 장소를 확정했다면 좌표를 직접 넣을 수 있습니다. 좌표가 있으면 장소명 검색보다 우선합니다.
+
+```bash
+open-gil plan \
+  --origin-lat 37.407722 --origin-lon 126.625572 --origin-label "송도달빛축제공원역" \
+  --destination-lat 37.516289 --destination-lon 127.117314 --destination-label "올림픽홀" \
+  --event-at "2026-06-06 13:00"
+```
+
+## API Keys
+
+TMAP API 키는 필수입니다.
+
+1. SK Open API에서 앱을 만들고 appKey를 발급합니다.
+2. TMAP 대중교통 API와 POI 검색 API 사용 권한을 확인합니다.
+3. 환경변수나 로컬 설정 파일로 키를 설정합니다.
+
+환경변수가 우선입니다.
+
+```bash
+export TMAP_API_KEY="발급받은_appKey"
+```
+
+로컬 파일에 저장할 수도 있습니다.
+
+```bash
+open-gil config set-key
+```
+
+Kakao Local fallback은 선택이지만 자연어 장소명 품질을 크게 올립니다. Kakao Developers에서 REST API 키를 발급하고 Local API 사용을 확인한 뒤 설정합니다.
+
+```bash
+export KAKAO_REST_API_KEY="발급받은_REST_API_key"
+```
+
+또는 로컬 파일에 저장합니다.
+
+```bash
+open-gil config set-kakao-key
+```
+
+설정 파일은 `~/.config/open-gil/config.json`에 평문으로 저장됩니다. POSIX 환경에서는 `0600` 권한으로 맞춥니다.
+
+공식 문서:
+
+- TMAP 대중교통 API: https://transit.tmapmobility.com/docs/routes
+- TMAP POI 검색 API: https://tmap-skopenapi.readme.io/reference/%EC%9E%A5%EC%86%8C%ED%86%B5%ED%95%A9%EA%B2%80%EC%83%89
+- Kakao Local API: https://developers.kakao.com/docs/latest/ko/local/dev-guide
+- NAVER Maps URL Scheme: https://guide.ncloud-docs.com/docs/en/maps-url-scheme
+- KakaoMap URL Scheme: https://apis.map.kakao.com/ios_v2/docs/getting-started/urlscheme/
+
+## Install from Source
+
+```bash
+git clone https://github.com/doul735/open_tools.git
+cd open_tools
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e "./packages/open-gil[dev]"
+```
+
+## Tests
+
+기본 테스트는 fixture/mock 기반이라 API 키가 없어도 실행됩니다.
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 python -m pytest packages/open-gil/tests -p no:cacheprovider
+```
+
+실제 TMAP API 테스트는 `TMAP_API_KEY`가 있을 때만 실행됩니다.
+
+```bash
+export TMAP_API_KEY="발급받은_appKey"
+PYTHONDONTWRITEBYTECODE=1 python -m pytest packages/open-gil/tests/test_live_tmap.py -p no:cacheprovider
+```
+
+## Release Prep
+
+이 저장소는 GitHub Actions CI와 PyPI Trusted Publishing용 워크플로를 포함합니다.
+
+- CI: `.github/workflows/ci.yml`
+- PyPI publish: `.github/workflows/publish.yml`
+- Dependabot: `.github/dependabot.yml`
+
+로컬 배포 산출물 검증:
+
+```bash
+python -m pip install -e "./packages/open-gil[dev]"
+python -m build packages/open-gil
+```
+
+PyPI에 실제 배포하려면 PyPI에서 Trusted Publisher를 이 저장소와 `publish.yml` 워크플로에 연결하세요.
+
+Pending publisher 값:
+
+```text
+Project name: open-gil
+Owner: doul735
+Repository name: open_tools
+Workflow name: publish.yml
+Environment name: pypi
+```
+
+## Limits
+
+- 현재 MVP 범위는 서울, 경기, 인천입니다.
+- 계산 근거는 TMAP 대중교통 API입니다.
+- 목표 도착 모드는 기본적으로 경로 조회 1회로 출발시각을 역산합니다. 낮은 호출 제한 때문에 이전/추천/다음 수단 전수 탐색은 기본 제공하지 않습니다.
+- 네이버지도와 카카오맵 링크는 확인용이며 계산 근거가 아닙니다.
+- 네이버지도와 카카오맵 링크는 같은 출발/도착 좌표로 앱 자체 길찾기를 다시 실행하므로 TMAP 추천 경로와 다를 수 있습니다.
+- 별도 실시간 지연, 운행 중단, 행사장 혼잡 정보를 보장하지 않습니다.
+- 원문 자연어 프롬프트는 외부 API로 보내거나 캐시하지 않습니다.

open_gil-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "open-gil"
+version = "0.1.0"
+description = "API-backed public transit departure planner for Seoul, Gyeonggi, and Incheon."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "open-gil contributors" }]
+keywords = ["transit", "tmap", "cli", "korea", "route-planning"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "Natural Language :: Korean",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "typer>=0.12",
+  "httpx>=0.27",
+  "pydantic>=2.7",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build>=1.2"]
+
+[project.scripts]
+open-gil = "open_gil.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/doul735/open_tools"
+Repository = "https://github.com/doul735/open_tools"
+Issues = "https://github.com/doul735/open_tools/issues"
+Changelog = "https://github.com/doul735/open_tools/blob/main/packages/open-gil/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"