rqfc-dev 1.0.0__py3-none-any.whl

rqfc/__init__.py

@@ -0,0 +1,110 @@
+# rqfc — RQFC fund trading client
+#
+# A thin, authenticated client for the RQFC trading backend. Traders log in with
+# credentials or an API key issued by an admin; the backend holds each pod's
+# Alpaca keys and submits trades on their behalf. No Alpaca keys ever touch this
+# client.
+#
+# Trader usage:
+#   import rqfc
+#   rqfc.login("alice@example.com", "password")
+#   # or: rqfc.login(api_key="rqfc_...")
+#   acct = rqfc.pod("Alpha Equities")   # a pod you're assigned to
+#   acct.buy("AAPL", 10)
+#   acct.positions()
+#   acct.sync()                          # refresh the dashboard
+#
+# Admin usage:
+#   rqfc.login("admin@example.com", "password")
+#   admin = rqfc.admin()
+#   pod = admin.create_pod("Vol Arb", "options", capital=100000,
+#                          alpaca_api_key="PK...", alpaca_api_secret="...")
+#   admin.add_trader(pod["id"], trader_id, role="trader")
+#   admin.allocate_capital(pod["id"], 150000)
+from __future__ import annotations
+
+import os
+
+from ._session import Session
+from .client import Account
+from .admin import Admin
+
+__version__ = "1.0.0"
+DEFAULT_BACKEND_URL = "https://fund-tkb1.onrender.com"
+
+_session: Session | None = None
+
+
+def configure(backend_url: str = None) -> Session:
+    """Set backend connection details.
+
+    Defaults to RQFC_BACKEND_URL, then the production RQFC API. Local dev can
+    pass backend_url="http://localhost:8000".
+    """
+    global _session
+    backend_url = backend_url or os.environ.get("RQFC_BACKEND_URL", DEFAULT_BACKEND_URL)
+    _session = Session(backend_url)
+    return _session
+
+
+def login(email: str = None, password: str = None, *, api_key: str = None,
+          backend_url: str = None) -> dict:
+    """Authenticate and start a session. Returns your profile."""
+    sess = configure(backend_url)
+    if api_key:
+        if email or password:
+            raise ValueError("Use either email/password or api_key, not both.")
+        sess.use_api_key(api_key)
+    else:
+        if not email or not password:
+            raise ValueError("Call rqfc.login(email, password) or rqfc.login(api_key='rqfc_...').")
+        profile = sess.login(email, password)
+        if profile:
+            me = profile
+            tag = " (admin)" if me.get("is_admin") else ""
+            print(
+                f"Logged in as {me['display_name']}{tag}. "
+                f"Pods: {[p['pods']['name'] for p in me.get('pods', [])] or 'none assigned'}"
+            )
+            return me
+
+    me = sess.get("/me")
+    tag = " (admin)" if me.get("is_admin") else ""
+    print(f"Logged in as {me['display_name']}{tag}. Pods: {[p['pods']['name'] for p in me['pods']] or 'none assigned'}")
+    return me
+
+
+def _require_session() -> Session:
+    if _session is None or not _session.access_token:
+        raise RuntimeError(
+            "Not logged in. Call rqfc.login(email, password) or "
+            "rqfc.login(api_key='rqfc_...') first."
+        )
+    return _session
+
+
+def pod(name_or_id: str) -> Account:
+    """Select a pod to trade, by name or id."""
+    return Account(_require_session(), name_or_id)
+
+
+def admin() -> Admin:
+    """Get the admin interface (requires an admin account)."""
+    return Admin(_require_session())
+
+
+def whoami() -> dict:
+    """Your profile and pod assignments."""
+    return _require_session().get("/me")
+
+
+__all__ = [
+    "DEFAULT_BACKEND_URL",
+    "configure",
+    "login",
+    "pod",
+    "admin",
+    "whoami",
+    "Account",
+    "Admin",
+]

rqfc/_session.py

@@ -0,0 +1,72 @@
+"""Authenticated HTTP session against the RQFC backend.
+
+The backend owns auth, authorization, and Alpaca credentials. This client stores
+only a backend-issued token or trader API key and sends it as bearer auth.
+"""
+import re
+
+import requests
+
+_UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.I)
+
+
+def looks_like_uuid(value: str) -> bool:
+    return bool(value and _UUID_RE.match(str(value)))
+
+
+class Session:
+    def __init__(self, backend_url: str):
+        self.backend_url = backend_url.rstrip("/")
+        self.access_token = None
+        self.profile = None
+
+    def login(self, email: str, password: str) -> dict:
+        r = requests.post(
+            f"{self.backend_url}/auth/login",
+            json={"email": email, "password": password},
+            timeout=30,
+        )
+        if r.status_code != 200:
+            raise RuntimeError(f"Login failed [{r.status_code}]: {r.text}")
+        data = r.json()
+        self.access_token = data["token"]
+        self.profile = data.get("profile")
+        return self.profile or {}
+
+    def use_api_key(self, api_key: str) -> None:
+        if not api_key:
+            raise ValueError("api_key is required.")
+        self.access_token = api_key
+        self.profile = None
+
+    # ── HTTP helpers ─────────────────────────────────────────────────────────
+
+    def _headers(self) -> dict:
+        if not self.access_token:
+            raise RuntimeError(
+                "Not logged in. Call rqfc.login(email, password) or "
+                "rqfc.login(api_key='rqfc_...') first."
+            )
+        return {"Authorization": f"Bearer {self.access_token}"}
+
+    def get(self, path: str, params: dict = None):
+        return self._handle(requests.get(
+            f"{self.backend_url}{path}", headers=self._headers(), params=params, timeout=60))
+
+    def post(self, path: str, json: dict = None):
+        return self._handle(requests.post(
+            f"{self.backend_url}{path}", headers=self._headers(), json=json, timeout=60))
+
+    def delete(self, path: str, json: dict = None):
+        return self._handle(requests.delete(
+            f"{self.backend_url}{path}", headers=self._headers(), json=json, timeout=60))
+
+    @staticmethod
+    def _handle(r: requests.Response):
+        if r.status_code >= 400:
+            try:
+                detail = r.json().get("detail", r.text)
+            except Exception:
+                detail = r.text
+            raise RuntimeError(f"[{r.status_code}] {detail}")
+        return r.json() if r.content else None

rqfc/admin.py

@@ -0,0 +1,58 @@
+"""Admin operations — manage pods, traders, capital. Admins only.
+
+All calls hit the backend's /admin endpoints, which re-check is_admin server-side.
+"""
+from ._session import Session
+
+
+class Admin:
+    def __init__(self, session: Session):
+        self._s = session
+        me = self._s.get("/me")
+        if not me.get("is_admin"):
+            raise PermissionError("This account does not have admin access.")
+
+    # ── Pods ─────────────────────────────────────────────────────────────────
+
+    def create_pod(self, name, asset_class, *, benchmark_symbol="SPY", description=None,
+                   capital=0, alpaca_api_key=None, alpaca_api_secret=None,
+                   alpaca_account_id=None) -> dict:
+        """Create a pod, optionally attaching its Alpaca paper-account keys."""
+        return self._s.post("/admin/pods", {
+            "name": name,
+            "asset_class": asset_class,
+            "benchmark_symbol": benchmark_symbol,
+            "description": description,
+            "allocated_capital": capital,
+            "alpaca_api_key": alpaca_api_key,
+            "alpaca_api_secret": alpaca_api_secret,
+            "alpaca_account_id": alpaca_account_id,
+        })
+
+    def set_alpaca(self, pod_id, *, api_key=None, api_secret=None, account_id=None) -> dict:
+        """Attach or update a pod's Alpaca credentials."""
+        return self._s.post(f"/admin/pods/{pod_id}/alpaca", {
+            "alpaca_api_key": api_key,
+            "alpaca_api_secret": api_secret,
+            "alpaca_account_id": account_id,
+        })
+
+    def allocate_capital(self, pod_id, amount, note=None) -> dict:
+        """Set a pod's allocated capital (logged to the audit trail)."""
+        return self._s.post(f"/admin/pods/{pod_id}/capital", {"amount": amount, "note": note})
+
+    # ── Memberships ──────────────────────────────────────────────────────────
+
+    def list_traders(self) -> list:
+        """All registered traders (id, display_name, is_admin)."""
+        return self._s.get("/admin/traders")
+
+    def add_trader(self, pod_id, trader_id, role="trader") -> dict:
+        """Assign a trader to a pod. role: 'trader' or 'pm'."""
+        return self._s.post("/admin/memberships",
+                            {"pod_id": pod_id, "trader_id": trader_id, "role": role})
+
+    def remove_trader(self, pod_id, trader_id) -> dict:
+        """Remove a trader from a pod."""
+        return self._s.delete("/admin/memberships",
+                             {"pod_id": pod_id, "trader_id": trader_id, "role": "trader"})

rqfc/client.py

@@ -0,0 +1,86 @@
+"""The trader-facing Account object.
+
+Every method is an authenticated call to the backend, which holds the pod's
+Alpaca keys and submits on your behalf. You can only act on pods you're assigned
+to (admins can act on any pod).
+"""
+from ._session import Session, looks_like_uuid
+
+
+class Account:
+    """A pod you can trade. Obtain one via rqfc.pod(name_or_id)."""
+
+    def __init__(self, session: Session, pod_ref: str):
+        self._s = session
+        self.pod_id = self._resolve_pod(pod_ref)
+
+    def _resolve_pod(self, ref: str) -> str:
+        if looks_like_uuid(ref):
+            return ref
+        for p in self._s.get("/pods"):
+            if p["name"].lower() == str(ref).lower():
+                return p["id"]
+        raise ValueError(f"No pod named '{ref}'. Run rqfc.whoami() to see your pods.")
+
+    # ── Orders ───────────────────────────────────────────────────────────────
+
+    def _order(self, **kw):
+        return self._s.post("/orders", {"pod_id": self.pod_id, **kw})
+
+    def buy(self, symbol, qty, order_type="market", limit_price=None, time_in_force="day"):
+        """Buy shares. order_type: 'market' (default) or 'limit'."""
+        return self._order(symbol=symbol, side="buy", qty=qty, order_type=order_type,
+                           order_label=order_type, limit_price=limit_price,
+                           time_in_force=time_in_force)
+
+    def sell(self, symbol, qty, order_type="market", limit_price=None, time_in_force="day"):
+        """Sell shares you hold in the pod."""
+        return self._order(symbol=symbol, side="sell", qty=qty, order_type=order_type,
+                           order_label=order_type, limit_price=limit_price,
+                           time_in_force=time_in_force)
+
+    def short(self, symbol, qty, time_in_force="day"):
+        """Short sell. Close with cover()."""
+        return self._order(symbol=symbol, side="sell", qty=qty, order_label="short",
+                           time_in_force=time_in_force)
+
+    def cover(self, symbol, qty, time_in_force="day"):
+        """Buy back a short position."""
+        return self._order(symbol=symbol, side="buy", qty=qty, order_label="cover",
+                           time_in_force=time_in_force)
+
+    def dollar_buy(self, symbol, amount, time_in_force="day"):
+        """Buy by dollar amount, e.g. dollar_buy('AAPL', 5000)."""
+        return self._order(symbol=symbol, side="buy", notional=amount, order_label="dollar_buy",
+                           time_in_force=time_in_force)
+
+    def dollar_sell(self, symbol, amount, time_in_force="day"):
+        """Sell by dollar amount."""
+        return self._order(symbol=symbol, side="sell", notional=amount, order_label="dollar_sell",
+                           time_in_force=time_in_force)
+
+    def cancel(self, order_id):
+        """Cancel an open order by its Alpaca order id."""
+        return self._s.post("/orders/cancel", {"pod_id": self.pod_id, "order_id": order_id})
+
+    # ── Read ─────────────────────────────────────────────────────────────────
+
+    def account(self):
+        """Live equity, cash, and buying power for the pod."""
+        return self._s.get(f"/pods/{self.pod_id}/account")
+
+    def positions(self):
+        """Live open positions for the pod."""
+        return self._s.get(f"/pods/{self.pod_id}/positions")
+
+    def price(self, symbol):
+        """Latest trade price."""
+        return self._s.get("/market/price", {"symbol": symbol, "pod_id": self.pod_id})
+
+    def bars(self, symbol, days=30):
+        """Daily OHLCV bars."""
+        return self._s.get("/market/bars", {"symbol": symbol, "pod_id": self.pod_id, "days": days})
+
+    def sync(self):
+        """Pull the pod's positions + NAV from Alpaca into the dashboard."""
+        return self._s.post(f"/sync/{self.pod_id}")

rqfc_dev-1.0.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: rqfc-dev
+Version: 1.0.0
+Summary: Thin client for the RQFC fund trading backend
+Author: RQFC
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+
+# rqfc
+
+Thin Python client for the RQFC fund trading backend.
+
+Traders log in with credentials or an API key issued by an admin. The backend
+owns authentication, permissions, and each pod's Alpaca credentials, then
+submits trades on the trader's behalf. **No Alpaca keys or Supabase settings
+ever touch this client**. A pod is one Alpaca account; several traders share a
+pod; admins can trade any pod and manage capital/membership.
+
+See `../docs/ARCHITECTURE.md` and `../docs/RUNBOOK.md` for the full system.
+
+## Install
+From GitHub:
+
+```bash
+pip install git+https://github.com/Rutgers-Quant-Finance-Club/fund.git
+```
+
+After publishing to PyPI, this becomes:
+
+```bash
+pip install rqfc
+```
+
+For local package development from this repo:
+```bash
+pip install -e .
+```
+
+## Trader Login
+By default, `rqfc` talks to the deployed RQFC API:
+
+```text
+https://fund-tkb1.onrender.com
+```
+
+Admins issue either email/password credentials or a trader API key. Traders do
+not need to configure Supabase or Alpaca.
+
+Email/password login:
+```python
+import rqfc
+
+rqfc.login("alice@example.com", "password")
+```
+
+API key login, useful for scripts and strategy runners:
+```python
+import rqfc
+
+rqfc.login(api_key="rqfc_...")
+```
+
+## Local Dev Override
+To test against a local or staging backend, use `RQFC_BACKEND_URL`:
+```bash
+export RQFC_BACKEND_URL=http://localhost:8000
+```
+
+Or pass it directly:
+```python
+import rqfc
+
+rqfc.login("alice@example.com", "password", backend_url="http://localhost:8000")
+```
+
+## Trader Usage
+```python
+import rqfc
+
+rqfc.login(api_key="rqfc_...")
+
+rqfc.whoami()                 # your profile + assigned pods
+
+acct = rqfc.pod("Alpha Equities")   # by name or id; must be assigned
+acct.buy("AAPL", 10)
+acct.sell("AAPL", 5)
+acct.short("TSLA", 3)
+acct.dollar_buy("NVDA", 5000)
+acct.account()                # live equity / cash / buying power
+acct.positions()              # live positions
+acct.price("AAPL")
+acct.sync()                   # refresh the dashboard (positions, NAV, metrics)
+```
+
+## Admin Usage
+```python
+rqfc.login("admin@example.com", "password")
+admin = rqfc.admin()
+
+pod = admin.create_pod("Vol Arb", "options", capital=100000,
+                       alpaca_api_key="PK...", alpaca_api_secret="...")
+admin.list_traders()
+admin.add_trader(pod["id"], trader_id, role="trader")
+admin.allocate_capital(pod["id"], 150000)
+admin.remove_trader(pod["id"], trader_id)
+```
+
+## Method Reference
+**Account** (`rqfc.pod(...)`): `buy`, `sell`, `short`, `cover`, `dollar_buy`,
+`dollar_sell`, `cancel`, `account`, `positions`, `price`, `bars`, `sync`.
+
+**Admin** (`rqfc.admin()`): `create_pod`, `set_alpaca`, `allocate_capital`,
+`list_traders`, `add_trader`, `remove_trader`.

rqfc_dev-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+rqfc/__init__.py,sha256=itistNFeXksxp70wqc_iJz6DaeiElyPYU2glimVGA6Y,3431
+rqfc/_session.py,sha256=gbDGGYg2zuUjCcpW6TTlnxI3IKt1l1kRHecJrowM4fs,2669
+rqfc/admin.py,sha256=575p0b0TH21avTEnHvUKY3ZsNKkIFv6uYa0KBh1UjgU,2782
+rqfc/client.py,sha256=VmE9EpufTrUI4CD8Ep8uXwRHcS6OEiF0cU4E32EiN3k,4030
+rqfc_dev-1.0.0.dist-info/METADATA,sha256=DxrNSwXaJ4R3ANtNYmyBixU88MHqF47FTcDi8iVQSRw,2902
+rqfc_dev-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rqfc_dev-1.0.0.dist-info/top_level.txt,sha256=5H5kAXL053EVccroS7Hy14k4NBfiie_H14ZoeIb4dVo,5
+rqfc_dev-1.0.0.dist-info/RECORD,,

rqfc_dev-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rqfc_dev-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rqfc