bitsentry 0.1.0__tar.gz

bitsentry-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+.env
+validation/*.json
+*.db
+dist/
+build/
+*.egg-info/
+.venv/
+.pytest_cache/

bitsentry-0.1.0/AGENTS.md

@@ -0,0 +1,43 @@
+# BitSentry — AGENTS.md
+
+## What We Are Building
+BitSentry is a pip-installable Python library (`pip install bitsentry`) that is the safety, audit, and intelligence layer for Bitget trading agents and traders. Built for the Bitget AI Base Camp Hackathon S1 — Track 2: Trading Infra.
+
+## Core Mission
+Every Bitget trading agent is a black box. When it loses money, nobody knows why. BitSentry fixes that by wrapping every trade decision with risk enforcement, audit logging, and performance intelligence.
+
+## 5 Layers We Are Building
+1. BGCClient — wrapper around bgc CLI for all Bitget data calls (DONE)
+2. AuditEngine — SQLite logger + SHA-256 integrity verification (NEXT)
+3. RiskGuardian — 5-layer risk middleware that approves or blocks trades
+4. PositionMonitor — live position safety ratings (green/yellow/red)
+5. StrategyEvaluator — rolling win rate tracker with PERFORMING/DEGRADING/DEAD verdict
+
+## Plus
+- FastAPI REST server exposing all layers as endpoints
+- React dashboard for human traders
+- MCP server for AI agent integration
+- Makefile with: make install, make test, make validate, make verify
+
+## Credentials (Demo Account)
+BITGET_DEMO_API_KEY=bg_a3a670745f27aaee1609acfe408215aa
+BITGET_DEMO_SECRET_KEY=912bf1e07cf01cc21ad485954d202b0e72fcab89877131129fa793d427fb50e9
+BITGET_DEMO_PASSPHRASE=BitgetDemoKey
+
+## Build Rules
+- Always read existing files before editing them
+- Never guess bgc tool names — run bgc --help first
+- Test every file immediately after writing it
+- One component at a time, confirm it works before moving on
+- Demo mode: always use BGCClient(demo=True) in tests
+- All bgc calls go through BGCClient, never call bgc directly in other files
+
+## Current Status
+- bitsentry/bgc_client.py — COMPLETE AND TESTED
+- bitsentry/audit_engine.py — IN PROGRESS
+- bitsentry/risk_guardian.py — TODO
+- bitsentry/position_monitor.py — TODO
+- bitsentry/strategy_evaluator.py — TODO
+
+## Stack
+Python 3.11+, FastAPI, SQLite, bgc CLI, React (dashboard), MCP protocol

bitsentry-0.1.0/Makefile

@@ -0,0 +1,24 @@
+PY = /opt/miniconda3/bin/python3.13
+
+.PHONY: install run test validate verify lint clean
+
+install:
+	$(PY) -m pip install -e .
+
+run:
+	$(PY) run.py
+
+test:
+	$(PY) -m pytest tests/
+
+validate:
+	$(PY) -c "from bitsentry.audit_engine import AuditEngine; e=AuditEngine(); r=e.generate_audit_report(); print(r); e.export_html_report(); print('HTML report: validation/audit_report.html')"
+
+verify:
+	$(PY) -c "from bitsentry.audit_engine import AuditEngine; e=AuditEngine(); r=e.generate_audit_report(); v=e.verify_integrity(r['integrity_hash']); print('Integrity verified:', v)"
+
+lint:
+	$(PY) -m ruff check bitsentry/
+
+clean:
+	rm -rf dist/ build/ *.egg-info __pycache__

bitsentry-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: bitsentry
+Version: 0.1.0
+Summary: Safety, audit, and intelligence layer for Bitget trading agents and traders
+Project-URL: Homepage, https://github.com/Benita2001/BitSentry
+Project-URL: Repository, https://github.com/Benita2001/BitSentry
+Author-email: Benita Chidera <0xbeni123@gmail.com>
+License: MIT
+Keywords: agent,audit,bitget,crypto,mcp,risk-management,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: uvicorn>=0.24.0
+Description-Content-Type: text/markdown
+
+# BitSentry
+
+Safety, audit, and intelligence layer for Bitget trading agents and traders.
+
+## Structure
+
+- `bitsentry/bgc_client.py` — Bitget API client
+- `bitsentry/audit_engine.py` — Trade audit and logging
+- `bitsentry/risk_guardian.py` — Pre-trade risk enforcement
+- `bitsentry/position_monitor.py` — Real-time position tracking
+- `bitsentry/strategy_evaluator.py` — Strategy scoring and auditing
+- `bitsentry/api/server.py` — FastAPI REST server (11 endpoints)
+- `config/risk_rules.yaml` — Configurable risk parameters
+- `run.py` — Server launcher with startup banner
+
+## Setup
+
+```bash
+make install   # pip install -e .
+make run       # start server on http://127.0.0.1:8000
+make validate  # generate audit report + HTML
+make verify    # verify SHA-256 integrity hash
+```
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Server health + mode |
+| GET | `/positions` | Open positions with safety ratings |
+| GET | `/positions/summary` | GREEN/YELLOW/RED counts |
+| GET | `/positions/safe-to-trade` | Pre-trade exposure check |
+| POST | `/risk/check` | 5-layer risk middleware |
+| GET | `/strategy/leaderboard` | Strategies ranked by profit factor |
+| GET | `/strategy/{tag}` | Strategy health verdict |
+| POST | `/strategy/record` | Record a trade result |
+| GET | `/audit/report` | Full audit + SHA-256 hash |
+| GET | `/audit/verify` | Verify integrity hash |
+| GET | `/docs` | Swagger UI |
+
+## Stack
+
+Python 3.10+, FastAPI, SQLite, bgc CLI, Pydantic v2

bitsentry-0.1.0/README.md

@@ -0,0 +1,43 @@
+# BitSentry
+
+Safety, audit, and intelligence layer for Bitget trading agents and traders.
+
+## Structure
+
+- `bitsentry/bgc_client.py` — Bitget API client
+- `bitsentry/audit_engine.py` — Trade audit and logging
+- `bitsentry/risk_guardian.py` — Pre-trade risk enforcement
+- `bitsentry/position_monitor.py` — Real-time position tracking
+- `bitsentry/strategy_evaluator.py` — Strategy scoring and auditing
+- `bitsentry/api/server.py` — FastAPI REST server (11 endpoints)
+- `config/risk_rules.yaml` — Configurable risk parameters
+- `run.py` — Server launcher with startup banner
+
+## Setup
+
+```bash
+make install   # pip install -e .
+make run       # start server on http://127.0.0.1:8000
+make validate  # generate audit report + HTML
+make verify    # verify SHA-256 integrity hash
+```
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Server health + mode |
+| GET | `/positions` | Open positions with safety ratings |
+| GET | `/positions/summary` | GREEN/YELLOW/RED counts |
+| GET | `/positions/safe-to-trade` | Pre-trade exposure check |
+| POST | `/risk/check` | 5-layer risk middleware |
+| GET | `/strategy/leaderboard` | Strategies ranked by profit factor |
+| GET | `/strategy/{tag}` | Strategy health verdict |
+| POST | `/strategy/record` | Record a trade result |
+| GET | `/audit/report` | Full audit + SHA-256 hash |
+| GET | `/audit/verify` | Verify integrity hash |
+| GET | `/docs` | Swagger UI |
+
+## Stack
+
+Python 3.10+, FastAPI, SQLite, bgc CLI, Pydantic v2

bitsentry-0.1.0/bitsentry/__init__.py

@@ -0,0 +1,18 @@
+# bitsentry — Safety, audit, and intelligence layer for Bitget trading agents
+__version__ = "0.1.0"
+
+from bitsentry.bgc_client import BGCClient
+from bitsentry.audit_engine import AuditEngine
+from bitsentry.risk_guardian import RiskGuardian, RiskCheckResult
+from bitsentry.position_monitor import PositionMonitor, PositionSnapshot
+from bitsentry.strategy_evaluator import StrategyEvaluator, StrategyHealth
+from bitsentry.reporter import ReportGenerator
+from bitsentry.scheduler import Scheduler
+
+__all__ = [
+    "BGCClient", "AuditEngine",
+    "RiskGuardian", "RiskCheckResult",
+    "PositionMonitor", "PositionSnapshot",
+    "StrategyEvaluator", "StrategyHealth",
+    "ReportGenerator", "Scheduler",
+]

bitsentry-0.1.0/bitsentry/api/server.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import dataclasses
+import os
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+from bitsentry.audit_engine import AuditEngine
+from bitsentry.bgc_client import BGCClient, BGCError
+from bitsentry.position_monitor import PositionMonitor
+from bitsentry.reporter import ReportGenerator
+from bitsentry.risk_guardian import RiskGuardian
+from bitsentry.strategy_evaluator import StrategyEvaluator
+
+# ── Global component references ───────────────────────────────────────────────
+# Populated during lifespan startup; all routes read from here.
+
+_state: dict[str, Any] = {}
+
+
+def _asdict(obj: Any) -> Any:
+    """Recursively convert dataclasses to dicts for JSON serialization."""
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return {k: _asdict(v) for k, v in dataclasses.asdict(obj).items()}
+    if isinstance(obj, list):
+        return [_asdict(i) for i in obj]
+    return obj
+
+
+# ── Startup / shutdown ────────────────────────────────────────────────────────
+
+@asynccontextmanager
+async def lifespan(application: FastAPI):
+    demo = os.environ.get("BITGET_DEMO", "true").lower() != "false"
+    try:
+        client = BGCClient(demo=demo)
+    except BGCError as exc:
+        print(f"[bitsentry] WARNING: BGCClient failed to initialize: {exc}")
+        client = None
+
+    audit = AuditEngine()
+    guardian = RiskGuardian(audit_engine=audit)
+    monitor = PositionMonitor(bgc_client=client, audit_engine=audit) if client else None
+    evaluator = StrategyEvaluator(audit_engine=audit)
+
+    reporter = ReportGenerator(
+        audit_engine=audit,
+        strategy_evaluator=evaluator,
+        position_monitor=monitor,
+    )
+
+    _state.update({
+        "client": client,
+        "audit": audit,
+        "guardian": guardian,
+        "monitor": monitor,
+        "evaluator": evaluator,
+        "reporter": reporter,
+        "demo": demo,
+    })
+
+    print("[bitsentry] API server ready.")
+    yield
+    _state.clear()
+
+
+# ── App ───────────────────────────────────────────────────────────────────────
+
+app = FastAPI(
+    title="BitSentry API",
+    description="Safety, audit, and intelligence layer for Bitget trading agents",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Serve dashboard static files at /dashboard/*
+_dashboard_path = os.path.join(os.path.dirname(__file__), "../../dashboard")
+if os.path.exists(_dashboard_path):
+    app.mount("/dashboard", StaticFiles(directory=_dashboard_path, html=True), name="dashboard")
+
+
+# ── Request / response models ─────────────────────────────────────────────────
+
+class RiskCheckRequest(BaseModel):
+    symbol: str
+    side: str
+    size_usdt: float
+    leverage: float
+    account_balance_usdt: float
+    daily_pnl_usdt: float
+    consecutive_losses: int
+
+
+class RecordTradeRequest(BaseModel):
+    strategy_tag: str
+    symbol: str
+    side: str
+    entry_price: float
+    exit_price: float
+    size_usdt: float
+    market_condition: str = ""
+
+
+# ── Routes ────────────────────────────────────────────────────────────────────
+
+@app.get("/ui")
+async def serve_dashboard():
+    dashboard_file = os.path.join(os.path.dirname(__file__), "../../dashboard/index.html")
+    return FileResponse(dashboard_file)
+
+
+@app.get("/")
+def root():
+    return {
+        "name": "BitSentry",
+        "version": "0.1.0",
+        "docs": "/docs",
+        "status": "running",
+    }
+
+
+@app.get("/health")
+def health():
+    return {
+        "status": "ok",
+        "version": "0.1.0",
+        "demo_mode": _state.get("demo", True),
+    }
+
+
+# ── Positions ─────────────────────────────────────────────────────────────────
+
+@app.get("/positions")
+def get_positions():
+    monitor: PositionMonitor | None = _state.get("monitor")
+    if not monitor:
+        raise HTTPException(503, "PositionMonitor unavailable — BGCClient failed to initialize")
+    return _asdict(monitor.get_positions())
+
+
+@app.get("/positions/summary")
+def get_positions_summary():
+    monitor: PositionMonitor | None = _state.get("monitor")
+    if not monitor:
+        raise HTTPException(503, "PositionMonitor unavailable — BGCClient failed to initialize")
+    return monitor.get_account_summary()
+
+
+@app.get("/positions/safe-to-trade")
+def safe_to_trade(
+    symbol: str = Query(..., description="Trading symbol, e.g. BTCUSDT"),
+    direction: str = Query(..., description="long or short"),
+):
+    monitor: PositionMonitor | None = _state.get("monitor")
+    if not monitor:
+        raise HTTPException(503, "PositionMonitor unavailable — BGCClient failed to initialize")
+    return monitor.get_safe_to_trade(symbol=symbol, direction=direction)
+
+
+# ── Risk ──────────────────────────────────────────────────────────────────────
+
+@app.post("/risk/check")
+def risk_check(body: RiskCheckRequest):
+    guardian: RiskGuardian = _state["guardian"]
+    result = guardian.check(
+        symbol=body.symbol,
+        side=body.side,
+        size_usdt=body.size_usdt,
+        leverage=body.leverage,
+        account_balance_usdt=body.account_balance_usdt,
+        daily_pnl_usdt=body.daily_pnl_usdt,
+        consecutive_losses=body.consecutive_losses,
+    )
+    return _asdict(result)
+
+
+# ── Strategy — leaderboard must be declared before /{strategy_tag} ────────────
+
+@app.get("/strategy/leaderboard")
+def strategy_leaderboard():
+    evaluator: StrategyEvaluator = _state["evaluator"]
+    return evaluator.get_leaderboard()
+
+
+@app.get("/strategy/{strategy_tag}")
+def strategy_health(strategy_tag: str):
+    evaluator: StrategyEvaluator = _state["evaluator"]
+    health = evaluator.evaluate(strategy_tag)
+    return _asdict(health)
+
+
+@app.post("/strategy/record")
+def record_trade(body: RecordTradeRequest):
+    evaluator: StrategyEvaluator = _state["evaluator"]
+    trade_id = evaluator.record_trade_result(
+        strategy_tag=body.strategy_tag,
+        symbol=body.symbol,
+        side=body.side,
+        entry_price=body.entry_price,
+        exit_price=body.exit_price,
+        size_usdt=body.size_usdt,
+        market_condition=body.market_condition,
+    )
+    return {"recorded": True, "trade_id": trade_id}
+
+
+# ── Audit ─────────────────────────────────────────────────────────────────────
+
+@app.get("/audit/report")
+def audit_report():
+    audit: AuditEngine = _state["audit"]
+    return audit.generate_audit_report()
+
+
+@app.get("/audit/verify")
+def audit_verify():
+    audit: AuditEngine = _state["audit"]
+    report = audit.generate_audit_report()
+    integrity_hash = report["integrity_hash"]
+    verified = audit.verify_integrity(integrity_hash)
+    return {"verified": verified, "hash": integrity_hash}
+
+
+# ── Reports ───────────────────────────────────────────────────────────────────
+
+class SendReportRequest(BaseModel):
+    type: str  # "daily" | "weekly" | "monthly"
+
+
+@app.get("/report/daily")
+def report_daily():
+    reporter: ReportGenerator = _state["reporter"]
+    return {"report": reporter.generate_daily_report()}
+
+
+@app.get("/report/weekly")
+def report_weekly():
+    reporter: ReportGenerator = _state["reporter"]
+    return {"report": reporter.generate_weekly_report()}
+
+
+@app.get("/report/monthly")
+def report_monthly():
+    reporter: ReportGenerator = _state["reporter"]
+    return {"report": reporter.generate_monthly_report()}
+
+
+@app.post("/report/send")
+def report_send(body: SendReportRequest):
+    reporter: ReportGenerator = _state["reporter"]
+    t = body.type.lower()
+    if t == "daily":
+        sent = reporter.send_daily_report()
+    elif t == "weekly":
+        sent = reporter.send_weekly_report()
+    elif t == "monthly":
+        sent = reporter.send_monthly_report()
+    else:
+        raise HTTPException(400, f"Unknown report type '{body.type}'. Use daily, weekly, or monthly.")
+    return {"sent": sent, "type": t}