🐦‍⬛ CORVUS

An AI agent that models the survivability of Solana Superteam startups.

CORVUS watches on-chain activity, developer output, community signal, and grant/bounty track record to produce a transparent 0–100 survivability score for early-stage Solana projects — with a risk tier, plain-English flags, and trend tracking over time.

Corvids are famously good at spotting what's about to fall apart before anyone else notices. That's the job here.

Nebula Swap (nebula-swap)
Score: 86.0/100  Tier: thriving  Trend: flat

┏━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Category    ┃ Sub-score ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ On-chain    │      0.95 │
│ Development │      0.80 │
│ Social      │      0.81 │ 
│ Grants      │      0.82 │
└─────────────┴───────────┘

PixelForge Games (pixelforge-games)
Score: 19.2/100  Tier: critical  Trend: flat
Flags:
  • No commits in 214 days — possible abandonment
  • On-chain activity dropped more than 50% month-over-month
  • Has abandoned grant(s) with no completed grants on record

Why

Superteam funds and Solana grant reviewers track dozens to hundreds of early-stage projects. Most survivability signal — is this thing actually being used, is anyone still shipping, is the community still there — is scattered across a block explorer, a GitHub repo, Twitter, and a grants dashboard. CORVUS pulls those into one explainable number and re-checks it over time so declines get caught early instead of six months after the repo went quiet.

Existing Architecture

This is v0.1: a solid, tested architecture with a fully working scoring pipeline running on bundled mock data for six fictional demo startups. The four data-source categories are built as an adapter interface with a Mock*Source (works out of the box) and a Live*Source stub (ready for you to wire up a real Solana RPC, the GitHub API, X/Twitter, and Superteam Earn). See docs/ARCHITECTURE.md for the complete design and extension points.

Install

git clone https://github.com/<you>/CORVUS.git
cd CORVUS
pip install -e .

Requires Python 3.10+.

Quickstart

# Score one of the bundled demo startups
corvus score nebula-swap

# See it as JSON
corvus score pixelforge-games --json

# Build a watchlist and track it over time
corvus watchlist add depin-grid
corvus watchlist add lumen-pay
corvus watchlist run     # ranked report, run this daily/weekly to get trends
corvus watchlist list

Demo startups bundled in data/mock/startups.json: nebula-swap, forge-dao, lumen-pay, pixelforge-games, depin-grid, mosaic-identity — spanning thriving to critical, so you can see the model differentiate.

How the score works

composite = 0.35·onchain + 0.30·dev + 0.15·social + 0.20·grants   (weights configurable)

Each category is normalized 0–1 from raw metrics (transaction volume, commit recency, sentiment, grant completion rate, etc.), then combined into a 0–100 score with a tier:

Score	Tier
75–100	🟢 Thriving
55–74	🔵 Stable
35–54	🟡 At Risk
0–34	🔴 Critical

Rule-based flags call out specific risk patterns (stale repo, activity cliff, abandoned grants, negative sentiment, usage/dev mismatch). Full detail in docs/ARCHITECTURE.md.

Going live

By default CORVUS_DATA_MODE=mock. To point CORVUS at real data:

1. Copy .env.example to .env and set CORVUS_DATA_MODE=live, plus a GITHUB_TOKEN and whatever RPC/social credentials you're using.
2. Implement the fetch() methods in Live*Source classes under src/corvus/data_sources/ — they're stubbed with NotImplementedError and comments on what's needed, since which indexer/API you use is a config choice.
3. Optionally set CORVUS_LLM_EXPLANATIONS=true and ANTHROPIC_API_KEY to have Claude turn each score breakdown into a written analyst note (corvus/llm.py) — grounded in the computed numbers, never inventing facts.

Project layout

src/corvus/
  schemas.py           # Pydantic contracts for every stage
  config.py             # weights, tier cutoffs, env-based settings
  agent.py               # CorvusAgent orchestrator
  watchlist.py            # JSON-backed persistence + history
  llm.py                   # optional Claude-generated narratives
  cli.py                    # `corvus` command-line interface
  data_sources/               # adapter interface + mock/live impls
  models/                       # feature normalization + scoring + trend
data/mock/                        # bundled demo data (6 fictional startups)
tests/                              # pytest suite
docs/ARCHITECTURE.md                  # design doc, extension points

Development

pip install -e ".[dev]"
pytest --cov=corvus
ruff check src tests

Roadmap ideas

• Live adapter implementations (Helius/Triton for on-chain, GitHub REST, X API, Superteam Earn ingestion)
• Percentile-rank normalization against a peer cohort instead of fixed caps
• Scheduled runs (GitHub Actions cron) with Slack/Discord alerts on tier downgrades
• Web dashboard for the watchlist report
• Backtesting harness once real outcome data exists

License

MIT — see LICENSE.