Ikigai

Most agents tell you what's happening. Ikigai tells you what it means — and why it conflicts.

RYO-CHAN Hackathon 2026 entry — an autonomous crypto market intelligence agent that detects when market signals contradict each other, resolves the conflict with visible reasoning, and publishes an honestly-graded public track record.

• Track 1 — Autonomous Agents: the flagship Ikigai agent (tick loop, conflict resolution, reasoning trails, public track record)
• Track 3 — New Skills: ConflictIQ + Pipeline Engine (stateless skill, callable by any agent)
• Track 2 — Dashboards & Interfaces: the signal terminal (same build, entered as submitted)

Practice decisions only. No real funds, ever. Every number comes from live RYO-CHAN research tools — nothing synthesized. Outcomes are graded against real price moves 24h later, including the agent's own INCORRECT calls.

Live: dashboard at / · private per-user agent at /app · MCP at /mcp

The demo story

Ikigai wakes up → scans market → detects SOL showing bullish RSI but Fear & Greed
deteriorating → ConflictIQ fires → auto-chains deep_analysis + compare_tokens →
conflict scored and resolved → agent reasons visibly → practice trade decision
with confidence score → logged to track record → pushed to Telegram, POSTed to
subscribed bots via webhook, served via MCP

Architecture

   GITHUB ACTIONS (cron, every 30 min)          VERCEL (serverless)
┌───────────────────────────────────┐    ┌──────────────────────────────────┐
│  Flagship agent tick:             │    │  Dashboard  GET /                │
│   RYO tools → ConflictIQ → LLM    │    │  REST  /signal/*, /track-record  │
│   reasoning → decision → grading  │    │  MCP   /mcp (real protocol)      │
└────────────────┬──────────────────┘    │  Private user app  GET /app      │
                 │ writes                └───────────────┬──────────────────┘
                 ▼                                       │ reads
        ┌────────────────────────────────────────────────┴──┐
        │   NEON POSTGRES — prod (flagship + all users)      │
        └────────────────────────────────────────────────────┘
                 ▲                                ▲
   your PC (optional local agent,   users anywhere (API keys, MCP clients,
   Telegram bot, deep-resolve runs) bot developers, dashboards)

One brain, many private instances

The flagship agent is public and accountable — its full reasoning and honestly-graded accuracy are on the dashboard. Individuals run their own private instances of the same brain without exposing anything:

| Step | How | |---|---| | Get an identity | POST /v1/users/register → personal iki_… API key (or one click at /app) | | Run YOUR agent | POST /v1/agent/run — one tick of your instance: your watched token, your reasoning, stored privately | | Your track record | GET /v1/my/track-record — outcomes graded for you, never mixed with anyone else | | Private ConflictIQ | POST /v1/conflictiq — your signals in, verdict out, nothing stored (stateless = private by construction) | | Self-conflict | include a decision_history signal — the detector flags when current evidence contradicts your own past stance or a decision that graded INCORRECT |

How ConflictIQ works

1. Detect — N tool outputs (not just pairs) go to the LLM with a strict JSON contract; it judges contradictions and scores severity. Three conflict classes: cross-signal, self-conflict (current evidence vs your own past), regime-vs-token. Detection is stateless and side-effect free.
2. Resolve (opt-in) — with auto_resolve: true, Ikigai grounds the token from the original envelopes, builds real RYO calls (deep_analysis, compare_tokens), executes the chain, then a second LLM role (the arbiter) weighs conflict + resolution into a verdict.
3. Explain — every step lands in a reasoning_trail, order preserved. The argument is inspectable.

How the Pipeline Engine works

ConflictIQ generalized: any RYO tool sequence with data flowing between steps, in pure JSON:

{
  "pipeline": [
    { "step": 1, "tool": "market_overview", "params": {} },
    { "step": 2, "tool": "scan_market", "params": { "theme": "DeFi", "top_n": 3 } },
    { "step": 3, "tool": "analyze_token", "params": { "symbol": "{{step2.candidates.0.symbol}}" } },
    { "step": 4, "tool": "conflictiq", "params": { "signals": ["{{step1}}", "{{step3}}"] } }
  ],
  "output": "{{step4}}"
}

{{stepN}} injects whole previous outputs; {{stepN.dot.path}} walks object keys and array indices (top scan candidate picked at runtime). Unresolved references fail loudly — never a silent None.

Channels — any consumer, human or machine

| Channel | Consumers | Access | |---|---|---| | MCP (/mcp, streamable HTTP + stdio wrapper) | Claude Desktop, any agent | public read tools + skill tools | | REST (/signal/latest, /signal/history, /track-record) | trading bots | public read | | Outbound webhooks (HMAC-SHA256 signed POST per decision) | PartBots, Impala, Alpaca bots | admin token to subscribe | | Telegram (anyone who /starts the bot gets decision pushes; /latest, /track, /watch TOKEN) | humans | bot token (ours) | | Dashboard (/) + private app (/app) | judges, users | public read / user API key |

MCP is pull, webhooks are push — together: any agent or bot can consume Ikigai.

Honest degradation & failure handling

• RYO timeouts / network errors → tool marked status: unavailable with warnings; tick continues. 90 s client timeout (deep tools observed at 36–45 s live).
• Rate limits (429) → capped backoff (max 2 retries), then explicit unavailable.
• Partial tool results → per-lane availability (token_profile: unavailable); lanes, not whole tools, are the failure unit.
• Outcome grading → never graded on missing price data; stays pending, retried next tick.
• Empty scans → guarded; tick returns no_candidates instead of crashing.
• LLM JSON drift → parse_llm_json tolerates fences/prose; strict response_format JSON mode where supported.
• Webhook/Telegram delivery failures → logged, never crash the tick.
• Tick crashes → safe_tick wraps the loop; failures logged, agent continues.
• prod/sandbox split → local test runs write sandbox/SQLite; the public track record is only written by the scheduled agent.

Track record & outcome grading

Decisions are graded 24 h later against a fresh analyze_token read (performance.change_24h_pct):

| Direction | CORRECT | INCORRECT | EXPIRED | |---|---|---|---| | LONG / SHORT | 24 h move beyond the dead zone in the decision's direction | move against it | move inside ±0.5 % | | HOLD / AVOID | |24 h move| < 3 % | |24 h move| ≥ 3 % | — |

Accuracy = correct / (correct + incorrect). Pending counts toward nothing. The public dashboard shows the flagship agent only; every user's record is private.

Quickstart

git clone <repo-url> && cd <repo>
python -m pip install -r requirements.txt
cp .env.example .env          # fill in keys — NEVER commit .env

python -m pytest tests/ -q    # 95 tests, no network needed
python main.py --once         # one full agent tick (needs RYO + LLM keys)
python init_db.py             # apply schema to Neon (idempotent)

python main.py                        # local agent: 30-min ticks + Telegram bot
IKIGAI_MODE=server python main.py     # server mode: dashboard + REST + MCP

Deploy (Vercel): vercel link --yes --project <name>, set env vars, vercel --prod. The scheduled tick runs on GitHub Actions (.github/workflows/tick.yml) — repo secrets: RYO_API_KEY, RYO_MCP_URL, DATABASE_URL, LLM_PROVIDER, LLM_API_KEY, LLM_MODEL, LLM_BASE_URL, LLM_JSON_MODE.

Individual user API (/v1, auth via X-Ikigai-Key header)

| Endpoint | Purpose | |---|---| | POST /v1/users/register | create identity, get API key (open during hackathon) | | POST /v1/agent/run | run one tick of your agent instance (deep_resolve: false fits serverless) | | GET /v1/my/decisions / GET /v1/my/track-record | your private history and accuracy | | GET/POST/DELETE /v1/my/watches | your watchlist (drives your instance's token selection) | | POST /v1/conflictiq | stateless ConflictIQ on your own signals — nothing stored | | POST /v1/pipeline/run | execute a custom RYO pipeline (logged, scoped to you) |

Model-agnostic LLM

LLM_PROVIDER = anthropic | openai | openrouter — or any OpenAI-compatible endpoint (Groq, Together, local vLLM) via LLM_BASE_URL. LLM_JSON_MODE=true requests strict response_format: json_object on compatible providers; parse_llm_json is the portable safety net.

Security

• Pre-commit guard blocks credential-shaped strings (ryo_mcp_*, sk-ant-*, hex keys)
• .env gitignored and never committed; .env.example documents every variable
• Public reads are read-only; writes require bearer token or user API key
• Webhook deliveries HMAC-SHA256 signed (X-Ikigai-Signature)
• prod/sandbox database separation; user data isolated by user_id scoping

Testing

python -m pytest tests/ -q    # 95 tests, no network required

Covers: RYO client, both LLM provider families, ConflictIQ flows, pipeline injection and failure modes, both storage backends, outcome grading, multi-tenancy and isolation, webhook signing, Telegram commands, agent ticks, API endpoints, MCP registration.

Submission

• Demo video: (< 3 min — link added before judging)
• X post: (@ryodigital — link added before judging)
• Project submission form: (PDF added before deadline)

Built for the RYO-CHAN Hackathon 2026. Powered by RYO-CHAN research tools — read-only, live market data, honest provenance.