koreaapi 0.1.0__tar.gz

koreaapi-0.1.0/.env.example

@@ -0,0 +1,32 @@
+# --- LLM (extraction / translation / verification) ---
+ANTHROPIC_API_KEY=
+
+# --- Sources (official APIs first; scraping is last-resort) ---
+SPOTIFY_CLIENT_ID=
+SPOTIFY_CLIENT_SECRET=
+YOUTUBE_API_KEY=
+
+# --- Append-only store ---
+KOREAAPI_DB=koreaapi.db            # dev SQLite path (default); used by admin / pull / export
+DATABASE_URL=                      # Postgres (production scale); same insert-only contract
+
+# --- Commerce rails (engine 1; cold-start optional; commission is a later switch) ---
+SKIMLINKS_PUBLISHER_ID=
+AMAZON_ASSOCIATES_TAG=
+
+# --- Trend digest (engine 2; "Korea Rising" newsletter) ---
+BEEHIIV_API_KEY=
+BEEHIIV_PUBLICATION_ID=
+
+# --- Phase 2: agent payments (x402 / USDC) — wire only when traffic qualifies ---
+CDP_API_KEY_ID=                    # Coinbase Developer Platform (x402 facilitator)
+CDP_API_KEY_SECRET=
+KOREAAPI_PAYOUT_ADDRESS=           # USDC receiving address (Base). Not "receive BNB"; no token.
+
+# --- Accounts & keys shopping list: docs/API_KEYS.md ---
+
+# --- Collection cadence (seconds; see src/koreaapi/pipeline/scheduler.py) ---
+CADENCE_CHARTS_SEC=43200
+CADENCE_EVENTS_SEC=86400
+
+LOG_LEVEL=INFO

koreaapi-0.1.0/.github/workflows/collect.yml

@@ -0,0 +1,57 @@
+# KoreaAPI daily collector — the cold-start data engine.
+# Runs the live Wikidata pull + cross-verify + exports the growing data asset, then commits
+# data/ back to the repo. GitHub's runners have open network access, so the live pull works
+# here. Manual run: Actions tab -> "collect" -> Run workflow. The daily schedule is active
+# once this file is on the default branch (main).
+name: collect
+
+on:
+  workflow_dispatch: {}
+  schedule:
+    - cron: "17 0 * * *" # daily ~00:17 UTC
+
+permissions:
+  contents: write
+
+concurrency:
+  group: koreaapi-collect
+  cancel-in-progress: false
+
+jobs:
+  collect:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv (Python env)
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install deps
+        run: uv sync
+
+      - name: Pull live Wikidata + export the data asset
+        env:
+          PYTHONPATH: src
+          KOREAAPI_DB: ${{ runner.temp }}/koreaapi.db # fresh per run; history lives in data/
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} # romanization + Circle Chart extract (best-effort; skipped if unset)
+          YOUTUBE_API_KEY: ${{ secrets.YOUTUBE_API_KEY }} # official-channel release snapshots (best-effort; skipped if unset)
+        run: |
+          uv run python -m koreaapi.admin pull
+          uv run python -m koreaapi.admin sweep
+          uv run python -m koreaapi.admin chart
+          uv run python -m koreaapi.admin youtube
+          uv run python -m koreaapi.admin export
+          uv run python -m koreaapi.admin digest
+          uv run python -m koreaapi.admin stats
+
+      - name: Commit accumulated data
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add data
+          if git diff --cached --quiet; then
+            echo "no data change"
+          else
+            git commit -m "data: daily Wikidata snapshot [skip ci]"
+            git push
+          fi

koreaapi-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,68 @@
+# Public GEO page (answer-engine-crawlable) on GitHub Pages.
+# Builds report.html + monitor.html from LIVE data (the pull runs on GitHub's open-network
+# runner) and deploys to GitHub Pages — a free, public, JSON-LD-bearing URL that
+# Perplexity / ChatGPT / Google AI Overviews can crawl and cite.
+#
+# ONE-TIME ENABLE: repo Settings -> Pages -> Build and deployment -> Source: "GitHub Actions".
+name: pages
+
+on:
+  workflow_dispatch: {}
+  push:
+    branches: [main]
+  schedule:
+    - cron: "37 1 * * *" # daily, after the collect job
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv (Python env)
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build the public GEO page from live data
+        env:
+          PYTHONPATH: src
+          KOREAAPI_DB: ${{ runner.temp }}/koreaapi.db
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} # romanization + Circle Chart extract (best-effort; skipped if unset)
+          YOUTUBE_API_KEY: ${{ secrets.YOUTUBE_API_KEY }} # official-channel release snapshots (best-effort; skipped if unset)
+        run: |
+          uv sync
+          uv run python -m koreaapi.admin pull
+          uv run python -m koreaapi.admin sweep
+          uv run python -m koreaapi.admin chart
+          uv run python -m koreaapi.admin youtube
+          uv run python -m koreaapi.admin report
+          uv run python -m koreaapi.admin entitypages
+          uv run python -m koreaapi.admin digest
+          uv run python -m koreaapi.admin monitor
+          uv run python -m koreaapi.admin export
+          mkdir -p _site
+          cp report.html _site/index.html
+          cp monitor.html _site/monitor.html   # human data-quality cockpit at /monitor.html
+          cp llms.txt _site/llms.txt   # agent-discoverable at /llms.txt (AEO/GEO)
+          cp data/korea-rising.md _site/korea-rising.md   # shareable verified digest
+          cp data/latest.json _site/latest.json   # open machine-readable verified data
+          cp robots.txt _site/robots.txt   # explicitly welcome answer-engine crawlers (AEO)
+          cp -r site/artist _site/artist   # per-entity citable answer pages (/artist/<slug>.html)
+          uv run python -m koreaapi.admin sitemap   # sitemap.xml incl. every entity page (daily lastmod)
+          cp sitemap.xml _site/sitemap.xml
+
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3 # publishes ./_site by default
+      - id: deploy
+        uses: actions/deploy-pages@v4

koreaapi-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+# Publish koreaapi to PyPI — no local tools needed.
+# Trigger: Actions -> "publish" -> Run workflow  (or publish a GitHub Release).
+# Requires a repo secret PYPI_API_TOKEN (pypi.org -> Account settings -> API tokens).
+name: publish
+
+on:
+  workflow_dispatch: {}
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}

koreaapi-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,26 @@
+# koreaapi CI — run the test suite + linter on every push and PR.
+# On GitHub's open-network runners the live smoke tests actually exercise Wikidata/Wikipedia
+# (they auto-skip only on transient network failure), so this gates both offline correctness
+# and the live adapters.
+name: test
+
+on:
+  workflow_dispatch: {}
+  push:
+    branches: [main]
+  pull_request: {}
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra dev
+      - name: Lint
+        run: uv run ruff check src tests
+      - name: Test
+        run: uv run pytest -q

koreaapi-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+.env.local
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+*.db
+report.html
+monitor.html
+sitemap.xml
+site/

koreaapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kwangdol-star
+
+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.

koreaapi-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: koreaapi
+Version: 0.1.0
+Summary: The verifiable data layer for Korean culture & commerce, callable by any AI agent (MCP).
+Project-URL: Homepage, https://kwangdol-star.github.io/koreaapi/
+Project-URL: Repository, https://github.com/kwangdol-star/koreaapi
+Project-URL: Open data (JSON), https://kwangdol-star.github.io/koreaapi/latest.json
+Author: kwangdol-star
+License: MIT
+License-File: LICENSE
+Keywords: aeo,ai-agents,geo,kculture,korea,kpop,mcp,model-context-protocol,verifiable-data,wikidata
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: anthropic
+Requires-Dist: fastmcp
+Requires-Dist: httpx
+Requires-Dist: pydantic>=2
+Requires-Dist: python-dotenv
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# KoreaAPI
+
+**The verifiable data layer for Korean culture & commerce, callable by any AI agent.**
+*The MCP gateway to Korea — verifiable.*
+
+KoreaAPI exposes Korean culture, entertainment, and commerce data to AI agents via
+Anthropic's Model Context Protocol (MCP). Every response carries machine-readable
+**provenance** and a **Skill Score** so an agent can decide whether to trust and cite it.
+
+> **Status:** Phase 1 (cold-start). The locked spec is in [`SCOPE.md`](./SCOPE.md); what is
+> built / decided and why is in [`ROADMAP.md`](./ROADMAP.md).
+> **Live, verified, public data (Schema.org JSON-LD + `/llms.txt`):**
+> **https://kwangdol-star.github.io/koreaapi/**
+> **Repository:** [`kwangdol-star/koreaapi`](https://github.com/kwangdol-star/koreaapi) — a
+> standalone repo, split out from its incubation home with full git history preserved.
+
+## What's live now (verified, on the public page + via MCP)
+- **Cross-verification** — Wikidata + Wikipedia must agree on the canonical bilingual name
+  before a fact clears the single-source cap (high Skill Score = independent concurrence).
+- **Identity guard** (rejects a contradictory label) + **hallucination guard** (LLM-extracted
+  data must appear verbatim in its source, else dropped — caught a fabricated chart entry live).
+- **소속사/Agency hub** — each artist anchored to its label (Wikidata P264); the roster grows by
+  discovering cross-verified **labelmates** (SPARQL) and is queryable via `get_agency`.
+- **YouTube** official-channel release/stats (live-state) · **LLM romanization** at ingest.
+- **GEO/AEO** — JSON-LD (incl. `recordLabel`) + a ready-to-cite line on every record + `/llms.txt`.
+
+## Why this exists
+Raw Korean API wrappers are a commodity (20+ already exist on GitHub). Our moat is the
+combination nobody else ships:
+
+- **Aggregation** of fragmented K-culture / commerce sources
+- **Verification** — Skill Score + provenance, exactly where LLMs confidently hallucinate
+- **Append-only time-series** — a latecomer cannot reconstruct our history
+- **Behavioral signal** — what agents query / buy through us becomes trend data
+
+The customer is the **AI agent** (consumer); humans / brands / enterprises pay.
+
+## Why now — the land-grab window
+The compounding assets accrue to **early, high-quality** entrants: only ~13% of public MCP
+servers are high-trust, and AI answer engines concentrate citations on content **refreshed in the
+last 1–3 years** (Seer Interactive). A verified hub that re-verifies **daily** compounds a citation
+lead latecomers can't backfill. We are **"picks-and-shovels"** — the data agents consume, not a
+chat wrapper (a category the same market analyses find largely fails to monetize). *(An independent 2026 AI-agent
+opportunity ranking places this exact model at its top — see [`ROADMAP.md`](./ROADMAP.md).)*
+
+## Revenue flywheel (engines ① + ②)
+K-culture current-state is the magnet. ① commerce commission + ② trend-intelligence
+subscription reinforce each other: transactions generate the behavioral signal that
+becomes the trend product, which improves commerce conversion. See [`SCOPE.md`](./SCOPE.md) §3.
+
+## The heart: append-only ingestion (component A)
+```
+fetch → LLM-extract → cross-verify → bilingual-normalize → append (+ Skill Score)
+```
+**Overwrite = wrapper. Append timestamped snapshots = an asset.**
+
+## Bilingual by design
+Korean = canonical (provenance anchor). English = distribution layer.
+Names carry `ko` / `en_official` / `romanized`. See [`SCOPE.md`](./SCOPE.md) §5.
+
+## Layout
+```
+koreaapi/
+├── SCOPE.md                 # locked Phase 1 spec
+├── llms.txt                 # agent-facing description
+├── pyproject.toml
+└── src/koreaapi/
+    ├── models.py            # bilingual records + Provenance (the data contract)
+    ├── skill_score.py       # transparent 0–1 quality score
+    ├── pipeline/            # component A: append-only ingestion (the heart)
+    │   ├── ingest.py        # fetch→extract→verify→translate→append
+    │   ├── store.py         # APPEND-ONLY store (the moat)
+    │   └── scheduler.py     # tiered collection cadence
+    └── sources/             # source adapters (official APIs first)
+        └── base.py
+```
+
+## Dev
+```bash
+cd koreaapi
+uv sync                      # or: pip install pydantic pytest
+
+# run the offline end-to-end pipeline test (no API keys / network needed)
+PYTHONPATH=src python -m pytest tests -q
+```
+
+The append-only ingestion heart (store + ingest + Skill Score + bilingual normalization) is
+implemented and **tested offline** via a `MockSource`. Real source adapters, all with pure
+fixture-tested parse steps + best-effort live fetch (graceful when egress/keys are absent):
+
+- **Wikidata** (#1) — bilingual labels via a curated entity→Q-id fast path (each anchor's
+  identity verified, so a contradictory label is **rejected, not ingested**) + live
+  `wbsearchentities`. Also pulls the **소속사/label** (P264) and discovers **labelmates** (SPARQL).
+- **Wikipedia** (#2) — independent cross-check; when both agree on the bilingual name the Skill
+  Score clears the single-source cap (the verification moat).
+- **YouTube Data API** (#3.5) — official-channel stats + latest release (live-state event data),
+  identity-guarded; deliberately *not* a name cross-verifier.
+- **Circle Chart** (#3) — official chart, LLM-extracted **with an anti-hallucination grounding
+  guard** (entries must appear verbatim in the page HTML). The page is JS-rendered, so the raw
+  chart awaits a data endpoint; the guard ensures it ships *nothing* over anything false.
+- **LLM romanization** (Haiku) fills `romanized` at ingest — "cheap AI as collection labor".
+
+Spotify is **skipped** (its Web API now requires Premium, 2026); a keyless EN-mostly source
+would only lower the cross-verified scores. See [`ROADMAP.md`](./ROADMAP.md) for the full log.
+
+> **Egress note:** the live pull needs outbound access to `*.wikidata.org`. In the
+> web/sandbox environment egress is allowlist-gated — if Wikidata isn't allowlisted the
+> live test skips (HTTP 403 `host_not_allowed`) while the offline parser tests still
+> cover correctness.
+
+## Viewing & managing it (human console)
+The product is agent-facing (MCP), but you (human) need a cockpit. There are
+**two faces over one source of truth** (the append-only store): the MCP server for
+agents, and a read-only console for you.
+
+```bash
+cd koreaapi
+PYTHONPATH=src python -m koreaapi.admin seed     # populate koreaapi.db (offline sample)
+PYTHONPATH=src python -m koreaapi.admin pull     # LIVE: Wikidata+Wikipedia cross-verified snapshots (+agency)
+PYTHONPATH=src python -m koreaapi.admin sweep    # LIVE: discover labelmates from each anchored agency (SPARQL)
+PYTHONPATH=src python -m koreaapi.admin youtube  # LIVE: official-channel release snapshots (needs YOUTUBE_API_KEY)
+PYTHONPATH=src python -m koreaapi.admin chart    # LIVE: Circle Chart (LLM-extract, grounding-guarded; needs key)
+PYTHONPATH=src python -m koreaapi.admin export   # write data/ asset (history + latest.json)
+PYTHONPATH=src python -m koreaapi.admin signals  # top behavioral signals (engine 2: what agents query)
+PYTHONPATH=src python -m koreaapi.admin stats    # data-quality summary
+PYTHONPATH=src python -m koreaapi.admin dump     # print recent snapshots
+PYTHONPATH=src python -m koreaapi.admin report   # -> report.html (open in a browser)
+
+# zero-code interactive browse + query + JSON API over the same DB:
+pip install datasette && datasette koreaapi.db
+```
+
+**Automated collection (cron).** `.github/workflows/collect.yml` runs `admin pull` +
+`admin export` daily (and on manual dispatch) and commits the growing data asset back to
+the repo: `koreaapi/data/snapshots.jsonl` (append-only history) + `latest.json` (current
+state, crawlable for GEO). It runs on GitHub's runners — **open network, so the live pull
+works there** even though the dev sandbox blocks Wikidata egress. Production scales this to
+Postgres behind the same insert-only contract (see `pipeline/store.py`); the repo file set
+is the zero-cost cold-start "database".
+
+**Public GEO page.** `.github/workflows/pages.yml` builds `report.html` from live data and
+deploys it to GitHub Pages (one-time enable: Settings → Pages → Source: GitHub Actions) — a
+public, crawlable, JSON-LD-bearing URL so answer engines can surface and cite the verified data.
+
+Watch the headline metric of a verifiable-data business: **avg Skill Score,
+freshness, and source agreement** - that is literally watching the moat.
+
+## Agent face (MCP server)
+The product itself: an MCP server exposing 5 tools, each returning verified, bilingual,
+provenance-bearing data (with a ready-to-cite line) from the same store the console reads.
+
+| Tool | Returns |
+|---|---|
+| `get_artist_status(artist_id)` | latest status across kinds + verified facts + agency |
+| `get_kculture_calendar(window_days)` | upcoming comebacks / releases / concerts |
+| `get_agency(name)` | artists verified under a 소속사/label (the agency hub) |
+| `get_korea_rising(category, limit)` | what's rising now, ranked by observed demand + Skill Score |
+| `get_buy_options(item)` | where to buy (Phase 1: rail pending; logs buy-intent) |
+
+```bash
+cd koreaapi
+pip install fastmcp                           # use a venv if system deps clash
+PYTHONPATH=src python -m koreaapi.server      # serves over MCP (stdio)
+```
+
+Logic lives in `service.py` (pure, offline-tested); `server.py` is the thin MCP
+binding. Tools register cleanly (verified in an isolated venv).
+
+**Install / connect it in your agent:** see [`docs/MCP_INSTALL.md`](./docs/MCP_INSTALL.md)
+(run command, Claude-Desktop config, and [`smithery.yaml`](./smithery.yaml) for the Smithery registry).

koreaapi-0.1.0/PRINCIPLES.md

@@ -0,0 +1,54 @@
+# KoreaAPI — North Star & Durability Principles
+
+> The load-bearing doctrine. Every design and build decision is checked against this.
+
+## North star
+Accumulate — faster and more verifiably than anyone in the world — the **live state of
+Korean culture & commerce**, using cheap AI as the collection labor, and monetize the
+**transactions and trust** that flow through it.
+
+**Hard requirement: the model must keep making money as AI models get *better*, not worse.**
+
+## Why this gets STRONGER as AI advances
+The bottleneck of the AI era is shifting from *intelligence* (becoming abundant and
+cheap) to *trustworthy real-world input + the right to act* (scarce). We own the scarce
+complement for Korea. Better models feed us; they do not erode us.
+
+| As AI models advance... | Effect on us |
+|---|---|
+| Training cutoff can't hold live state | Agents need fresh feeds → **demand ↑** |
+| Smarter models hallucinate more *plausibly* | Verifiable ground truth + provenance worth **more**, not less |
+| Our append-only history was never in any training set | **Un-reconstructable**; compounds daily |
+| Behavioral signal is generated by usage | Exclusive, never trainable; grows with adoption |
+| Agents recommend & transact more confidently | More volume through our **commission rail** |
+| Extraction models get cheaper/better | Our **collection cost ↓** (the progress that helps rivals helps us first) |
+
+Demand ↑ + our cost ↓ + history compounding = the flywheel **accelerates** with model progress.
+
+## What we DO and DON'T build
+**DO (model-advancement-proof):**
+- Live / future state (calendars, charts, prices) — structurally outside any model
+- Verification: Skill Score + provenance on every record
+- Append-only history (never overwrite) — the un-reconstructable asset
+- Proprietary behavioral signal (what agents query / buy)
+- Transaction-attached monetization (commission) + data subscription
+
+**DON'T (eroded by better models):**
+- Static evergreen knowledge the model already has (generic encyclopedia)
+- Commodity raw data a browsing agent fetches itself (plain public-API wrapping)
+- Pure reformatting / translation as the *only* value (verification, not translation, is the value)
+
+## Design invariants (check every change against these)
+1. **Append, never overwrite.** History is the moat.
+2. **Every record carries provenance + Skill Score.** No unverifiable data ships.
+3. **Korean canonical, English distribution; official names over translation.**
+4. **Every new tool must add live-state, verification, or history value** — never just restate model-known facts.
+5. **Prefer transaction-attached revenue** (commission) over pure read fees.
+6. **Use cheap AI as collection labor;** collection cost should fall as models improve.
+7. **One source of truth, two faces** (agent MCP + human console) — never a second data path.
+
+## The main long-term risk (and the answer)
+Disintermediation by a model/platform building the Korean layer themselves. Answer:
+they build *horizontal intelligence*, not *vertical Korean ground truth*. We win by
+owning the **cited default + the transaction rail + the behavioral flywheel** inside the
+12–18 month window — before anyone bothers.