autobrain-sim 1.0.0__tar.gz

autobrain_sim-1.0.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

autobrain_sim-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+recursive-include examples *.py
+exclude *.ipynb
+recursive-exclude * __pycache__
+recursive-exclude * *.py[cod]

autobrain_sim-1.0.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: autobrain-sim
+Version: 1.0.0
+Summary: Python client for the WorldQuant Brain API
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Dynamic: license-file
+
+# AutoBrain Sim
+
+A lightweight Python client library for interacting with the [WorldQuant Brain](https://platform.worldquantbrain.com) platform API. Supports authentication, alpha simulation submission, and result retrieval.
+
+## Features
+
+- Multiple authentication methods (direct, credentials file, interactive prompt)
+- Submit alpha expressions for simulation
+- Poll for simulation completion automatically
+- Retrieve alpha details and PnL record sets
+
+## Install
+
+```bash
+pip install autobrain-sim
+```
+
+## Requirements
+
+- Python 3.7+
+- `requests`
+
+Install the dependency:
+
+```bash
+pip install requests
+```
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `brain_client.py` | Core client library (`BrainClient`, `SimulationResult`) |
+| `example.py` | Standalone usage example |
+| `main.ipynb` | Jupyter notebook walkthrough |
+
+## Quick Start
+
+### Authentication
+
+**Method 1 — Direct credentials**
+```python
+from brain_client import BrainClient
+
+client = BrainClient(email="your@email.com", password="yourpassword")
+client.authenticate()
+```
+
+**Method 2 — One-liner login**
+```python
+client = BrainClient.login("your@email.com", "yourpassword")
+```
+
+**Method 3 — Interactive prompt** (asks at runtime if no credentials are found)
+```python
+client = BrainClient()
+client.authenticate()
+```
+
+**Method 4 — Credentials file**
+
+Create `~/.brain_credentials` (or any path) as a JSON array:
+```json
+["your@email.com", "yourpassword"]
+```
+
+Then load it:
+```python
+client = BrainClient(credentials_file="~/.brain_credentials")
+client.authenticate()
+```
+
+> Credentials priority: direct args → `credentials_file` → `~/.brain_credentials` → interactive prompt.
+
+---
+
+### Simulate an Alpha
+
+```python
+sim = client.simulate(
+    expression="close / ts_mean(close, 20) - 1",
+    settings={
+        "region": "USA",
+        "universe": "TOP3000",
+        "neutralization": "SUBINDUSTRY",
+    }
+)
+
+result = sim.wait(verbose=True)   # blocks until done
+print("Alpha ID:", sim.alpha_id)
+```
+
+### Retrieve Results
+
+```python
+alpha = sim.get_alpha()
+print("Sharpe:", alpha["is"]["sharpe"])
+print("Fitness:", alpha["is"]["fitness"])
+
+pnl = sim.get_pnl()
+print(pnl)
+```
+
+---
+
+## API Reference
+
+### `BrainClient`
+
+| Method | Description |
+|--------|-------------|
+| `__init__(email, password, credentials_file)` | Initialize client with credentials |
+| `BrainClient.login(email, password)` | Create client and authenticate in one step |
+| `authenticate()` | Sign in and obtain a session token |
+| `simulate(expression, settings, ...)` | Submit an alpha for simulation; returns `SimulationResult` |
+| `get_alpha(alpha_id)` | Fetch alpha details by ID |
+| `get_pnl(alpha_id)` | Fetch PnL record set for an alpha |
+| `get_recordset(alpha_id, record_set_name)` | Fetch any named record set |
+
+#### Default Simulation Settings
+
+```python
+{
+    "instrumentType": "EQUITY",
+    "region": "USA",
+    "universe": "TOP3000",
+    "delay": 1,
+    "decay": 15,
+    "neutralization": "SUBINDUSTRY",
+    "truncation": 0.08,
+    "maxTrade": "ON",
+    "pasteurization": "ON",
+    "testPeriod": "P1Y6M",
+    "unitHandling": "VERIFY",
+    "nanHandling": "OFF",
+    "language": "FASTEXPR",
+}
+```
+
+Any key passed via `settings` overrides the default.
+
+---
+
+### `SimulationResult`
+
+Returned by `client.simulate()`.
+
+| Method | Description |
+|--------|-------------|
+| `wait(verbose=True)` | Poll until simulation completes; returns result JSON |
+| `get_alpha()` | Fetch full alpha details (call after `wait()`) |
+| `get_pnl(poll_interval)` | Fetch PnL record set (call after `wait()`) |
+
+| Attribute | Description |
+|-----------|-------------|
+| `alpha_id` | Alpha ID string (available after `wait()`) |
+| `progress_url` | URL used to poll simulation progress |
+
+---
+
+## Example
+
+```python
+from brain_client import BrainClient
+
+client = BrainClient.login()  # interactive prompt
+
+sim = client.simulate("close / ts_mean(close, 20) - 1")
+result = sim.wait(verbose=True)
+
+alpha = sim.get_alpha()
+print(f"Alpha ID : {sim.alpha_id}")
+print(f"Sharpe   : {alpha['is']['sharpe']}")
+print(f"Fitness  : {alpha['is']['fitness']}")
+```
+
+## Notes
+
+- The client uses HTTP Basic Auth to obtain a session token from the `/authentication` endpoint.
+- Polling respects the `Retry-After` response header returned by the Brain API.
+- Never commit your credentials to version control. Use `~/.brain_credentials` or environment variables instead.

autobrain_sim-1.0.0/README.md

@@ -0,0 +1,181 @@
+# AutoBrain Sim
+
+A lightweight Python client library for interacting with the [WorldQuant Brain](https://platform.worldquantbrain.com) platform API. Supports authentication, alpha simulation submission, and result retrieval.
+
+## Features
+
+- Multiple authentication methods (direct, credentials file, interactive prompt)
+- Submit alpha expressions for simulation
+- Poll for simulation completion automatically
+- Retrieve alpha details and PnL record sets
+
+## Install
+
+```bash
+pip install autobrain-sim
+```
+
+## Requirements
+
+- Python 3.7+
+- `requests`
+
+Install the dependency:
+
+```bash
+pip install requests
+```
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `brain_client.py` | Core client library (`BrainClient`, `SimulationResult`) |
+| `example.py` | Standalone usage example |
+| `main.ipynb` | Jupyter notebook walkthrough |
+
+## Quick Start
+
+### Authentication
+
+**Method 1 — Direct credentials**
+```python
+from brain_client import BrainClient
+
+client = BrainClient(email="your@email.com", password="yourpassword")
+client.authenticate()
+```
+
+**Method 2 — One-liner login**
+```python
+client = BrainClient.login("your@email.com", "yourpassword")
+```
+
+**Method 3 — Interactive prompt** (asks at runtime if no credentials are found)
+```python
+client = BrainClient()
+client.authenticate()
+```
+
+**Method 4 — Credentials file**
+
+Create `~/.brain_credentials` (or any path) as a JSON array:
+```json
+["your@email.com", "yourpassword"]
+```
+
+Then load it:
+```python
+client = BrainClient(credentials_file="~/.brain_credentials")
+client.authenticate()
+```
+
+> Credentials priority: direct args → `credentials_file` → `~/.brain_credentials` → interactive prompt.
+
+---
+
+### Simulate an Alpha
+
+```python
+sim = client.simulate(
+    expression="close / ts_mean(close, 20) - 1",
+    settings={
+        "region": "USA",
+        "universe": "TOP3000",
+        "neutralization": "SUBINDUSTRY",
+    }
+)
+
+result = sim.wait(verbose=True)   # blocks until done
+print("Alpha ID:", sim.alpha_id)
+```
+
+### Retrieve Results
+
+```python
+alpha = sim.get_alpha()
+print("Sharpe:", alpha["is"]["sharpe"])
+print("Fitness:", alpha["is"]["fitness"])
+
+pnl = sim.get_pnl()
+print(pnl)
+```
+
+---
+
+## API Reference
+
+### `BrainClient`
+
+| Method | Description |
+|--------|-------------|
+| `__init__(email, password, credentials_file)` | Initialize client with credentials |
+| `BrainClient.login(email, password)` | Create client and authenticate in one step |
+| `authenticate()` | Sign in and obtain a session token |
+| `simulate(expression, settings, ...)` | Submit an alpha for simulation; returns `SimulationResult` |
+| `get_alpha(alpha_id)` | Fetch alpha details by ID |
+| `get_pnl(alpha_id)` | Fetch PnL record set for an alpha |
+| `get_recordset(alpha_id, record_set_name)` | Fetch any named record set |
+
+#### Default Simulation Settings
+
+```python
+{
+    "instrumentType": "EQUITY",
+    "region": "USA",
+    "universe": "TOP3000",
+    "delay": 1,
+    "decay": 15,
+    "neutralization": "SUBINDUSTRY",
+    "truncation": 0.08,
+    "maxTrade": "ON",
+    "pasteurization": "ON",
+    "testPeriod": "P1Y6M",
+    "unitHandling": "VERIFY",
+    "nanHandling": "OFF",
+    "language": "FASTEXPR",
+}
+```
+
+Any key passed via `settings` overrides the default.
+
+---
+
+### `SimulationResult`
+
+Returned by `client.simulate()`.
+
+| Method | Description |
+|--------|-------------|
+| `wait(verbose=True)` | Poll until simulation completes; returns result JSON |
+| `get_alpha()` | Fetch full alpha details (call after `wait()`) |
+| `get_pnl(poll_interval)` | Fetch PnL record set (call after `wait()`) |
+
+| Attribute | Description |
+|-----------|-------------|
+| `alpha_id` | Alpha ID string (available after `wait()`) |
+| `progress_url` | URL used to poll simulation progress |
+
+---
+
+## Example
+
+```python
+from brain_client import BrainClient
+
+client = BrainClient.login()  # interactive prompt
+
+sim = client.simulate("close / ts_mean(close, 20) - 1")
+result = sim.wait(verbose=True)
+
+alpha = sim.get_alpha()
+print(f"Alpha ID : {sim.alpha_id}")
+print(f"Sharpe   : {alpha['is']['sharpe']}")
+print(f"Fitness  : {alpha['is']['fitness']}")
+```
+
+## Notes
+
+- The client uses HTTP Basic Auth to obtain a session token from the `/authentication` endpoint.
+- Polling respects the `Retry-After` response header returned by the Brain API.
+- Never commit your credentials to version control. Use `~/.brain_credentials` or environment variables instead.

autobrain_sim-1.0.0/autobrain_sim.egg-info/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: autobrain-sim
+Version: 1.0.0
+Summary: Python client for the WorldQuant Brain API
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Dynamic: license-file
+
+# AutoBrain Sim
+
+A lightweight Python client library for interacting with the [WorldQuant Brain](https://platform.worldquantbrain.com) platform API. Supports authentication, alpha simulation submission, and result retrieval.
+
+## Features
+
+- Multiple authentication methods (direct, credentials file, interactive prompt)
+- Submit alpha expressions for simulation
+- Poll for simulation completion automatically
+- Retrieve alpha details and PnL record sets
+
+## Install
+
+```bash
+pip install autobrain-sim
+```
+
+## Requirements
+
+- Python 3.7+
+- `requests`
+
+Install the dependency:
+
+```bash
+pip install requests
+```
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `brain_client.py` | Core client library (`BrainClient`, `SimulationResult`) |
+| `example.py` | Standalone usage example |
+| `main.ipynb` | Jupyter notebook walkthrough |
+
+## Quick Start
+
+### Authentication
+
+**Method 1 — Direct credentials**
+```python
+from brain_client import BrainClient
+
+client = BrainClient(email="your@email.com", password="yourpassword")
+client.authenticate()
+```
+
+**Method 2 — One-liner login**
+```python
+client = BrainClient.login("your@email.com", "yourpassword")
+```
+
+**Method 3 — Interactive prompt** (asks at runtime if no credentials are found)
+```python
+client = BrainClient()
+client.authenticate()
+```
+
+**Method 4 — Credentials file**
+
+Create `~/.brain_credentials` (or any path) as a JSON array:
+```json
+["your@email.com", "yourpassword"]
+```
+
+Then load it:
+```python
+client = BrainClient(credentials_file="~/.brain_credentials")
+client.authenticate()
+```
+
+> Credentials priority: direct args → `credentials_file` → `~/.brain_credentials` → interactive prompt.
+
+---
+
+### Simulate an Alpha
+
+```python
+sim = client.simulate(
+    expression="close / ts_mean(close, 20) - 1",
+    settings={
+        "region": "USA",
+        "universe": "TOP3000",
+        "neutralization": "SUBINDUSTRY",
+    }
+)
+
+result = sim.wait(verbose=True)   # blocks until done
+print("Alpha ID:", sim.alpha_id)
+```
+
+### Retrieve Results
+
+```python
+alpha = sim.get_alpha()
+print("Sharpe:", alpha["is"]["sharpe"])
+print("Fitness:", alpha["is"]["fitness"])
+
+pnl = sim.get_pnl()
+print(pnl)
+```
+
+---
+
+## API Reference
+
+### `BrainClient`
+
+| Method | Description |
+|--------|-------------|
+| `__init__(email, password, credentials_file)` | Initialize client with credentials |
+| `BrainClient.login(email, password)` | Create client and authenticate in one step |
+| `authenticate()` | Sign in and obtain a session token |
+| `simulate(expression, settings, ...)` | Submit an alpha for simulation; returns `SimulationResult` |
+| `get_alpha(alpha_id)` | Fetch alpha details by ID |
+| `get_pnl(alpha_id)` | Fetch PnL record set for an alpha |
+| `get_recordset(alpha_id, record_set_name)` | Fetch any named record set |
+
+#### Default Simulation Settings
+
+```python
+{
+    "instrumentType": "EQUITY",
+    "region": "USA",
+    "universe": "TOP3000",
+    "delay": 1,
+    "decay": 15,
+    "neutralization": "SUBINDUSTRY",
+    "truncation": 0.08,
+    "maxTrade": "ON",
+    "pasteurization": "ON",
+    "testPeriod": "P1Y6M",
+    "unitHandling": "VERIFY",
+    "nanHandling": "OFF",
+    "language": "FASTEXPR",
+}
+```
+
+Any key passed via `settings` overrides the default.
+
+---
+
+### `SimulationResult`
+
+Returned by `client.simulate()`.
+
+| Method | Description |
+|--------|-------------|
+| `wait(verbose=True)` | Poll until simulation completes; returns result JSON |
+| `get_alpha()` | Fetch full alpha details (call after `wait()`) |
+| `get_pnl(poll_interval)` | Fetch PnL record set (call after `wait()`) |
+
+| Attribute | Description |
+|-----------|-------------|
+| `alpha_id` | Alpha ID string (available after `wait()`) |
+| `progress_url` | URL used to poll simulation progress |
+
+---
+
+## Example
+
+```python
+from brain_client import BrainClient
+
+client = BrainClient.login()  # interactive prompt
+
+sim = client.simulate("close / ts_mean(close, 20) - 1")
+result = sim.wait(verbose=True)
+
+alpha = sim.get_alpha()
+print(f"Alpha ID : {sim.alpha_id}")
+print(f"Sharpe   : {alpha['is']['sharpe']}")
+print(f"Fitness  : {alpha['is']['fitness']}")
+```
+
+## Notes
+
+- The client uses HTTP Basic Auth to obtain a session token from the `/authentication` endpoint.
+- Polling respects the `Retry-After` response header returned by the Brain API.
+- Never commit your credentials to version control. Use `~/.brain_credentials` or environment variables instead.

autobrain_sim-1.0.0/autobrain_sim.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+MANIFEST.in
+README.md
+brain_client.py
+pyproject.toml
+autobrain_sim.egg-info/PKG-INFO
+autobrain_sim.egg-info/SOURCES.txt
+autobrain_sim.egg-info/dependency_links.txt
+autobrain_sim.egg-info/requires.txt
+autobrain_sim.egg-info/top_level.txt
+examples/example.py

autobrain_sim-1.0.0/autobrain_sim.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

autobrain_sim-1.0.0/autobrain_sim.egg-info/requires.txt

@@ -0,0 +1,5 @@
+requests>=2.28
+
+[dev]
+pytest
+pytest-mock

autobrain_sim-1.0.0/autobrain_sim.egg-info/top_level.txt

@@ -0,0 +1 @@
+brain_client

autobrain_sim-1.0.0/brain_client.py

@@ -0,0 +1,282 @@
+"""
+WorldQuant Brain API Client Library
+
+A Python client for interacting with the WorldQuant Brain platform API.
+Supports authentication, alpha simulation, and result retrieval.
+"""
+
+import json
+import getpass
+import requests
+from time import sleep
+from os.path import expanduser
+from typing import Optional
+
+
+BASE_URL = "https://api.worldquantbrain.com"
+
+
+class BrainClient:
+    """Client for the WorldQuant Brain API."""
+
+    def __init__(
+        self,
+        email: Optional[str] = None,
+        password: Optional[str] = None,
+        credentials_file: Optional[str] = None,
+    ):
+        """
+        Initialize the client. Credentials priority:
+          1. email + password passed directly
+          2. credentials_file path (JSON: ["email", "password"])
+          3. ~/.brain_credentials (if the file exists)
+          4. Interactive prompt (asks at runtime)
+
+        Args:
+            email: Brain platform email.
+            password: Brain platform password.
+            credentials_file: Path to a JSON credentials file.
+        """
+        self._session = requests.Session()
+        self._authenticated = False
+
+        if email and password:
+            self._session.auth = (email, password)
+            return
+
+        if credentials_file:
+            with open(expanduser(credentials_file), "r") as f:
+                self._session.auth = tuple(json.load(f))
+            return
+
+        default_file = expanduser("~/.brain_credentials")
+        try:
+            with open(default_file, "r") as f:
+                self._session.auth = tuple(json.load(f))
+        except FileNotFoundError:
+            # Fall back to interactive prompt
+            email = input("WorldQuant Brain email: ").strip()
+            password = getpass.getpass("WorldQuant Brain password: ")
+            self._session.auth = (email, password)
+
+    @classmethod
+    def login(cls, email: Optional[str] = None, password: Optional[str] = None) -> "BrainClient":
+        """
+        Create a BrainClient and authenticate in one step.
+
+        If email/password are not provided, prompts interactively.
+
+        Args:
+            email: Brain platform email (optional).
+            password: Brain platform password (optional).
+
+        Returns:
+            An authenticated BrainClient instance.
+
+        Example:
+            client = BrainClient.login()                          # interactive prompt
+            client = BrainClient.login("me@email.com", "pass")   # direct
+        """
+        client = cls(email=email, password=password)
+        client.authenticate()
+        return client
+
+    # -------------------------------------------------------------------------
+    # Authentication
+    # -------------------------------------------------------------------------
+
+    def authenticate(self) -> dict:
+        """
+        Sign in and obtain a JWT token.
+
+        Returns:
+            Response JSON from the /authentication endpoint.
+
+        Raises:
+            requests.HTTPError: If authentication fails.
+        """
+        response = self._session.post(f"{BASE_URL}/authentication")
+        response.raise_for_status()
+        self._authenticated = True
+        return response.json()
+
+    # -------------------------------------------------------------------------
+    # Simulations
+    # -------------------------------------------------------------------------
+
+    def simulate(self, expression: str, settings: dict = None, alpha_type: str = "REGULAR", regular: str = "close") -> "SimulationResult":
+        """
+        Submit an alpha expression for simulation.
+
+        Args:
+            expression: The alpha expression string.
+            settings: Simulation settings dict. Defaults to standard equity settings.
+            alpha_type: Type of simulation, e.g. "REGULAR".
+            regular: Price field, e.g. "close".
+
+        Returns:
+            A SimulationResult object to poll for completion.
+
+        Raises:
+            requests.HTTPError: If the submission fails.
+        """
+        default_settings = {
+            "instrumentType": "EQUITY",
+            "region": "USA",
+            "universe": "TOP3000",
+            "delay": 1,
+            "decay": 15,
+            "neutralization": "SUBINDUSTRY",
+            "truncation": 0.08,
+            "maxTrade": "ON",
+            "pasteurization": "ON",
+            "testPeriod": "P1Y6M",
+            "unitHandling": "VERIFY",
+            "nanHandling": "OFF",
+            "language": "FASTEXPR",
+            "visualization": False,
+        }
+        if settings:
+            default_settings.update(settings)
+
+        payload = {
+            "type": alpha_type,
+            "settings": default_settings,
+            "regular": expression if regular == "close" else regular,
+        }
+
+        # If expression is provided separately from regular field
+        if regular == "close":
+            payload["regular"] = expression
+
+        response = self._session.post(f"{BASE_URL}/simulations", json=payload)
+        response.raise_for_status()
+
+        progress_url = response.headers.get("Location")
+        return SimulationResult(self._session, progress_url)
+
+    # -------------------------------------------------------------------------
+    # Alphas
+    # -------------------------------------------------------------------------
+
+    def get_alpha(self, alpha_id: str) -> dict:
+        """
+        Retrieve details of a completed alpha by ID.
+
+        Args:
+            alpha_id: The alpha ID string.
+
+        Returns:
+            Alpha details as a dict.
+        """
+        response = self._session.get(f"{BASE_URL}/alphas/{alpha_id}")
+        response.raise_for_status()
+        return response.json()
+
+    def get_pnl(self, alpha_id: str, poll_interval: float = 5.0) -> dict:
+        """
+        Retrieve PnL record set for an alpha, polling until ready.
+
+        Args:
+            alpha_id: The alpha ID string.
+            poll_interval: Fallback seconds to wait between polls if no Retry-After header.
+
+        Returns:
+            PnL record set as a dict.
+        """
+        return self._poll_recordset(alpha_id, "pnl", poll_interval)
+
+    def get_recordset(self, alpha_id: str, record_set_name: str, poll_interval: float = 5.0) -> dict:
+        """
+        Retrieve any named record set for an alpha, polling until ready.
+
+        Args:
+            alpha_id: The alpha ID string.
+            record_set_name: Name of the record set (e.g. "pnl", "sharpe").
+            poll_interval: Fallback seconds between polls if no Retry-After header.
+
+        Returns:
+            Record set data as a dict.
+        """
+        return self._poll_recordset(alpha_id, record_set_name, poll_interval)
+
+    def _poll_recordset(self, alpha_id: str, record_set_name: str, poll_interval: float) -> dict:
+        url = f"{BASE_URL}/alphas/{alpha_id}/recordsets/{record_set_name}"
+        while True:
+            response = self._session.get(url)
+            retry_after = float(response.headers.get("Retry-After", 0))
+            if retry_after == 0:
+                response.raise_for_status()
+                return response.json()
+            #print(f"Sleeping for {retry_after} seconds...")
+            sleep(retry_after)
+
+
+class SimulationResult:
+    """Represents a pending or completed alpha simulation."""
+
+    def __init__(self, session: requests.Session, progress_url: str):
+        self._session = session
+        self.progress_url = progress_url
+        self.alpha_id: str = None
+        self._result: dict = None
+
+    def wait(self, verbose: bool = True) -> dict:
+        """
+        Poll until the simulation completes.
+
+        Args:
+            verbose: If True, print polling status messages.
+
+        Returns:
+            The completed simulation result JSON containing the alpha id.
+        """
+        while True:
+            response = self._session.get(self.progress_url)
+            retry_after = float(response.headers.get("Retry-After", 0))
+            if retry_after == 0:
+                response.raise_for_status()
+                self._result = response.json()
+                self.alpha_id = self._result.get("alpha")
+                if verbose:
+                    print(f"Alpha simulation complete. Alpha ID: {self.alpha_id}")
+                return self._result
+            if verbose:
+                print(f"Simulating... sleeping for {retry_after} seconds")
+            sleep(retry_after)
+
+    def get_alpha(self) -> dict:
+        """
+        Fetch full alpha details after simulation completes.
+
+        Returns:
+            Alpha details dict.
+
+        Raises:
+            RuntimeError: If wait() has not been called yet.
+        """
+        if not self.alpha_id:
+            raise RuntimeError("Simulation not complete. Call wait() first.")
+        response = self._session.get(f"{BASE_URL}/alphas/{self.alpha_id}")
+        response.raise_for_status()
+        return response.json()
+
+    def get_pnl(self, poll_interval: float = 5.0) -> dict:
+        """
+        Retrieve PnL record set after simulation completes.
+
+        Args:
+            poll_interval: Fallback seconds between polls if no Retry-After header.
+
+        Returns:
+            PnL record set dict.
+
+        Raises:
+            RuntimeError: If wait() has not been called yet.
+        """
+        if not self.alpha_id:
+            raise RuntimeError("Simulation not complete. Call wait() first.")
+        client = BrainClient.__new__(BrainClient)
+        client._session = self._session
+        client._authenticated = True
+        return client.get_pnl(self.alpha_id, poll_interval)

autobrain_sim-1.0.0/examples/example.py

@@ -0,0 +1,40 @@
+"""
+Example usage of the WorldQuant Brain API client library.
+"""
+
+from brain_client import BrainClient
+
+# ── วิธีที่ 1: ใส่ email/password โดยตรง ────────────────────────────────────
+client = BrainClient(email="your@email.com", password="yourpassword")
+client.authenticate()
+
+# ── วิธีที่ 2: Interactive prompt (ถามตอนรัน) ────────────────────────────────
+# client = BrainClient()          # ถ้าไม่มี ~/.brain_credentials จะ prompt อัตโนมัติ
+# client.authenticate()
+
+# ── วิธีที่ 3: login() — สั้นสุด สร้าง + auth ในบรรทัดเดียว ─────────────────
+# client = BrainClient.login()                          # interactive prompt
+# client = BrainClient.login("your@email.com", "pass") # หรือใส่ตรงๆ
+
+# ── วิธีที่ 4: Credentials file ──────────────────────────────────────────────
+# client = BrainClient(credentials_file="~/my_creds.json")
+# client.authenticate()
+
+print("Authenticated!")
+
+# Submit simulation
+sim = client.simulate(
+    expression="close / ts_mean(close, 20) - 1",
+    settings={
+        "region": "USA",
+        "universe": "TOP3000",
+        "neutralization": "SUBINDUSTRY",
+    }
+)
+
+result = sim.wait(verbose=True)
+print("Alpha ID:", sim.alpha_id)
+
+alpha = sim.get_alpha()
+print("Sharpe:", alpha["is"]["sharpe"])
+print("Fitness:", alpha["is"]["fitness"])

autobrain_sim-1.0.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "autobrain-sim"
+version = "1.0.0"
+description = "Python client for the WorldQuant Brain API"
+readme = "README.md"
+requires-python = ">=3.7"
+
+dependencies = [
+  "requests>=2.28",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest",
+  "pytest-mock",
+]
+
+[tool.setuptools]
+py-modules = ["brain_client"]

autobrain_sim-1.0.0/setup.cfg

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