Week 3 — M3: Hyperliquid Enhanced Research + Personas + Final Integration

Goal: Build 2 Hyperliquid enhanced research tools, wire persona configs to the full pipeline, and run integration tests for all 3 personas.

Exit Criteria: All 3 milestones complete. Every module has unit tests. Integration tests pass for all 3 personas. Everything runs locally with uv run pytest.

Tasks

3.1 — Open Interest History Tool (M3)

Assignee: Dev A Effort: 1 day Depends on: —

Description: New RobustTool that tracks open interest changes over time for Hyperliquid perpetuals. Derives positioning and sentiment signals from OI trends. Uses existing Hyperliquid tools as data sources.

Subtasks:

  • Define OpenInterestHistoryParams (symbol, lookback_days, interval)
  • Implement OI history retrieval:
    • Use existing hyperliquid_market_discovery for current OI
    • Use existing hyperliquid_candles for historical price context
    • Calculate OI change rate over time windows (1h, 4h, 24h, 7d)
    • Derive sentiment signals:
      • Rising OI + rising price → new longs (bullish)
      • Rising OI + falling price → new shorts (bearish)
      • Falling OI + rising price → short covering (bullish)
      • Falling OI + falling price → long liquidation (bearish)
  • Output: OI time series, change rates, sentiment signal, conviction level
  • Unit tests with fixture candle/OI data

Acceptance Criteria:

  • Takes symbol + lookback → returns OI analysis with sentiment
  • Sentiment derivation follows the 4 quadrants (OI direction × price direction)
  • Change rates calculated for multiple time windows
  • Conviction level based on magnitude of OI change
  • Unit tests cover: each sentiment quadrant, flat OI, missing data
  • Tests pass with uv run pytest tests/unit/test_oi_history.py

Deliverables:

  • kosong_agent/tools/hyperliquid/oi_history.py
  • tests/unit/test_oi_history.py

3.2 — Taker Flow + Whale Print Detection Tool (M3)

Assignee: Dev A Effort: 1.5 days Depends on: —

Description: New RobustTool that identifies large aggressive orders (whale prints) and taker-side flow imbalance in Hyperliquid trades. Helps detect informed aggression.

Subtasks:

  • Define TakerFlowParams (symbol, lookback_minutes, whale_threshold_usd)
  • Implement taker flow analysis:
    • Fetch recent trades via existing hyperliquid_trades
    • Classify each trade as taker-buy or taker-sell
    • Calculate taker flow imbalance: net taker buy volume / total volume
    • Bucket by time (e.g., 5-minute windows)
    • Flow trend: is taker side accelerating or decelerating?
  • Implement whale print detection:
    • Flag trades above whale_threshold_usd (default $50,000)
    • For each whale print: timestamp, size, side, price
    • Aggregate: whale buy volume vs whale sell volume
    • Whale conviction: are whales aligned or split?
  • Output: taker_flow_summary, whale_prints list, whale_conviction, flow_trend
  • Unit tests with fixture trade data (normal + whale activity)

Acceptance Criteria:

  • Takes symbol + params → returns taker flow analysis + whale prints
  • Taker flow imbalance correctly calculated (-1 to +1 scale)
  • Whale prints correctly identified above threshold
  • Whale conviction derived from buy/sell whale volume ratio
  • Unit tests cover: balanced flow, taker-buy heavy, whale activity, no whales, edge cases
  • Tests pass with uv run pytest tests/unit/test_taker_flow.py

Deliverables:

  • kosong_agent/tools/hyperliquid/taker_flow.py
  • tests/unit/test_taker_flow.py

3.3 — Wire Persona Configs to Full Pipeline

Assignee: Dev B Effort: 1 day Depends on: 2.2, all M2/M3 tools

Description: Connect persona config to the orchestration pipeline so that each persona uses its specific tool subset, scoring weights, and risk limits. Verify that different personas produce different behavior.

Subtasks:

  • Update Orchestrator to filter available tools based on persona’s tool_allowlist
  • Update ScorecardEngine to use persona’s scoring_config weights
  • Update ActionEngine to use persona’s risk_limits and action_thresholds
  • Update PlanGenerator to only reference allowed tools
  • Finalize 3 persona configs with correct tool lists:
    • polymarket_sports: market discovery, price history, sportsbook benchmark, spike detection, directional flow
    • polymarket_multichoice: market discovery, price history, account age, concentration, directional flow
    • hyperliquid_intent: market discovery, candles, funding, OI history, taker flow
  • Integration test: run each persona, verify different tools are used

Acceptance Criteria:

  • Each persona only has access to its allowed tools
  • Scoring weights differ per persona
  • Risk limits differ per persona (e.g., Hyperliquid has leverage limits)
  • Integration test shows 3 different tool usage patterns
  • Tests pass with uv run pytest tests/integration/test_persona_wiring.py

Deliverables:

  • Updated kosong_agent/orchestration/orchestrator.py
  • Updated persona JSON files
  • tests/integration/test_persona_wiring.py

3.4 — Polymarket Sports Integration Test

Assignee: Dev A Effort: 0.5 days Depends on: 3.3

Description: Full end-to-end integration test for the Polymarket Sports persona. Runs the complete pipeline against real APIs: thesis → plan → investigate (real tools) → score → action.

Subtasks:

  • Load polymarket_sports persona
  • Run full orchestration loop with real Polymarket + Odds APIs
  • Verify thesis is sports-relevant
  • Verify plan uses sportsbook benchmark + spike detection + directional flow
  • Verify scorecard has all expected factors populated
  • Verify action recommendation is valid (BUY/SELL/PASS)

Acceptance Criteria:

  • Full pipeline completes without errors
  • All audit entries are present
  • Test marked @pytest.mark.integration, skipped without API keys
  • Test passes with uv run pytest tests/integration/test_polymarket_sports_e2e.py -m integration

Deliverables:

  • tests/integration/test_polymarket_sports_e2e.py

3.5 — Polymarket Multi-Choice Integration Test

Assignee: Dev A Effort: 0.5 days Depends on: 3.3

Description: Full end-to-end integration test for the Polymarket Multi-Choice persona.

Subtasks:

  • Load polymarket_multichoice persona
  • Run full orchestration loop with real Polymarket + Polygon APIs
  • Verify plan uses account age + concentration + directional flow
  • Verify scorecard and action are populated

Acceptance Criteria:

  • Full pipeline completes without errors
  • Uses multi-choice specific tools (account age, concentration)
  • Test passes with uv run pytest tests/integration/test_polymarket_multichoice_e2e.py -m integration

Deliverables:

  • tests/integration/test_polymarket_multichoice_e2e.py

3.6 — Hyperliquid Intent Integration Test

Assignee: Dev A Effort: 0.5 days Depends on: 3.3

Description: Full end-to-end integration test for the Hyperliquid Intent persona.

Subtasks:

  • Load hyperliquid_intent persona
  • Run full orchestration loop with real Hyperliquid APIs
  • Verify plan uses OI history + taker flow + funding
  • Verify risk limits include leverage constraints
  • Verify scorecard and action are populated

Acceptance Criteria:

  • Full pipeline completes without errors
  • Uses Hyperliquid-specific tools (OI history, taker flow)
  • Leverage limits are enforced in action engine
  • Test passes with uv run pytest tests/integration/test_hyperliquid_intent_e2e.py -m integration

Deliverables:

  • tests/integration/test_hyperliquid_intent_e2e.py

3.7 — Debug Script: Full Pipeline

Assignee: Dev B Effort: 0.5 days Depends on: 3.3

Description: CLI script that runs all 3 personas in dry-run mode, printing the full execution trace for each.

Subtasks:

  • CLI with --persona flag (or --all to run all 3)
  • --dry-run uses mocked tools, --live uses real APIs
  • Rich-formatted output: state transitions, thesis, plan, tool results, scorecard, action
  • Summary table at end: persona | score | action | tool calls made

Acceptance Criteria:

  • uv run python -m kosong_agent.debug.debug_full_pipeline --all --dry-run runs all 3 personas
  • Each persona prints its full trace
  • Summary table shows differences between personas
  • No API keys required in dry-run mode

Deliverables:

  • kosong_agent/debug/debug_full_pipeline.py