{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# HLP capital and execution activity\n",
    "Set `AHAB_DATA_API_KEY` in your notebook environment before running. This example uses your paid request/row allowance. It fetches the latest seven observed days, reconciles three analytics against raw records, and stops if the snapshot changes.\n",
    "The measured data covers selected HLP observations. Capital is a collector-defined proxy; equity changes are not wallet flows or PnL. Fill observations on different legs can share a trade. Timing statistics do not predict returns.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#!/usr/bin/env python3\n",
    "\"\"\"Research example: reconcile seven days of BTC HLP activity and capital analytics.\n",
    "\n",
    "Set AHAB_DATA_API_KEY; optionally AHAB_DATA_API_BASE_URL (defaults to captainahab.dev).\n",
    "Uses the standard library. Prints aggregate research results, never the key.\n",
    "\"\"\"\n",
    "from __future__ import annotations\n",
    "\n",
    "from collections import defaultdict\n",
    "import json\n",
    "import math\n",
    "import os\n",
    "from urllib.parse import urlencode\n",
    "from urllib.request import HTTPRedirectHandler, Request, build_opener\n",
    "\n",
    "DAY = 86_400_000\n",
    "\n",
    "\n",
    "class NoRedirect(HTTPRedirectHandler):\n",
    "    def redirect_request(self, *args, **kwargs):\n",
    "        return None\n",
    "\n",
    "\n",
    "def study(get):\n",
    "    coverage = get('/v1/coverage', {})\n",
    "    datasets = coverage['coverage']\n",
    "    end = min(datasets[t]['newest_ts_ms'] for t in ('capital', 'fills')) + 1\n",
    "    start = max(end - 7 * DAY, max(datasets[t]['oldest_ts_ms'] for t in ('capital', 'fills')))\n",
    "    if start >= end:\n",
    "        raise ValueError('No overlapping observed history')\n",
    "    version = coverage['snapshot']['version']\n",
    "\n",
    "    def fetch(path, params):\n",
    "        result = get(path, params)\n",
    "        if result['snapshot']['version'] != version:\n",
    "            raise RuntimeError('Snapshot refreshed during the study; rerun to use one version')\n",
    "        return result\n",
    "\n",
    "    query = {'start_ms': start, 'end_ms': end}\n",
    "    capital = fetch('/v1/analytics/capital', query)\n",
    "    fills = fetch('/v1/analytics/fills', {**query, 'coin': 'BTC'})\n",
    "    activity = fetch('/v1/analytics/activity', {**query, 'coin': 'BTC'})\n",
    "\n",
    "    def raw(dataset, coin=None):\n",
    "        params = {**query, 'limit': 1000}\n",
    "        if coin:\n",
    "            params['coin'] = coin\n",
    "        rows, seen = [], set()\n",
    "        for _ in range(100):\n",
    "            page = fetch('/v1/hlp/' + dataset, params)\n",
    "            rows.extend(page['data'])\n",
    "            cursor = page['next_cursor']\n",
    "            if not cursor:\n",
    "                return rows\n",
    "            if cursor in seen:\n",
    "                raise RuntimeError('Pagination did not advance')\n",
    "            seen.add(cursor)\n",
    "            params['cursor'] = cursor\n",
    "        raise RuntimeError('Research request bound reached; choose a shorter window')\n",
    "\n",
    "    raw_capital, raw_fills = raw('capital'), raw('fills', 'BTC')\n",
    "    if not raw_capital or not raw_fills:\n",
    "        raise ValueError('No observations for this example; this does not mean zero activity')\n",
    "    by_day, by_group, by_series = defaultdict(list), defaultdict(list), defaultdict(list)\n",
    "    for row in raw_capital:\n",
    "        by_day[row['snapshot_ts_ms'] // DAY * DAY].append(row)\n",
    "    for result in capital['data']:\n",
    "        rows = by_day[result['day_start_ms']]\n",
    "        values = [r['utilization'] for r in rows if r['utilization'] is not None]\n",
    "        expected = math.fsum(values) / len(values) if values else None\n",
    "        actual = result['utilization']['mean']\n",
    "        assert (actual is None and expected is None) or (\n",
    "            actual is not None and expected is not None and math.isclose(actual, expected, rel_tol=1e-10))\n",
    "        assert result['sample_count'] == len(rows)\n",
    "\n",
    "    seen = set()\n",
    "    fields = ('coin', 'hlp_address', 'fill_ts_ms', 'side', 'hlp_side', 'px', 'sz', 'usd', 'trade_id')\n",
    "    for row in raw_fills:\n",
    "        by_group[tuple(row[k] for k in ('coin', 'hlp_address', 'hlp_side', 'side'))].append(row)\n",
    "        key = tuple(row[k] for k in fields)\n",
    "        if row['trade_id'] is None or key not in seen:\n",
    "            by_series[(row['coin'], row['hlp_address'])].append(row['fill_ts_ms'])\n",
    "        seen.add(key)\n",
    "    assert len(fills['data']) == len(by_group)\n",
    "    for result in fills['data']:\n",
    "        group = by_group[tuple(result[k] for k in ('coin', 'hlp_address', 'hlp_side', 'side'))]\n",
    "        assert result['fill_count'] == len(group)\n",
    "        assert math.isclose(result['notional_usd'], math.fsum(r['usd'] for r in group), rel_tol=1e-10)\n",
    "        size = math.fsum(r['sz'] for r in group)\n",
    "        expected = math.fsum(r['px'] * r['sz'] for r in group) / size if size else None\n",
    "        assert (expected is None and result['vwap'] is None) or (\n",
    "            expected is not None and math.isclose(expected, result['vwap'], rel_tol=1e-10))\n",
    "    assert len(activity['data']) == len(by_series)\n",
    "    for result in activity['data']:\n",
    "        times = sorted(by_series[(result['coin'], result['hlp_address'])])\n",
    "        gaps = [times[n] - times[n-1] for n in range(1, len(times))]\n",
    "        assert result['gap_count'] == len(gaps)\n",
    "        expected = sum(g <= 1000 for g in gaps) / len(gaps) if gaps else None\n",
    "        assert result['burst_fraction'] == expected\n",
    "\n",
    "    return {\n",
    "        'question': 'How did observed HLP utilization and BTC execution activity vary over the latest seven days?',\n",
    "        'snapshot_version': version, 'window': query,\n",
    "        'coverage_caveat': 'Selected observations; gaps and shared trades across legs prevent exchange-volume claims.',\n",
    "        'dataset_freshness': coverage['snapshot'].get('dataset_freshness'),\n",
    "        'independent_reconciliation': 'passed',\n",
    "        'raw_rows_checked': {'capital': len(raw_capital), 'BTC_fills': len(raw_fills)},\n",
    "        'daily_utilization': [\n",
    "            {k: r[k] for k in ('day_start_ms', 'sample_count', 'utilization', 'max_gap_ms')}\n",
    "            for r in capital['data']],\n",
    "        'BTC_fill_groups': fills['data'], 'BTC_activity_by_leg': activity['data'],\n",
    "        'interpretation': 'Utilization is sample-weighted. Burst fraction describes observed timing; it is not a forecast.',\n",
    "    }\n",
    "\n",
    "\n",
    "def main():\n",
    "    base = os.environ.get('AHAB_DATA_API_BASE_URL', 'https://captainahab.dev').rstrip('/')\n",
    "    if not base.startswith('https://') and not base.startswith(('http://127.0.0.1:', 'http://localhost:')):\n",
    "        raise ValueError('Use HTTPS, or an explicit loopback HTTP test server')\n",
    "    key = os.environ['AHAB_DATA_API_KEY']\n",
    "    opener = build_opener(NoRedirect)\n",
    "\n",
    "    def get(path, params):\n",
    "        req = Request(base + path + '?' + urlencode(params),\n",
    "                      headers={'Authorization': 'Bearer ' + key, 'Accept': 'application/json'})\n",
    "        with opener.open(req, timeout=30) as response:\n",
    "            return json.load(response)\n",
    "\n",
    "    print(json.dumps(study(get), indent=2, allow_nan=False))\n",
    "\n",
    "\n",
    "if __name__ == '__main__':\n",
    "    main()\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}