gecko-surf 0.1.0__tar.gz

gecko_surf-0.1.0/.dockerignore

@@ -0,0 +1,19 @@
+# Keep the build context small and secrets out of the image (invariant #1).
+.git
+.venv
+__pycache__
+*.pyc
+.pytest_cache
+.mypy_cache
+.ruff_cache
+# secrets / local env — must never enter the image
+.env
+.env.*
+.env.tgbot
+private/
+# not needed at runtime
+tests/
+docs/
+.github/
+*.md
+!README.md

gecko_surf-0.1.0/.env.example

@@ -0,0 +1,287 @@
+# =============================================================================
+# Gecko — environment variables (gecko-api side)
+# =============================================================================
+#
+# Two consumers read this file:
+#
+# 1. Local dev: `uv run uvicorn gecko_api.main:app` reads from .env via
+#    set -a; source .env; set +a (Settings.from_env() reads os.environ).
+#
+# 2. Deploy: ./infra/push-ssm-params.sh maps each non-empty value into
+#    /gecko-api/<NAME> as a SecureString in AWS SSM. ECS tasks then read
+#    these via the `secrets:` block in the CloudFormation task definition.
+#
+# End users (Claude Code skill) never touch this file. Their wallet lives at
+# ~/.agentwallet/config.json (frames.ag) and gecko-mcp talks to the deployed
+# gecko-api at https://api.geckovision.tech — no local secrets needed.
+# =============================================================================
+
+# ---------------------------------------------------------------------------
+# Required — database + ingestion
+# ---------------------------------------------------------------------------
+SUPABASE_URL=
+SUPABASE_SERVICE_ROLE_KEY=
+TAVILY_API_KEY=
+OPENAI_API_KEY=
+
+# Optional — only needed for `tests/eval/runner.py --live`.
+# The eval harness uses Claude Sonnet 4.6 as the rubric judge (cross-family
+# scoring reduces same-family bias). Mock mode does not need this.
+ANTHROPIC_API_KEY=
+
+# ---------------------------------------------------------------------------
+# Required — LLM routing
+# ---------------------------------------------------------------------------
+# Two paths — pick one (uncomment the block):
+#
+# Path A: OpenAI direct (recommended for deploy until ClawRouter is hosted).
+#   GECKO_LLM_ENDPOINT=https://api.openai.com/v1
+#   GECKO_LLM_API_KEY=${OPENAI_API_KEY}
+#   CHAT_MODEL=gpt-4o-mini
+#
+# Path B: ClawRouter local proxy (v3 demo path; not viable on Fargate yet
+# unless we run ClawRouter as a sidecar — defer post-MVP).
+#   GECKO_LLM_ENDPOINT=http://localhost:8402/v1
+#   GECKO_LLM_API_KEY=x402
+#   CHAT_MODEL=openai/gpt-4o
+GECKO_LLM_ENDPOINT=https://api.openai.com/v1
+GECKO_LLM_API_KEY=
+CHAT_MODEL=gpt-4o-mini
+
+# ---------------------------------------------------------------------------
+# Pro tier — LLM routing (S1-01)
+# ---------------------------------------------------------------------------
+# Selects the OpenAI-compatible base URL the AG2 GroupChat hits. Per-agent
+# model strings come from `gecko_core.orchestration.pro.router.model_matrix`.
+#   openai      — direct api.openai.com (uses OPENAI_API_KEY)
+#   openrouter  — https://openrouter.ai/api/v1 (uses OPENROUTER_API_KEY)
+#   clawrouter  — http://localhost:8402/v1 (no auth; CLAWROUTER_URL overrides)
+LLM_ROUTER=openai
+# Required when LLM_ROUTER=openrouter. Ignored otherwise.
+OPENROUTER_API_KEY=
+# Optional — only used when LLM_ROUTER=clawrouter.
+# CLAWROUTER_URL=http://localhost:8402/v1
+
+# ---------------------------------------------------------------------------
+# Required — x402 payments (devnet ↔ mainnet via SSM, no code changes)
+# ---------------------------------------------------------------------------
+# Mode:
+#   stub  — local dev only; auto-settles, no real payment. NEVER deploy stub.
+#   live  — real facilitator + on-chain settlement.
+# x402 mode controls payment behavior:
+#   stub - synthetic receipts, no real USDC moved (DEFAULT for local dev)
+#   live - real Solana mainnet/devnet payments via x402 facilitator
+# Flip to `live` only after:
+#   1. Funding your client wallet with ~$1 SOL for gas
+#   2. Setting GECKO_WALLET_ADDRESS to a treasury YOU control
+#   3. Reading docs/test-plan.md → "Live-mode pre-flight"
+# For one-off live calls, prefer: X402_MODE=live <command> (override per-call)
+X402_MODE=stub
+
+# Network. Friendly names — devnet for testing, mainnet for production.
+# The CAIP-2 chain id, facilitator URL, and Solana cluster are all derived
+# from this value (see gecko_core.payments.networks). Legacy CAIP-2 form
+# (solana:EtW... / solana:5eyk...) is still accepted with a deprecation
+# warning so existing SSM values don't break across one deploy.
+X402_NETWORK=solana-devnet
+
+# x402 facilitator URL. OPTIONAL — defaults to the per-network value:
+#   solana-devnet  → https://www.x402.org/facilitator   (free, no auth)
+#   solana-mainnet → https://api.cdp.coinbase.com/platform/v2/x402  (CDP)
+# Set this only to override (e.g. staging, private gateway, PayAI fallback).
+X402_FACILITATOR_URL=
+
+# CDP credentials — REQUIRED when X402_NETWORK=solana-mainnet, ignored on
+# devnet. Generate at https://portal.cdp.coinbase.com/access/api → "Create
+# API Key". `KEY_ID` is public-ish; `KEY_SECRET` is the Ed25519 (or ES256)
+# private key — keep it in 1Password, never commit. SSM holds both as
+# SecureString. Sentinel `__unset__` triggers a clean startup error on
+# mainnet rather than a confusing 401 at first paid request.
+CDP_API_KEY_ID=
+CDP_API_KEY_SECRET=
+
+# Privy v2 server-side wallet credentials — REQUIRED for per-project wallet
+# provisioning (S2-05). On `POST /projects` we create a Solana embedded
+# wallet via Privy and persist its id/address on the project row. Without
+# these set, `Settings.is_privy_configured()` returns False and provisioning
+# is silently skipped — devnet without Privy keys still serves users without
+# `project_id`. Generate at https://dashboard.privy.io → "Settings" → "API
+# keys"; `APP_ID` (~26 chars, public-ish) and `APP_SECRET` (~105 chars,
+# secret — keep in 1Password). SSM holds both as SecureString. Sentinel
+# `__unset__` triggers the lazy-skip path rather than a hard boot error.
+PRIVY_APP_ID=
+PRIVY_APP_SECRET=
+
+# ---------------------------------------------------------------------------
+# twit.sh — X/Twitter data via x402 micropayments
+# ---------------------------------------------------------------------------
+# https://twit.sh — Pay $0.0025-$0.01 per X read via x402 on Base.
+# The Gecko-owned wallet is server-managed (you fund it with USDC on Base).
+# Disabled by default (TWITSH_ENABLED=false) — flip to "true" once funded.
+# Sentinel "__unset__" on private key disables the integration silently
+# regardless of TWITSH_ENABLED, so misconfigured deploys don't burn calls.
+TWITSH_ENABLED=false
+TWITSH_WALLET_PRIVATE_KEY=
+TWITSH_WALLET_ADDRESS=
+TWITSH_BASE_URL=https://x402.twit.sh
+
+# Treasury address — Solana pubkey that RECEIVES USDC. Generate fresh for
+# production (we only need the public key here; keep the secret in 1Password):
+#   uv run python -c "from solders.keypair import Keypair; kp=Keypair(); print(kp.pubkey())"
+# Then send a tiny USDC transfer to it once so the SPL token account exists.
+GECKO_WALLET_ADDRESS=
+
+# Pricing (single quotes to keep the literal `$`, otherwise bash expands $0)
+#   '$0.10'   — devnet/demo
+#   '$0.50'   — mainnet starter
+#   '$20.00'  — production target
+RESEARCH_BASIC_PRICE='$0.10'
+RESEARCH_PRO_PRICE='$0.75'
+
+# ---------------------------------------------------------------------------
+# Optional — V1 Decision Receipt (on-chain verdict-hash anchor, DEVNET ONLY)
+# ---------------------------------------------------------------------------
+# Anchors sha256(canonical_json(verdict_envelope)) as an SPL Memo on Solana
+# devnet so a third party can verify "this agent checked before it acted".
+# v0 = SPL Memo, devnet, NO real money (devnet airdrop pays the ~5000-lamport
+# fee). DEFAULT OFF — the anchor signs + broadcasts a tx, so it is gated hard.
+# Mainnet anchoring is the v1 PDA program, not this path.
+#
+# Enable the ANCHOR side (server that posts receipts):
+#   GECKO_RECEIPT_ENABLED=1
+#   GECKO_RECEIPT_RPC_URL=https://api.devnet.solana.com   (must be devnet)
+#   GECKO_RECEIPT_ORACLE_KEYPAIR=/abs/path/devnet-oracle.json  (gitignored)
+# Generate the devnet keypair with: solana-keygen new -o devnet-oracle.json
+# then `solana airdrop 1 <pubkey> --url devnet`. NEVER commit the keypair.
+GECKO_RECEIPT_ENABLED=
+GECKO_RECEIPT_RPC_URL=
+GECKO_RECEIPT_ORACLE_KEYPAIR=
+#
+# Enable the VERIFIER side (public POST /v1/receipt/verify route). The PUBLIC
+# key is safe to publish — it is the verification anchor. Set it + the devnet
+# RPC so the route checks against the right oracle; unset → route returns 503.
+GECKO_RECEIPT_ORACLE_PUBKEY=
+
+# ---------------------------------------------------------------------------
+# Optional — YouTube caption fallback
+# ---------------------------------------------------------------------------
+# Enables Deepgram nova-3 transcription when a YouTube video has no captions.
+# Without it, those sources are silently skipped (~$0.0043/minute when used).
+# DEEPGRAM_API_KEY=
+# DEEPGRAM_MAX_AUDIO_MIN=30
+
+# ---------------------------------------------------------------------------
+# Client-side (gecko-mcp talking to gecko-api) — NOT pushed to SSM
+# ---------------------------------------------------------------------------
+# Lives in ~/.gecko/.env on the user's machine, not here. Default once
+# deployed: https://api.geckovision.tech. Override only for local dev.
+# GECKO_API_URL=http://localhost:8000
+
+# ---------------------------------------------------------------------------
+# Defaults — NOT pushed to SSM (pure code default)
+# ---------------------------------------------------------------------------
+GECKO_DEFAULT_TIER=basic
+
+# ---------------------------------------------------------------------------
+# Production judge transcript capture (S12-HARDEN-03)
+# ---------------------------------------------------------------------------
+# Every successful /research and /plan call writes one transcript record to
+# disk for audit (compliance + post-hoc review of misranked verdicts surfaced
+# by CDP Bazaar). Schema mirrors the eval-side capture in tests/eval/runner.
+#
+# Default: enabled in production, disabled under pytest (see tests/conftest.py).
+# See docs/runbooks/cdp-bazaar.md § "Inspect public verdicts" for queries.
+# GECKO_TRANSCRIPT_CAPTURE=true
+#
+# S12-HARDEN-05 — backend selection. Three modes:
+#   mongo      → judge_transcripts collection in MongoDB (production default
+#                when MONGODB_URI is set; ECS Fargate has ephemeral disk so
+#                Mongo is the only durable store). Reuses MONGODB_URI and
+#                MONGODB_DB env vars already required for the twit.sh cache.
+#                If a write fails (network blip, auth fail), the dispatcher
+#                logs WARN and falls through to the filesystem store so a
+#                verdict is never lost.
+#   filesystem → one JSON file per session_id at GECKO_TRANSCRIPT_DIR (or
+#                /var/lib/gecko/judge_transcripts when writable, else
+#                /tmp/gecko/transcripts). Local dev / CI / fallback.
+#   noop       → drop on the floor. Rare; differs from CAPTURE=false in
+#                intent only.
+#
+# Default when GECKO_TRANSCRIPT_STORE is unset: "mongo" if MONGODB_URI is set,
+# otherwise "filesystem".
+# GECKO_TRANSCRIPT_STORE=mongo
+# GECKO_TRANSCRIPT_DIR=/var/lib/gecko/judge_transcripts  # filesystem mode only
+# MONGODB_URI=mongodb+srv://...                          # required for mongo mode
+# MONGODB_DB=gecko_cache                                 # default; shared with twit.sh cache
+
+# ---------------------------------------------------------------------------
+# S18-MONGO — chunk store (chunks + chunk_embedding_cache + chunks_write_audit)
+# ---------------------------------------------------------------------------
+# Cutover from Supabase pgvector to MongoDB Atlas Vector Search. Solo-user
+# fresh-start cutover (no backfill). See docs/strategy/2026-05-02-s18-plan.md.
+#
+#   GECKO_CHUNK_STORE selects the active store:
+#     supabase → legacy Postgres + pgvector (default during S18 dev)
+#     mongo    → MongoDB Atlas (gecko_rag DB; flip after M5 cutover)
+#
+# MONGODB_URI is reused from the transcript store above. The chunk store lives
+# in its own database (gecko_rag) and uses these collections:
+#   - chunks                  (vector + Atlas Search indexes; M1 schema)
+#   - chunk_embedding_cache   (content-addressed embed cache)
+#   - chunks_write_audit      (per-batch ingest observability)
+#
+# GECKO_CHUNK_STORE=supabase
+# MONGODB_CHUNK_DB=gecko_rag                             # default for chunk store
+
+# ---------------------------------------------------------------------------
+# S22-VOYAGE-EMBED — embedding provider (default: voyage)
+# ---------------------------------------------------------------------------
+EMBED_PROVIDER=voyage
+VOYAGE_API_KEY=                    # required when EMBED_PROVIDER=voyage
+# EMBED_MODEL=voyage-context-3     # default — RAG-optimal context-aware embedding model
+#                                  # legacy voyage-3 still supported (same 1024 dim)
+
+# ---------------------------------------------------------------------------
+# S28 #25 — Cohere Rerank (post-retrieval semantic reranker).
+# Wired into orchestration/trade_panel/retrieve_trade_corpus_chunks between
+# `_apply_retrieval_boosts` and `_provider_quota_floor`. When unset, the
+# rerank step degrades gracefully and the trade-panel falls through to the
+# Path D baseline slate (still functional, no crash). Model: rerank-v3.5.
+# Cost: ~$1.20 per 1000 verdicts at 180-doc pool.
+# ---------------------------------------------------------------------------
+COHERE_API_KEY=                    # optional — enables Cohere rerank-v3.5 in trade-panel retrieval
+
+# ---------------------------------------------------------------------------
+# OKX OnchainOS Market — developer key (OK-ACCESS-KEY header).
+# Drives gecko_core.sources.okx_onchainos_market: token metrics (mcap /
+# liquidity / 24h volume / holders count), top-20 holder concentration, and
+# the manipulation-resistant composite index price. Distinct from OKX_API_KEY
+# (the Bearer-token news adapter). Unset → client disabled, all methods
+# fail-OPEN to None/[]. Base: https://web3.okx.com (override OKX_BASE_URL N/A;
+# base is a client kwarg).
+# ---------------------------------------------------------------------------
+OKX_ONCHAINOS_API_KEY=             # optional — OnchainOS Market developer key
+
+# Helius API — get a key at https://dev.helius.xyz
+HELIUS_API_KEY=
+# Colosseum Copilot (optional) — for startup research skill
+# Get a PAT at https://arena.colosseum.org/copilot
+COLOSSEUM_COPILOT_PAT=
+COLOSSEUM_COPILOT_API_BASE=https://copilot.colosseum.com/api/v1
+# QEDGen formal verification (optional) — requires qedgen CLI
+# Get a key at https://console.mistral.ai
+MISTRAL_API_KEY=
+# TheGrid (optional) — for Colosseum project graph queries
+# Get a key at https://thegrid.id
+THEGRID_API_KEY=
+THEGRID_GRAPHQL_ENDPOINT=https://beta.node.thegrid.id/graphql
+# QuickNode (optional) — for QuickNode RPC/Streams/DAS
+# Get endpoints at https://www.quicknode.com
+QUICKNODE_RPC_URL=
+QUICKNODE_WSS_URL=
+QUICKNODE_API_KEY=
+# X/Twitter (optional) — for CT alpha research skill
+# Get a bearer token at https://developer.x.com
+X_BEARER_TOKEN=
+# DFlow (optional) — for DFlow order flow integration
+DFLOW_API_KEY=

gecko_surf-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+build/
+dist/
+
+# Test / tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Env / secrets — ship .env.example only
+.env
+.env.*
+!.env.example
+
+# OS / editor
+.DS_Store
+.idea/
+*.swp
+
+# Strategy / business docs — never in the public tree (canonical set lives in Notion)
+private/
+docs/
+CLAUDE.md
+
+# Claude Code local config, agents, and skills (internal)
+.claude/
+
+# MCP — real config carries a token; ship .mcp.json.example instead
+.mcp.json

gecko_surf-0.1.0/.mcp.json.example

@@ -0,0 +1,21 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp@latest"
+      ]
+    },
+    "github": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-github"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    }
+  }
+}

gecko_surf-0.1.0/Dockerfile

@@ -0,0 +1,56 @@
+# =============================================================================
+# surfcall — MCP Streamable-HTTP container (Python + uv + uvicorn on port 8000)
+#
+# Single-package repo (NOT a uv workspace). Stage 1 builds the venv with the
+# `serve` extra (mcp[cli] + uvicorn -> pulls starlette). Stage 2 copies the venv
+# + the surfcall package + the one local OpenAPI spec the container serves.
+# Stateless: no DB/SSM/secrets at build or run time (control plane only).
+# =============================================================================
+
+FROM python:3.12-slim AS builder
+
+# uv (Astral): static binary from the official image (slim has no curl/wget).
+COPY --from=ghcr.io/astral-sh/uv:0.5.30 /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# Manifests + source first, so `uv sync` can build the flat-layout package.
+COPY pyproject.toml uv.lock README.md ./
+COPY surfcall ./surfcall
+
+# Engine + the serve extra (mcp[cli], uvicorn, starlette). --no-dev drops
+# mypy/pytest/ruff; --frozen pins to uv.lock (must resolve the serve extra).
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev --extra serve
+
+# -----------------------------------------------------------------------------
+
+FROM python:3.12-slim AS runner
+
+RUN useradd --create-home --shell /bin/bash surfcall
+
+WORKDIR /app
+
+COPY --from=builder /app/.venv ./.venv
+COPY --from=builder /app/pyproject.toml /app/uv.lock /app/README.md ./
+COPY surfcall ./surfcall
+# The one OpenAPI spec the container comprehends + serves. Control plane only:
+# no payloads, no secrets.
+COPY examples/sos_vzla_bot/spec ./examples/sos_vzla_bot/spec
+
+RUN chown -R surfcall:surfcall /app
+USER surfcall
+
+ENV PATH="/app/.venv/bin:$PATH" \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PORT=8000
+
+EXPOSE 8000
+
+# Mirror the ALB target-group health check (GET /healthz, matcher 200) locally.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=3).status==200 else 1)" || exit 1
+
+# Bind 0.0.0.0:$PORT, mode=live, allowlist mcp.geckovision.tech.
+CMD ["python", "-m", "surfcall.serve_mcp"]

gecko_surf-0.1.0/LICENSE

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

gecko_surf-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: gecko-surf
+Version: 0.1.0
+Summary: Make any API agent-usable without integration code. V1: comprehension layer — turn a human-shaped OpenAPI surface into question-shaped, first-call-correct agent tools. (Working name; rename on brand pick.)
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: serve
+Requires-Dist: mcp[cli]>=1.28.1; extra == 'serve'
+Requires-Dist: uvicorn>=0.49.0; extra == 'serve'
+Provides-Extra: sosbot
+Requires-Dist: anthropic>=0.40; extra == 'sosbot'
+Requires-Dist: openai>=1.40; extra == 'sosbot'
+Requires-Dist: python-telegram-bot>=21; extra == 'sosbot'