聖地巡礼 Seichijunrei

AI-powered pilgrimage search and route planning for anime sacred sites

Try it live | Architecture | Deployment

English | 日本語 | 中文

---

Tell the agent an anime title or a location in natural language. It finds real-world pilgrimage spots, shows them on a map, and plans a walking route — all in one conversational turn.

How It Works

User text  →  PydanticAI Agent (pilgrimage_agent)
                 ├── resolve_anime  → DB-first title lookup; Bangumi.tv API on miss
                 ├── search_bangumi → parameterized SQL → Supabase points
                 ├── search_nearby  → PostGIS geo retrieval
                 ├── plan_route     → nearest-neighbor route ordering
                 └── answer_question → QA pass-through
              → AgentResult (typed output + tool call records)

A single PydanticAI agent handles planning and tool dispatch. Tools use ModelRetry guards to reject invalid parameters, and an output_validator rejects fabricated responses. Selected-point routes bypass the agent entirely.

resolve_anime is self-evolving: on first query for an unknown title it fetches metadata from Bangumi.tv, upserts it into the database, and all future queries hit the local DB.

Features

• Conversational search — ask in Japanese, English, or Chinese; the agent handles intent
• Self-evolving anime catalog — DB-first with Bangumi.tv API write-through on miss
• Geo retrieval — find pilgrimage spots near any coordinate or station name
• Route planning — nearest-neighbor ordering with optional user-selected points
• Generative UI — three-column layout with chat panel + interactive result panel
• Edge auth — JWT (magic-link) and API key auth enforced at Cloudflare Worker
• Eval harness — 50+ plan-quality cases across 3 locales via pydantic_evals

Quick Start

# Install Python dependencies
uv sync --extra dev

# Run the service locally
make serve

# Run tests
make test              # unit tests
make test-integration  # stable acceptance tests
make test-all          # unit + integration
make test-eval         # model-backed evals (needs LLM access)
make check             # lint + typecheck + test

Database Migrations

Uses the Supabase CLI for all schema changes:

make db-list           # list applied migrations
make db-push-dry       # dry-run migration
make db-push           # apply migrations
make db-diff NAME=x    # generate diff from local changes

Apply migrations in a dedicated deploy step, not at application startup.

Environment

Required:

Variable	Purpose
SUPABASE_DB_URL	Postgres connection string
SUPABASE_URL	Supabase project URL
SUPABASE_SERVICE_ROLE_KEY	Server-side Supabase auth
SUPABASE_ANON_KEY	JWT validation at Worker edge
ANITABI_API_URL	Anitabi pilgrimage data API
GEMINI_API_KEY	LLM for planner agent

Optional: SERVICE_HOST, SERVICE_PORT, OBSERVABILITY_*, DEFAULT_AGENT_MODEL

See agent/config/settings.py for full reference and .env.example for defaults.

Example Usage

Python (direct):

from agent.agents.pilgrimage_runner import run_pilgrimage_agent
from agent.infrastructure.supabase.client import SupabaseClient

async def main() -> None:
    async with SupabaseClient(db_url) as db:
        result = await run_pilgrimage_agent("吹響ユーフォニアムの聖地", db, locale="ja")
        print(result.output)

HTTP (API key):

curl -X POST https://seichijunrei.zhenjia.dev/v1/runtime \
  -H 'Authorization: Bearer sk_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"text":"吹響の聖地","locale":"ja"}'

Python client:

from agent.clients.python.seichijunrei_client import SeichijunreiClient

client = SeichijunreiClient(api_key="sk_your_key_here")
result = client.search("Hibike Euphonium locations", locale="en")

Repository Map

• agent/ — Python runtime: agents, interfaces, infrastructure, tests, and tools
• frontend/ — Next.js static-export frontend and UI components
• worker/ — Cloudflare Worker entrypoint for auth and request routing
• supabase/ — schema migrations and Supabase project assets
• docs/ — architecture, ops runbooks, iteration artifacts, and implementation plans
• Dockerfile, Makefile, pyproject.toml, wrangler.toml, package.json — root runtime and tooling entrypoints that stay at the repository root

Docs

• Architecture — full system design reference
• Deployment — Cloudflare Workers + Containers deploy guide
• Ops docs — operational runbooks and environment procedures
• Iteration artifacts — task plans, progress logs, and findings by iteration
• Implementation plans — implementation plans kept in place for execution history
• Design spec — product specification