tribulnation-engine 0.1.0__tar.gz

tribulnation_engine-0.1.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: tribulnation-engine
+Version: 0.1.0
+Summary: Trading engine — gateway, task manager, and process SDK
+Author-email: Marcel Claramunt <marcel@tribulnation.com>
+Project-URL: repo, https://github.com/tribulnation/engine.git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer
+Requires-Dist: aiohttp
+Requires-Dist: aiofiles
+Requires-Dist: fastapi
+Requires-Dist: aiosqlite
+Requires-Dist: httpx
+Requires-Dist: pydantic
+Requires-Dist: python-dotenv
+Requires-Dist: uvicorn
+
+# Trading Engine
+
+Run algorithmic trading strategies as managed tasks — with a live dashboard, per-task logs, restart policies, and a market SDK that abstracts across venues.
+
+---
+
+## Quickstart
+
+### 1 — Install
+
+```bash
+pip install tribulnation-engine
+```
+
+### 2 — Initialize
+
+Initialize the engine in a new directory:
+
+```bash
+engine init
+# creates engine.toml, .env, and strats/ directory
+```
+
+Edit `engine.toml` and `.env` to configure accounts and strategies.
+
+### 3 — Write a strategy
+
+```python
+# strats/my_strat.py
+from tribulnation.engine import Process, RestartPolicy
+
+class MyStrat(Process):
+  name = 'my-strat'
+  restart = RestartPolicy(on='error', delay=5.0)
+
+  async def run(self, market: str):
+    mkt  = await self.sdk.market(market)
+    book = await mkt.depth()
+    self.log.info('mark price: %s', book.mark_price)
+```
+
+`run()` parameters become the task's argument schema — they appear as a form in
+the dashboard and are coerced to the declared types when a task is started.
+
+### 4 — Start the engine
+
+```bash
+engine start          # foreground, logs to stdout
+engine start -d       # background — writes .engine.pid and engine.log
+```
+
+### 5 — Run a strategy
+
+From the dashboard at `http://localhost:3121` or via the CLI:
+
+```bash
+engine task start my-strat bitcoin -a market=mexc:spot:BTCUSDT
+# engine task start <process_name> <run_id> -a <arg_name>=<arg_value> ...
+```
+
+### 6 — Stop a strategy
+
+From the dashboard or:
+
+```bash
+engine task stop my-strat bitcoin
+# engine task stop <process_name> <run_id>
+```
+
+---
+
+## Strategies
+
+### The `Process` base
+
+```python
+from tribulnation.engine import Process, RestartPolicy
+```
+
+Implement `async def run(self, ...)`. Anything `run()` needs is injected via
+`self`:
+
+| Attribute | What it is |
+|-----------|------------|
+| `self.sdk` | Market SDK — call `await self.sdk.market('venue::symbol')` |
+| `self.log` | Logger scoped to this task |
+| `self.run_id` | The run ID this task was started with |
+| `self.set_state(s)` | Publish a named state (`'connected'`, `'quoting'`, …) |
+| `self.require(cls, id)` | Declare a dependency on another running task |
+| `self.ipc` | Call methods on `Service` processes |
+
+### Restart policy
+
+```python
+class Hedger(Process):
+  restart = RestartPolicy(on='error', delay=5.0)
+```
+
+| `on=` | Behaviour |
+|-------|-----------|
+| `'never'` | Stop on exit or error |
+| `'error'` | Restart after an unhandled exception, with `delay` seconds between attempts |
+| `'always'` | Restart after any exit |
+
+`max_attempts=N` caps the number of consecutive restarts.
+
+### Dependencies
+
+Use `require()` to gate a task on another reaching a named state:
+
+```python
+class DydxMaker(Process):
+  async def run(self, maker: str, hedge: str) -> None:
+    async with self.require(Hedger, self.run_id, state='connected')(
+      listen=maker, hedge=hedge
+    ):
+      # runs only while Hedger/{self.run_id} is alive and in state 'connected'
+      ...
+```
+
+`require()` also auto-starts the dependency if it isn't running, and cancels
+the dependent if the dependency stops or errors.
+
+### Logging
+
+Standard `logging` calls are automatically captured and streamed to the
+dashboard. No setup needed:
+
+```python
+log = logging.getLogger(__name__)
+
+class Hedger(Process):
+  async def run(self, ...):
+    log.info('listener live: %s → %s', listen, hedge)
+    # or use the process logger:
+    self.log.info('works the same way')
+```
+
+`INFO` and above are always captured. `DEBUG` records are captured only from
+loggers whose name starts with a prefix listed in `[daemon] debug_loggers`:
+
+```toml
+[daemon]
+debug_loggers = ["strats"]
+```
+
+---
+
+## Config reference (`engine.toml`)
+
+```toml
+[engine]
+processes = [
+  "strats.hedger:Hedger",
+  "strats.dydx_maker:DydxMaker",
+]
+
+[daemon]
+host     = "localhost"
+port     = 3121
+db       = "engine.db"    # SQLite path; default "engine.db"
+max_logs = 500            # in-memory log lines per task; default unlimited
+
+[accounts.dydx-main]
+venue    = "dydx"
+mnemonic = "$DYDX_MNEMONIC"
+
+[accounts.hyperliquid-main]
+venue       = "hyperliquid"
+address     = "$HYPERLIQUID_ADDRESS"
+private_key = "$HYPERLIQUID_PRIVATE_KEY"
+
+[[tasks]]
+process = "hedger"
+id      = "btc"
+args    = { listen = "dydx:perp:BTC-USD", hedge = "hl::BTC" }
+```
+
+Account credentials are resolved from environment variables when the value
+starts with `$`. `engine start` automatically loads `.env` from the same
+directory as `engine.toml`.
+
+`[[tasks]]` entries are started automatically when the engine starts. Each
+entry needs `process` (the registered process name), `id` (the run ID), and
+optionally `args` (a table of keyword arguments matching the process
+signature).
+
+---
+
+## CLI
+
+```bash
+engine start                                          # launch gateway + manager (foreground)
+engine start -d                                       # background — writes .engine.pid + engine.log
+engine stop                                           # stop a background engine
+engine task start hedger btc -a listen=dydx:perp:BTC-USD -a hedge=hyperliquid::BTC
+engine task stop  hedger btc
+engine register strats.new_strat:NewStrat             # hot-load a process class
+```
+
+---
+
+## HTTP API
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/tasks` | Running tasks |
+| `GET` | `/api/tasks/history` | Completed tasks (SQLite) |
+| `GET` | `/api/task/{process}/{id}` | Single task |
+| `GET` | `/api/task/{process}/{id}/logs` | Task logs |
+| `GET` | `/api/task/{process}/{id}/attempts` | Restart attempts |
+| `POST` | `/api/task/{process}/{id}` | Start a task — body: `{"args": {...}}` |
+| `DELETE` | `/api/task/{process}/{id}` | Stop a task |
+| `DELETE` | `/api/task/{process}/{id}?purge=true` | Stop and remove from history |
+| `DELETE` | `/api/task/{process}/{id}/logs` | Clear logs and attempt history |
+| `GET` | `/api/processes` | Registered process classes |
+| `POST` | `/api/processes` | Register a process at runtime |
+| `GET` | `/api/health` | Health check |
+| `GET` | `/api/ws` | WebSocket event feed |
+
+---
+
+## Architecture
+
+```
+engine start
+├── engine gateway    owns real venue SDK connections, serves the market RPC protocol
+└── engine manager    task control plane
+  ├── in-process runtime — strategies run as asyncio tasks
+  ├── REST + WebSocket API (FastAPI / uvicorn)
+  └── SQLite store — task history, logs, restart attempts
+```
+
+Strategies never hold venue connections directly. `self.sdk` inside a task is a
+`ProxySDK` that routes market calls to the gateway over a local Unix socket. The
+gateway owns the real credentials and connections; the manager owns task
+lifecycle and the dashboard.

tribulnation_engine-0.1.0/README.md

@@ -0,0 +1,237 @@
+# Trading Engine
+
+Run algorithmic trading strategies as managed tasks — with a live dashboard, per-task logs, restart policies, and a market SDK that abstracts across venues.
+
+---
+
+## Quickstart
+
+### 1 — Install
+
+```bash
+pip install tribulnation-engine
+```
+
+### 2 — Initialize
+
+Initialize the engine in a new directory:
+
+```bash
+engine init
+# creates engine.toml, .env, and strats/ directory
+```
+
+Edit `engine.toml` and `.env` to configure accounts and strategies.
+
+### 3 — Write a strategy
+
+```python
+# strats/my_strat.py
+from tribulnation.engine import Process, RestartPolicy
+
+class MyStrat(Process):
+  name = 'my-strat'
+  restart = RestartPolicy(on='error', delay=5.0)
+
+  async def run(self, market: str):
+    mkt  = await self.sdk.market(market)
+    book = await mkt.depth()
+    self.log.info('mark price: %s', book.mark_price)
+```
+
+`run()` parameters become the task's argument schema — they appear as a form in
+the dashboard and are coerced to the declared types when a task is started.
+
+### 4 — Start the engine
+
+```bash
+engine start          # foreground, logs to stdout
+engine start -d       # background — writes .engine.pid and engine.log
+```
+
+### 5 — Run a strategy
+
+From the dashboard at `http://localhost:3121` or via the CLI:
+
+```bash
+engine task start my-strat bitcoin -a market=mexc:spot:BTCUSDT
+# engine task start <process_name> <run_id> -a <arg_name>=<arg_value> ...
+```
+
+### 6 — Stop a strategy
+
+From the dashboard or:
+
+```bash
+engine task stop my-strat bitcoin
+# engine task stop <process_name> <run_id>
+```
+
+---
+
+## Strategies
+
+### The `Process` base
+
+```python
+from tribulnation.engine import Process, RestartPolicy
+```
+
+Implement `async def run(self, ...)`. Anything `run()` needs is injected via
+`self`:
+
+| Attribute | What it is |
+|-----------|------------|
+| `self.sdk` | Market SDK — call `await self.sdk.market('venue::symbol')` |
+| `self.log` | Logger scoped to this task |
+| `self.run_id` | The run ID this task was started with |
+| `self.set_state(s)` | Publish a named state (`'connected'`, `'quoting'`, …) |
+| `self.require(cls, id)` | Declare a dependency on another running task |
+| `self.ipc` | Call methods on `Service` processes |
+
+### Restart policy
+
+```python
+class Hedger(Process):
+  restart = RestartPolicy(on='error', delay=5.0)
+```
+
+| `on=` | Behaviour |
+|-------|-----------|
+| `'never'` | Stop on exit or error |
+| `'error'` | Restart after an unhandled exception, with `delay` seconds between attempts |
+| `'always'` | Restart after any exit |
+
+`max_attempts=N` caps the number of consecutive restarts.
+
+### Dependencies
+
+Use `require()` to gate a task on another reaching a named state:
+
+```python
+class DydxMaker(Process):
+  async def run(self, maker: str, hedge: str) -> None:
+    async with self.require(Hedger, self.run_id, state='connected')(
+      listen=maker, hedge=hedge
+    ):
+      # runs only while Hedger/{self.run_id} is alive and in state 'connected'
+      ...
+```
+
+`require()` also auto-starts the dependency if it isn't running, and cancels
+the dependent if the dependency stops or errors.
+
+### Logging
+
+Standard `logging` calls are automatically captured and streamed to the
+dashboard. No setup needed:
+
+```python
+log = logging.getLogger(__name__)
+
+class Hedger(Process):
+  async def run(self, ...):
+    log.info('listener live: %s → %s', listen, hedge)
+    # or use the process logger:
+    self.log.info('works the same way')
+```
+
+`INFO` and above are always captured. `DEBUG` records are captured only from
+loggers whose name starts with a prefix listed in `[daemon] debug_loggers`:
+
+```toml
+[daemon]
+debug_loggers = ["strats"]
+```
+
+---
+
+## Config reference (`engine.toml`)
+
+```toml
+[engine]
+processes = [
+  "strats.hedger:Hedger",
+  "strats.dydx_maker:DydxMaker",
+]
+
+[daemon]
+host     = "localhost"
+port     = 3121
+db       = "engine.db"    # SQLite path; default "engine.db"
+max_logs = 500            # in-memory log lines per task; default unlimited
+
+[accounts.dydx-main]
+venue    = "dydx"
+mnemonic = "$DYDX_MNEMONIC"
+
+[accounts.hyperliquid-main]
+venue       = "hyperliquid"
+address     = "$HYPERLIQUID_ADDRESS"
+private_key = "$HYPERLIQUID_PRIVATE_KEY"
+
+[[tasks]]
+process = "hedger"
+id      = "btc"
+args    = { listen = "dydx:perp:BTC-USD", hedge = "hl::BTC" }
+```
+
+Account credentials are resolved from environment variables when the value
+starts with `$`. `engine start` automatically loads `.env` from the same
+directory as `engine.toml`.
+
+`[[tasks]]` entries are started automatically when the engine starts. Each
+entry needs `process` (the registered process name), `id` (the run ID), and
+optionally `args` (a table of keyword arguments matching the process
+signature).
+
+---
+
+## CLI
+
+```bash
+engine start                                          # launch gateway + manager (foreground)
+engine start -d                                       # background — writes .engine.pid + engine.log
+engine stop                                           # stop a background engine
+engine task start hedger btc -a listen=dydx:perp:BTC-USD -a hedge=hyperliquid::BTC
+engine task stop  hedger btc
+engine register strats.new_strat:NewStrat             # hot-load a process class
+```
+
+---
+
+## HTTP API
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/tasks` | Running tasks |
+| `GET` | `/api/tasks/history` | Completed tasks (SQLite) |
+| `GET` | `/api/task/{process}/{id}` | Single task |
+| `GET` | `/api/task/{process}/{id}/logs` | Task logs |
+| `GET` | `/api/task/{process}/{id}/attempts` | Restart attempts |
+| `POST` | `/api/task/{process}/{id}` | Start a task — body: `{"args": {...}}` |
+| `DELETE` | `/api/task/{process}/{id}` | Stop a task |
+| `DELETE` | `/api/task/{process}/{id}?purge=true` | Stop and remove from history |
+| `DELETE` | `/api/task/{process}/{id}/logs` | Clear logs and attempt history |
+| `GET` | `/api/processes` | Registered process classes |
+| `POST` | `/api/processes` | Register a process at runtime |
+| `GET` | `/api/health` | Health check |
+| `GET` | `/api/ws` | WebSocket event feed |
+
+---
+
+## Architecture
+
+```
+engine start
+├── engine gateway    owns real venue SDK connections, serves the market RPC protocol
+└── engine manager    task control plane
+  ├── in-process runtime — strategies run as asyncio tasks
+  ├── REST + WebSocket API (FastAPI / uvicorn)
+  └── SQLite store — task history, logs, restart attempts
+```
+
+Strategies never hold venue connections directly. `self.sdk` inside a task is a
+`ProxySDK` that routes market calls to the gateway over a local Unix socket. The
+gateway owns the real credentials and connections; the manager owns task
+lifecycle and the dashboard.

tribulnation_engine-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tribulnation-engine"
+version = "0.1.0"
+authors = [
+  {name="Marcel Claramunt", email="marcel@tribulnation.com"}
+]
+description = "Trading engine — gateway, task manager, and process SDK"
+dependencies = [
+  "typer",
+  "aiohttp",
+  "aiofiles",
+  "fastapi",
+  "aiosqlite",
+  "httpx",
+  "pydantic",
+  "python-dotenv",
+  "uvicorn",
+]
+requires-python = ">=3.11"
+readme = {file="README.md", content-type="text/markdown"}
+
+[tool.setuptools.package-data]
+"tribulnation.engine" = ["ui/**/*"]
+
+[project.urls]
+repo = "https://github.com/tribulnation/engine.git"
+
+[project.scripts]
+engine = "tribulnation.engine.cli:app"
+
+# [project.optional-dependencies]
+# test = [
+#   "pytest < 5.0.0",
+#   "pytest-cov[all]"
+# ]

tribulnation_engine-0.1.0/setup.cfg

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

tribulnation_engine-0.1.0/src/tribulnation/engine/__init__.py

@@ -0,0 +1,3 @@
+import lazy_loader as lazy
+
+__getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)

tribulnation_engine-0.1.0/src/tribulnation/engine/__init__.pyi

@@ -0,0 +1,51 @@
+"""Tribulnation Engine — gateway, task manager, and strategy SDK.
+
+Quick-start::
+
+    # 1. Define a worker:
+    from tribulnation.engine import Process
+
+    class Hedge(Process):
+      async def run(self, listen: str, market: str) -> None:
+        mkt = await self.sdk.perp_market(listen)
+        self.set_state('connected')
+        async for trade in await mkt.trades_stream():
+          ...
+
+    # 2. Connect a client:
+    from tribulnation.engine import TradingEngine
+
+    async with TradingEngine.at('unix:///tmp/engine-gateway.sock', api_url='http://localhost:3121') as e:
+      book = await (await e.sdk.perp_market('dydx:perp:BTC-USD')).depth()
+      await e.task.start('hedge', 'btc', market='dydx:perp:BTC-USD', listen='hyper:perp:BTC')
+"""
+
+from .client import TaskClient, TradingEngine
+from .config import DaemonConfig, EngineConfig
+from .gateway import EngineError, EngineGateway, ProxySDK
+from .runtime import (
+  Process,
+  RPC,
+  Require,
+  RestartPolicy,
+  Runtime,
+)
+from .manager import Manager, Store, load_process
+
+__all__ = [
+  'Process',
+  'RPC',
+  'Require',
+  'RestartPolicy',
+  'Runtime',
+  'EngineGateway',
+  'ProxySDK',
+  'EngineError',
+  'TradingEngine',
+  'TaskClient',
+  'EngineConfig',
+  'DaemonConfig',
+  'Manager',
+  'Store',
+  'load_process',
+]

tribulnation_engine-0.1.0/src/tribulnation/engine/cli/__init__.py

@@ -0,0 +1,18 @@
+import typer
+
+from .init import init
+from .start import start
+from .stop import stop
+from .gateway import gateway
+from .manager import manager
+from .register import register
+from .task import task_app
+
+app = typer.Typer()
+app.command()(init)
+app.command()(start)
+app.command()(stop)
+app.command()(gateway)
+app.command()(manager)
+app.command()(register)
+app.add_typer(task_app, name='task')

tribulnation_engine-0.1.0/src/tribulnation/engine/cli/gateway.py

@@ -0,0 +1,61 @@
+"""CLI command: ``engine gateway`` — start the standalone gateway process."""
+
+from __future__ import annotations
+
+from typing_extensions import Annotated
+from pathlib import Path
+import asyncio
+import logging
+
+import typer
+from dotenv import load_dotenv
+
+_GATEWAY_LOGGERS = ('tribulnation.engine.gateway.server',)
+
+_FMT = '%(asctime)s  %(name)-40s  %(message)s'
+_DATEFMT = '%H:%M:%S'
+
+
+def gateway(
+  socket: Annotated[
+    str | None,
+    typer.Option('--socket', '-s', help='Unix socket path (overrides engine.toml).'),
+  ] = None,
+  config: Annotated[
+    Path, typer.Option('--config', '-c', help='Path to TOML config file.')
+  ] = Path('engine.toml'),
+  verbose: Annotated[
+    int,
+    typer.Option(
+      '--verbose',
+      '-v',
+      count=True,
+      help='Increase log verbosity. Repeat for all debug output.',
+    ),
+  ] = 0,
+):
+  """Start the WebSocket gateway on a Unix socket."""
+  _configure_logging(verbose)
+  load_dotenv(config.parent / '.env')
+
+  from tribulnation.engine.config import EngineConfig
+  from tribulnation.engine.gateway.server import run_gateway
+
+  cfg = EngineConfig.load(config)
+  sock = socket or cfg.daemon.socket
+  asyncio.run(run_gateway(sock, cfg))
+
+
+def _configure_logging(verbose: int) -> None:
+  if verbose >= 2:
+    logging.basicConfig(level=logging.DEBUG, format=_FMT, datefmt=_DATEFMT)
+    return
+  if verbose:
+    handler = logging.StreamHandler()
+    handler.setLevel(logging.DEBUG)
+    handler.setFormatter(logging.Formatter(_FMT, datefmt=_DATEFMT))
+    root = logging.getLogger()
+    root.setLevel(logging.WARNING)
+    root.addHandler(handler)
+    for name in _GATEWAY_LOGGERS:
+      logging.getLogger(name).setLevel(logging.DEBUG)