Nava Agent — Sprint Roadmap
Overview
AI trading agent for Polymarket prediction markets and Hyperliquid perpetual futures. Architecture: persona → thesis → plan → tool calls → score → action.
Three configurable agent personas on a single engine:
- Polymarket Sports — binary “Who will win” markets
- Polymarket Multi-Choice — “By what date will X occur” markets
- Hyperliquid Intent — perp long/short requests
What Already Exists
| Source | What’s There | Status |
|---|---|---|
nava-agent/ (Nava scaffold) | 8 Polymarket tools, 7 Hyperliquid tools, 2 web tools, RobustTool base, 2 workflows, interactive CLI, kosong SDK | Stable, use as-is |
polymarket-scratch/ | PolymarketClient, EtherscanClient, spike detection, insider signals framework, trade analysis patterns, market discovery | Reuse & wrap |
sports-odds-backtesting/ | OddsClient (async + retry + quota), DuckDB storage, PropSnapshot models, NBA/NFL market configs, backfiller | Reuse & wrap |
What We Build
Milestone 1: Base Agent Infrastructure (Week 1)
The orchestration engine — state machine, LLM-powered thesis/plan generators, scorecard, action engine.
Milestone 2: Polymarket Enhanced Research (Week 2)
5 analysis tools that leverage existing code from polymarket-scratch/ and sports-odds-backtesting/:
- Sportsbook odds benchmark (wraps OddsClient)
- Spike + retracement detection (wraps
find_price_spikes()) - Directional flow analysis (wraps trade analysis patterns)
- Account age scoring (wraps
get_wallet_first_tx()+ signals) - Concentration + cross-market detection (wraps investigation patterns)
Milestone 3: Hyperliquid Enhanced Research (Week 3)
2 analysis tools + persona wiring + final integration:
- Open interest history
- Taker flow + whale print detection
- 3 persona configs wired end-to-end
Timeline
| Week | Focus | Exit Criteria |
|---|---|---|
| 1 | M1 — Base Infrastructure | Orchestration loop runs end-to-end with mocked tools. State machine tested. Thesis/plan generators produce structured output. |
| 2 | M1 finish + M2 — Scoring + Polymarket | Full pipeline works with real APIs. All 5 Polymarket enhanced modules done with tests. |
| 3 | M3 — Hyperliquid + Personas + Integration | All milestones complete. 3 personas configured. Full integration tests pass locally. |
| 4 | Buffer | Bug fixes, edge cases, test hardening, slippage. |
Team
- Dev A (80%) — Lead. Orchestration, scoring, action engine, Hyperliquid modules, integration.
- Dev B (20%) — Support. Polymarket tool wrapping, test fixtures, debug scripts.
Constraints
- All modules have unit + integration tests
- Everything runs locally with
uv run pytest - No infra (CloudWatch/SNS/Docker) in scope
- Nava tools are stable dependencies — no rework
- Personas are same engine, different config/prompts
Architecture Decisions
- Framework: kosong SDK (
step()loop,SimpleToolset,CallableTool2) - Tool pattern:
RobustToolbase class (retry, timeout, JSON output) - Config: Module-level constants with
python-dotenv - Models: Pydantic for tool I/O, dataclasses for internal state
- Testing: pytest + pytest-asyncio,
@pytest.mark.integrationfor API tests - Build: uv with pyproject.toml, Python 3.12
Existing Code Reuse Map
| Enhanced Tool | Existing Code | Location | Adaptation |
|---|---|---|---|
| Sportsbook odds benchmark | OddsClient, PropSnapshot, market configs | sports-odds-backtesting/src/odds_collector/ | Wrap as RobustTool, add Polymarket price comparison |
| Spike + retracement detection | find_price_spikes(), PricePoint | polymarket-scratch/insider-detection/src/polymarket_api.py | Wrap as RobustTool, add retracement logic, configurable thresholds |
| Directional flow analysis | Trade aggregation, time-window grouping | polymarket-scratch/insider-detection/scripts/analyze_all_markets.py | Extract buy/sell ratio logic, wrap as RobustTool |
| Account age scoring | get_wallet_first_tx(), EtherscanClient | polymarket-scratch/insider-detection/src/polygon_client.py | Wrap as RobustTool, add age-based scoring tiers |
| Concentration + cross-market | Cross-market analysis, wallet grouping | polymarket-scratch/insider-detection/scripts/investigate_copy_trading.py | Extract concentration metrics, wrap as RobustTool |
| Open interest history | Hyperliquid candles tool (existing) | nava-agent/kosong_agent/tools/hyperliquid/ | New RobustTool, derive OI from existing candle data |
| Taker flow + whale detection | Trade analysis patterns | polymarket-scratch/insider-detection/scripts/ | New RobustTool, apply volume/size thresholds to HL trades |