tasilab 0.1.0__tar.gz

tasilab-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: tasilab
+Version: 0.1.0
+Summary: Tasi Lab is the first API-native paper trading sandbox for the Saudi Stock Exchange, empowering developers to build, test, and deploy AI-driven trading strategies with zero financial risk.
+Author-email: Jafar Albinmousa <binmousa@gmail.com>
+License: Proprietary
+Project-URL: Homepage, https://tasilab.com
+Project-URL: Documentation, https://api.tasilab.com/docs
+Project-URL: Issues, https://github.com/jafaralbinmousa/tasilab/issues
+Project-URL: Source, https://github.com/jafaralbinmousa/tasilab
+Keywords: tasi,tadawul,saudi,stock,exchange,paper-trading,backtesting,trading,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25.0
+
+# Tasi Lab Python SDK
+
+Tasi Lab is the first API-native paper trading sandbox for the Saudi Stock Exchange, empowering developers to build, test, and deploy AI-driven trading strategies with zero financial risk.
+
+This package is the official Python client. Use it to pull historical TASI data, log backtests as experiments, and view results in the Tasi Lab dashboard.
+
+- Dashboard: <https://tasilab.com>
+- API docs: <https://api.tasilab.com/docs>
+
+## Install
+
+```bash
+pip install tasilab
+```
+
+## Quick start
+
+```python
+from tasilab import TasiLab
+
+tasi = TasiLab(api_key="YOUR_API_KEY")
+
+# 1. Pull historical bars (Tasi Lab caches them for you)
+hist = tasi.get_historical("1120", "2024-01-01", "2025-12-31")
+
+# 2. Run your strategy locally → list of trade dicts
+trades = my_strategy(hist["bars"])
+
+# 3. Log the run as a Tasi Lab experiment (auto-seals on exit)
+with tasi.create_experiment(
+    name="MACD 12/26/9 on Al Rajhi",
+    symbol="1120",
+    start_date="2024-01-01",
+    end_date="2025-12-31",
+    parameters={"fast": 12, "slow": 26, "signal": 9},
+) as exp:
+    exp.log_trades(trades)
+    exp.log_metrics({"total_return_sar": 439.64, "win_rate": 0.412})
+```
+
+The `with` block automatically marks the experiment `completed` on clean exit and `failed` if an exception propagates, so experiments never get stuck in `running`.
+
+## Paper trading
+
+The SDK also supports live paper-trading against the simulated exchange:
+
+```python
+order = tasi.buy("2222", quantity=100)
+portfolio = tasi.portfolio()
+```
+
+See <https://tasilab.com> for the full surface.
+
+## License
+
+Proprietary — see <https://tasilab.com> for terms.

tasilab-0.1.0/README.md

@@ -0,0 +1,56 @@
+# Tasi Lab Python SDK
+
+Tasi Lab is the first API-native paper trading sandbox for the Saudi Stock Exchange, empowering developers to build, test, and deploy AI-driven trading strategies with zero financial risk.
+
+This package is the official Python client. Use it to pull historical TASI data, log backtests as experiments, and view results in the Tasi Lab dashboard.
+
+- Dashboard: <https://tasilab.com>
+- API docs: <https://api.tasilab.com/docs>
+
+## Install
+
+```bash
+pip install tasilab
+```
+
+## Quick start
+
+```python
+from tasilab import TasiLab
+
+tasi = TasiLab(api_key="YOUR_API_KEY")
+
+# 1. Pull historical bars (Tasi Lab caches them for you)
+hist = tasi.get_historical("1120", "2024-01-01", "2025-12-31")
+
+# 2. Run your strategy locally → list of trade dicts
+trades = my_strategy(hist["bars"])
+
+# 3. Log the run as a Tasi Lab experiment (auto-seals on exit)
+with tasi.create_experiment(
+    name="MACD 12/26/9 on Al Rajhi",
+    symbol="1120",
+    start_date="2024-01-01",
+    end_date="2025-12-31",
+    parameters={"fast": 12, "slow": 26, "signal": 9},
+) as exp:
+    exp.log_trades(trades)
+    exp.log_metrics({"total_return_sar": 439.64, "win_rate": 0.412})
+```
+
+The `with` block automatically marks the experiment `completed` on clean exit and `failed` if an exception propagates, so experiments never get stuck in `running`.
+
+## Paper trading
+
+The SDK also supports live paper-trading against the simulated exchange:
+
+```python
+order = tasi.buy("2222", quantity=100)
+portfolio = tasi.portfolio()
+```
+
+See <https://tasilab.com> for the full surface.
+
+## License
+
+Proprietary — see <https://tasilab.com> for terms.

tasilab-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tasilab"
+version = "0.1.0"
+description = "Tasi Lab is the first API-native paper trading sandbox for the Saudi Stock Exchange, empowering developers to build, test, and deploy AI-driven trading strategies with zero financial risk."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "Jafar Albinmousa", email = "binmousa@gmail.com" }]
+keywords = ["tasi", "tadawul", "saudi", "stock", "exchange", "paper-trading", "backtesting", "trading", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["httpx>=0.25.0"]
+
+[project.urls]
+Homepage = "https://tasilab.com"
+Documentation = "https://api.tasilab.com/docs"
+Issues = "https://github.com/jafaralbinmousa/tasilab/issues"
+Source = "https://github.com/jafaralbinmousa/tasilab"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tasilab*"]

tasilab-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tasilab-0.1.0/tasilab/__init__.py

@@ -0,0 +1,6 @@
+"""Tasi Lab Python SDK — paper trading sandbox for the Saudi Exchange."""
+
+from tasilab.client import Experiment, TasiLab
+
+__all__ = ["TasiLab", "Experiment"]
+__version__ = "0.1.0"

tasilab-0.1.0/tasilab/client.py

@@ -0,0 +1,662 @@
+"""TasiLab SDK client — synchronous Python wrapper for the Tasi Lab API.
+
+Usage:
+    from tasilab import TasiLab
+
+    tasi = TasiLab(api_key="your-api-key")
+    quote = tasi.get_quote("2222")
+    order = tasi.buy("2222", quantity=100)
+    portfolio = tasi.portfolio()
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+DEFAULT_BASE_URL = "https://api.tasilab.com"
+
+
+class TasiLabError(Exception):
+    """Raised when the Tasi Lab API returns an error."""
+
+    def __init__(self, status_code: int, error: str, message: str) -> None:
+        self.status_code = status_code
+        self.error = error
+        self.message = message
+        super().__init__(f"[{status_code}] {error}: {message}")
+
+
+class TasiLab:
+    """Synchronous client for the Tasi Lab paper trading API.
+
+    Args:
+        api_key: Your API key from POST /v1/auth/register.
+        base_url: API base URL. Defaults to https://api.tasilab.com.
+        timeout: Request timeout in seconds. Defaults to 30.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={"X-API-Key": api_key},
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> TasiLab:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict | list:
+        response = self._client.request(method, path, **kwargs)
+        if response.status_code >= 400:
+            body = response.json()
+            detail = body.get("detail", body)
+            if isinstance(detail, dict):
+                raise TasiLabError(
+                    status_code=response.status_code,
+                    error=detail.get("error", "UNKNOWN"),
+                    message=detail.get("message", str(detail)),
+                )
+            raise TasiLabError(
+                status_code=response.status_code,
+                error="UNKNOWN",
+                message=str(detail),
+            )
+        return response.json()
+
+    # ── Auth ──────────────────────────────────────────────
+
+    @staticmethod
+    def register(
+        email: str,
+        password: str,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> dict:
+        """Register a new account and get an API key.
+
+        Returns:
+            {"id": "...", "email": "...", "api_key": "...", "created_at": "..."}
+        """
+        response = httpx.post(
+            f"{base_url}/v1/auth/register",
+            json={"email": email, "password": password},
+        )
+        if response.status_code >= 400:
+            body = response.json()
+            detail = body.get("detail", body)
+            if isinstance(detail, dict):
+                raise TasiLabError(
+                    status_code=response.status_code,
+                    error=detail.get("error", "UNKNOWN"),
+                    message=detail.get("message", str(detail)),
+                )
+            raise TasiLabError(response.status_code, "UNKNOWN", str(detail))
+        return response.json()
+
+    # ── Market Data ───────────────────────────────────────
+
+    def get_quote(self, symbol: str) -> dict:
+        """Get a real-time quote for a TASI symbol.
+
+        Args:
+            symbol: TASI symbol (e.g. "2222" for Aramco).
+
+        Returns:
+            Quote dict with price, change, volume, bid, ask, etc.
+        """
+        return self._request("GET", f"/v1/market/quote/{symbol}")
+
+    def get_quotes(self, symbols: list[str]) -> list[dict]:
+        """Get quotes for multiple symbols.
+
+        Args:
+            symbols: List of TASI symbols.
+
+        Returns:
+            List of quote dicts.
+        """
+        return self._request(
+            "GET", "/v1/market/quotes", params={"symbols": ",".join(symbols)}
+        )
+
+    def market_status(self) -> dict:
+        """Get TASI market status — index value, advancing/declining, mood.
+
+        Returns:
+            MarketStatus dict.
+        """
+        return self._request("GET", "/v1/market/status")
+
+    # ── Orders ────────────────────────────────────────────
+
+    def place_order(
+        self,
+        symbol: str,
+        side: str,
+        order_type: str,
+        quantity: int,
+        limit_price: float | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        """Place a market or limit order.
+
+        Args:
+            symbol: TASI symbol.
+            side: "BUY" or "SELL".
+            order_type: "MARKET" or "LIMIT".
+            quantity: Number of shares.
+            limit_price: Required for LIMIT orders.
+            idempotency_key: Optional UUID for idempotent submission.
+
+        Returns:
+            Order dict with status, filled_price, trades, etc.
+        """
+        body: dict[str, Any] = {
+            "symbol": symbol,
+            "side": side,
+            "order_type": order_type,
+            "quantity": quantity,
+        }
+        if limit_price is not None:
+            body["limit_price"] = limit_price
+        if idempotency_key is not None:
+            body["idempotency_key"] = idempotency_key
+        return self._request("POST", "/v1/orders", json=body)
+
+    def buy(
+        self,
+        symbol: str,
+        quantity: int,
+        limit_price: float | None = None,
+    ) -> dict:
+        """Shortcut: place a BUY order (market if no limit_price, limit otherwise).
+
+        Args:
+            symbol: TASI symbol.
+            quantity: Number of shares.
+            limit_price: If set, places a LIMIT order.
+
+        Returns:
+            Order dict.
+        """
+        order_type = "LIMIT" if limit_price is not None else "MARKET"
+        return self.place_order(symbol, "BUY", order_type, quantity, limit_price)
+
+    def sell(
+        self,
+        symbol: str,
+        quantity: int,
+        limit_price: float | None = None,
+    ) -> dict:
+        """Shortcut: place a SELL order.
+
+        Args:
+            symbol: TASI symbol.
+            quantity: Number of shares.
+            limit_price: If set, places a LIMIT order.
+
+        Returns:
+            Order dict.
+        """
+        order_type = "LIMIT" if limit_price is not None else "MARKET"
+        return self.place_order(symbol, "SELL", order_type, quantity, limit_price)
+
+    def get_orders(
+        self,
+        symbol: str | None = None,
+        status: str | None = None,
+        limit: int = 50,
+    ) -> list[dict]:
+        """List orders.
+
+        Args:
+            symbol: Filter by symbol.
+            status: Filter by status (PENDING, FILLED, CANCELLED, REJECTED).
+            limit: Max results (default 50, max 100).
+
+        Returns:
+            List of order dicts.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if symbol:
+            params["symbol"] = symbol
+        if status:
+            params["status"] = status
+        return self._request("GET", "/v1/orders", params=params)
+
+    def get_order(self, order_id: str) -> dict:
+        """Get a specific order by ID.
+
+        Args:
+            order_id: UUID of the order.
+
+        Returns:
+            Order dict.
+        """
+        return self._request("GET", f"/v1/orders/{order_id}")
+
+    # ── Portfolio ─────────────────────────────────────────
+
+    def portfolio(self) -> dict:
+        """Get portfolio summary with total return.
+
+        Returns:
+            Dict with portfolio, total_value, total_return, total_return_pct.
+        """
+        return self._request("GET", "/v1/portfolio")
+
+    def positions(self) -> list[dict]:
+        """Get all open positions with live values.
+
+        Returns:
+            List of position dicts.
+        """
+        return self._request("GET", "/v1/portfolio/positions")
+
+    def trades(
+        self,
+        symbol: str | None = None,
+        limit: int = 50,
+    ) -> list[dict]:
+        """Get trade history.
+
+        Args:
+            symbol: Filter by symbol.
+            limit: Max results.
+
+        Returns:
+            List of trade dicts.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if symbol:
+            params["symbol"] = symbol
+        return self._request("GET", "/v1/portfolio/trades", params=params)
+
+    def snapshots(self, limit: int = 30) -> list[dict]:
+        """Get daily portfolio value snapshots.
+
+        Args:
+            limit: Max results.
+
+        Returns:
+            List of snapshot dicts.
+        """
+        return self._request("GET", "/v1/portfolio/snapshots", params={"limit": limit})
+
+    # ── Analytics ─────────────────────────────────────────
+
+    def performance(self) -> dict:
+        """Get portfolio performance metrics.
+
+        Returns:
+            Dict with total_return, win_rate, trade stats, etc.
+        """
+        return self._request("GET", "/v1/analytics/performance")
+
+    def daily_returns(self, limit: int = 30) -> list[dict]:
+        """Get daily portfolio returns.
+
+        Args:
+            limit: Number of days.
+
+        Returns:
+            List of daily return dicts.
+        """
+        return self._request(
+            "GET", "/v1/analytics/daily-returns", params={"limit": limit}
+        )
+
+    # ── Historical Data ──────────────────────────────────
+
+    def get_historical(self, symbol: str, start: str, end: str) -> dict:
+        """Get historical OHLCV data for a TASI symbol.
+
+        Args:
+            symbol: TASI symbol (e.g. "2222").
+            start: Start date, YYYY-MM-DD.
+            end: End date, YYYY-MM-DD.
+
+        Returns:
+            Dict with symbol, start, end, count, and bars list.
+        """
+        return self._request(
+            "GET",
+            f"/v1/historical/{symbol}",
+            params={"start": start, "end": end},
+        )
+
+    # ── Experiments ──────────────────────────────────────
+
+    def create_experiment(
+        self,
+        name: str,
+        symbol: str,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        description: str | None = None,
+        parameters: dict | None = None,
+        experiment_type: str = "technical_indicator",
+        ml_model_config: dict | None = None,
+        ml_dataset_config: dict | None = None,
+    ) -> "Experiment":
+        """Create a new backtest experiment.
+
+        Args:
+            name: Strategy label (e.g. "SMA Crossover").
+            symbol: TASI symbol (e.g. "2222") or "MULTI" for multi-symbol.
+            start_date: Backtest start date, YYYY-MM-DD.
+            end_date: Backtest end date, YYYY-MM-DD.
+            description: Free-text description.
+            parameters: Strategy parameters dict.
+            experiment_type: "technical_indicator" (default) or "machine_learning".
+            ml_model_config: ML model spec. Required when experiment_type is
+                "machine_learning". Must include "framework" and "model_type";
+                extra keys (hyperparameters, features, etc.) allowed.
+            ml_dataset_config: ML dataset split. Required when experiment_type is
+                "machine_learning". Shape:
+                {"train": {"start": "YYYY-MM-DD", "end": "YYYY-MM-DD"},
+                 "test": {...}, "val": {...}}  (val optional).
+
+        Returns:
+            Experiment helper object for fluent logging.
+        """
+        body: dict[str, Any] = {
+            "name": name,
+            "symbol": symbol,
+            "experiment_type": experiment_type,
+        }
+        if start_date is not None:
+            body["start_date"] = start_date
+        if end_date is not None:
+            body["end_date"] = end_date
+        if description is not None:
+            body["description"] = description
+        if parameters is not None:
+            body["parameters"] = parameters
+        if ml_model_config is not None:
+            body["ml_model_config"] = ml_model_config
+        if ml_dataset_config is not None:
+            body["ml_dataset_config"] = ml_dataset_config
+        data = self._request("POST", "/v1/experiments", json=body)
+        return Experiment(self, data)
+
+    def create_ml_experiment(
+        self,
+        name: str,
+        symbol: str,
+        framework: str,
+        model_type: str,
+        train: tuple[str, str],
+        test: tuple[str, str],
+        val: tuple[str, str] | None = None,
+        description: str | None = None,
+        parameters: dict | None = None,
+        **model_extra: Any,
+    ) -> "Experiment":
+        """Create an ML experiment — convenience wrapper over create_experiment.
+
+        Args:
+            name: Experiment label.
+            symbol: TASI symbol or "MULTI".
+            framework: e.g. "sklearn", "xgboost", "pytorch".
+            model_type: e.g. "RandomForestClassifier".
+            train: (start, end) dates for the training set, YYYY-MM-DD.
+            test: (start, end) dates for the test set.
+            val: Optional (start, end) dates for the validation set.
+            description, parameters: as in create_experiment.
+            **model_extra: arbitrary extra keys merged into ml_model_config
+                (e.g. hyperparameters={...}, features=[...]).
+        """
+        model_cfg: dict[str, Any] = {"framework": framework, "model_type": model_type}
+        model_cfg.update(model_extra)
+
+        dataset_cfg: dict[str, Any] = {
+            "train": {"start": train[0], "end": train[1]},
+            "test": {"start": test[0], "end": test[1]},
+        }
+        if val is not None:
+            dataset_cfg["val"] = {"start": val[0], "end": val[1]}
+
+        return self.create_experiment(
+            name=name,
+            symbol=symbol,
+            description=description,
+            parameters=parameters,
+            experiment_type="machine_learning",
+            ml_model_config=model_cfg,
+            ml_dataset_config=dataset_cfg,
+        )
+
+    def list_experiments(
+        self,
+        status: str | None = None,
+        symbol: str | None = None,
+        experiment_type: str | None = None,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> dict:
+        """List your experiments.
+
+        Args:
+            status: Filter by status (running, completed, failed).
+            symbol: Filter by symbol.
+            limit: Max results per page.
+            offset: Pagination offset.
+
+        Returns:
+            Dict with experiments list, total, limit, offset.
+        """
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if status:
+            params["status"] = status
+        if symbol:
+            params["symbol"] = symbol
+        if experiment_type:
+            params["experiment_type"] = experiment_type
+        return self._request("GET", "/v1/experiments", params=params)
+
+    def get_experiment(self, experiment_id: str) -> "Experiment":
+        """Get an experiment by ID.
+
+        Args:
+            experiment_id: UUID of the experiment.
+
+        Returns:
+            Experiment helper object.
+        """
+        data = self._request("GET", f"/v1/experiments/{experiment_id}")
+        return Experiment(self, data)
+
+    def compare_experiments(self, experiment_ids: list[str]) -> dict:
+        """Compare two or more experiments side-by-side.
+
+        Args:
+            experiment_ids: List of experiment UUIDs (2–5).
+
+        Returns:
+            Dict with experiments list containing metrics for comparison.
+        """
+        return self._request(
+            "GET",
+            "/v1/experiments/compare",
+            params={"ids": ",".join(experiment_ids)},
+        )
+
+
+class Experiment:
+    """Helper class wrapping an experiment for fluent logging.
+
+    Usage (context manager — recommended):
+        with tasi.create_experiment(name="SMA Crossover", symbol="2222") as exp:
+            exp.log_params({"fast": 10, "slow": 50})
+            exp.log_trades([...])
+            exp.log_metrics({"win_rate": 0.62})
+        # auto-sealed as completed on clean exit, failed on exception
+
+    Usage (manual):
+        exp = tasi.create_experiment(name="SMA Crossover", symbol="2222")
+        exp.log_metrics({"win_rate": 0.62})
+        exp.end()
+    """
+
+    def __init__(self, client: TasiLab, data: dict) -> None:
+        self._client = client
+        self.data = data
+        self.id: str = data["id"]
+
+    def __enter__(self) -> Experiment:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        if exc_type is not None:
+            self.fail()
+        else:
+            self.end()
+
+    def log_params(self, params: dict) -> dict:
+        """Log or merge strategy parameters.
+
+        Args:
+            params: Key-value parameter dict.
+
+        Returns:
+            Updated experiment dict.
+        """
+        self.data = self._client._request(
+            "POST",
+            f"/v1/experiments/{self.id}/params",
+            json={"parameters": params},
+        )
+        return self.data
+
+    def log_trade(
+        self,
+        side: str,
+        symbol: str,
+        price: float,
+        quantity: int,
+        date: str,
+        pnl: float | None = None,
+        commission: float = 0,
+        metadata: dict | None = None,
+    ) -> list[dict]:
+        """Log a single trade.
+
+        Args:
+            side: "BUY" or "SELL".
+            symbol: TASI symbol.
+            price: Execution price.
+            quantity: Number of shares.
+            date: Trade date, YYYY-MM-DD.
+            pnl: Optional per-trade P&L.
+            commission: Trading commission (default 0).
+            metadata: Optional per-trade metadata dict.
+
+        Returns:
+            List containing the created trade dict.
+        """
+        trade: dict[str, Any] = {
+            "side": side,
+            "symbol": symbol,
+            "price": price,
+            "quantity": quantity,
+            "date": date,
+            "commission": commission,
+        }
+        if pnl is not None:
+            trade["pnl"] = pnl
+        if metadata:
+            trade["metadata"] = metadata
+        return self._client._request(
+            "POST",
+            f"/v1/experiments/{self.id}/trades",
+            json={"trades": [trade]},
+        )
+
+    def log_trades(self, trades: list[dict]) -> list[dict]:
+        """Log multiple trades in a batch.
+
+        Args:
+            trades: List of trade dicts (side, symbol, price, quantity, date, ...).
+
+        Returns:
+            List of created trade dicts.
+        """
+        return self._client._request(
+            "POST",
+            f"/v1/experiments/{self.id}/trades",
+            json={"trades": trades},
+        )
+
+    def log_metrics(self, metrics: dict) -> dict:
+        """Log or merge performance metrics.
+
+        Args:
+            metrics: Key-value metrics dict (e.g. {"win_rate": 0.62}).
+
+        Returns:
+            Updated experiment dict.
+        """
+        self.data = self._client._request(
+            "POST",
+            f"/v1/experiments/{self.id}/metrics",
+            json={"metrics": metrics},
+        )
+        return self.data
+
+    def end(self) -> dict:
+        """Mark experiment as completed.
+
+        Idempotent — returns current data if already sealed.
+        """
+        if self.data.get("status") in ("completed", "failed"):
+            return self.data
+        self.data = self._client._request(
+            "PATCH",
+            f"/v1/experiments/{self.id}",
+            json={"status": "completed"},
+        )
+        return self.data
+
+    def fail(self) -> dict:
+        """Mark experiment as failed.
+
+        Idempotent — returns current data if already sealed.
+        """
+        if self.data.get("status") in ("completed", "failed"):
+            return self.data
+        self.data = self._client._request(
+            "PATCH",
+            f"/v1/experiments/{self.id}",
+            json={"status": "failed"},
+        )
+        return self.data
+
+    def compare(self, other_id: str) -> dict:
+        """Compare this experiment with another.
+
+        Args:
+            other_id: UUID of the other experiment.
+
+        Returns:
+            Dict with both experiments' metrics for comparison.
+        """
+        return self._client.compare_experiments([self.id, other_id])
+
+    def delete(self) -> None:
+        """Delete this experiment and all its trades."""
+        self._client._request("DELETE", f"/v1/experiments/{self.id}")

tasilab-0.1.0/tasilab.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: tasilab
+Version: 0.1.0
+Summary: Tasi Lab is the first API-native paper trading sandbox for the Saudi Stock Exchange, empowering developers to build, test, and deploy AI-driven trading strategies with zero financial risk.
+Author-email: Jafar Albinmousa <binmousa@gmail.com>
+License: Proprietary
+Project-URL: Homepage, https://tasilab.com
+Project-URL: Documentation, https://api.tasilab.com/docs
+Project-URL: Issues, https://github.com/jafaralbinmousa/tasilab/issues
+Project-URL: Source, https://github.com/jafaralbinmousa/tasilab
+Keywords: tasi,tadawul,saudi,stock,exchange,paper-trading,backtesting,trading,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25.0
+
+# Tasi Lab Python SDK
+
+Tasi Lab is the first API-native paper trading sandbox for the Saudi Stock Exchange, empowering developers to build, test, and deploy AI-driven trading strategies with zero financial risk.
+
+This package is the official Python client. Use it to pull historical TASI data, log backtests as experiments, and view results in the Tasi Lab dashboard.
+
+- Dashboard: <https://tasilab.com>
+- API docs: <https://api.tasilab.com/docs>
+
+## Install
+
+```bash
+pip install tasilab
+```
+
+## Quick start
+
+```python
+from tasilab import TasiLab
+
+tasi = TasiLab(api_key="YOUR_API_KEY")
+
+# 1. Pull historical bars (Tasi Lab caches them for you)
+hist = tasi.get_historical("1120", "2024-01-01", "2025-12-31")
+
+# 2. Run your strategy locally → list of trade dicts
+trades = my_strategy(hist["bars"])
+
+# 3. Log the run as a Tasi Lab experiment (auto-seals on exit)
+with tasi.create_experiment(
+    name="MACD 12/26/9 on Al Rajhi",
+    symbol="1120",
+    start_date="2024-01-01",
+    end_date="2025-12-31",
+    parameters={"fast": 12, "slow": 26, "signal": 9},
+) as exp:
+    exp.log_trades(trades)
+    exp.log_metrics({"total_return_sar": 439.64, "win_rate": 0.412})
+```
+
+The `with` block automatically marks the experiment `completed` on clean exit and `failed` if an exception propagates, so experiments never get stuck in `running`.
+
+## Paper trading
+
+The SDK also supports live paper-trading against the simulated exchange:
+
+```python
+order = tasi.buy("2222", quantity=100)
+portfolio = tasi.portfolio()
+```
+
+See <https://tasilab.com> for the full surface.
+
+## License
+
+Proprietary — see <https://tasilab.com> for terms.

tasilab-0.1.0/tasilab.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+tasilab/__init__.py
+tasilab/client.py
+tasilab.egg-info/PKG-INFO
+tasilab.egg-info/SOURCES.txt
+tasilab.egg-info/dependency_links.txt
+tasilab.egg-info/requires.txt
+tasilab.egg-info/top_level.txt

tasilab-0.1.0/tasilab.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tasilab-0.1.0/tasilab.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.25.0

tasilab-0.1.0/tasilab.egg-info/top_level.txt

@@ -0,0 +1 @@
+tasilab