neleus 0.1.0

Python user layer for the Neleus trading framework

Neleus Python Package

The Python user layer for the Neleus trading framework. Write strategies in Python, run them anywhere.

📚 Documentation Quick Links

• SETUP_VISUAL.md - Visual guide: Where everything goes
• ENV_QUICK_REFERENCE.md - Environment setup quick reference
• ENVIRONMENT_SETUP.md - Complete environment configuration guide
• BINARY_DISTRIBUTION.md - Building & publishing guide
• RELEASE_CHECKLIST.md - Pre-release security checklist
• Tools: ./check_environment.sh, ./build_wheels.sh, ./publish_wheels.sh

Installation

pip install neleus

Or install from source:

cd python
pip install -e .

Quick Start

1. Create a New Project

neleus create my_trading_project
cd my_trading_project

This creates:

my_trading_project/
├── .env              # API keys and secrets (DO NOT COMMIT)
├── .env.example      # Example environment file
├── .gitignore        # Pre-configured gitignore
├── config.yaml       # Main project configuration
├── run_backtest.py   # Backtest runner script
├── strategies/       # Your trading strategies
├── configs/          # Strategy-specific configs
├── data/             # Market data cache
├── logs/             # Application logs
└── reports/          # Backtest reports

2. Configure Your Credentials

Edit .env with your API keys:

# Hyperliquid
HYPERLIQUID_PRIVATE_KEY=your_private_key_here
HYPERLIQUID_TESTNET=true

# Lighter
LIGHTER_API_KEY=your_api_key_here
LIGHTER_API_SECRET=your_secret_here

3. Create a Strategy

neleus new strategy --name MyMomentum

This creates:

• strategies/my_momentum.py - Your strategy code
• configs/my_momentum.yaml - Strategy configuration

4. Edit Your Strategy

# strategies/my_momentum.py

from neleus import Strategy, StrategyContext, Bar, OrderSide

class MyMomentum(Strategy):
    def __init__(self, lookback: int = 20, threshold: float = 0.02):
        super().__init__("MyMomentum")
        self.lookback = lookback
        self.threshold = threshold
        self.prices = []
    
    def on_start(self, ctx: StrategyContext):
        ctx.subscribe_bars(ctx.instruments[0])
    
    def on_data(self, ctx: StrategyContext, data):
        if isinstance(data, Bar):
            self.prices.append(data.close)
            if len(self.prices) > self.lookback:
                momentum = (self.prices[-1] - self.prices[-self.lookback]) / self.prices[-self.lookback]
                if momentum > self.threshold:
                    ctx.market_order(data.instrument_id, OrderSide.BUY, 0.1)
                elif momentum < -self.threshold:
                    ctx.market_order(data.instrument_id, OrderSide.SELL, 0.1)

5. Run Backtest

neleus backtest

Or with options:

neleus backtest --strategy my_momentum --start 2024-01-01 --end 2024-06-01

6. Open Dashboard

neleus ui

Opens a web dashboard at http://localhost:8080 where you can:

• View price charts and orderbook
• Configure strategy parameters
• Run backtests with visual results
• Monitor positions and PnL

CLI Commands

Command	Description
neleus create [name]	Create a new Neleus project
neleus new strategy --name NAME	Create a new strategy
neleus backtest	Run backtest
neleus run --mode paper	Start paper trading
neleus run --mode live	Start live trading
neleus ui	Open web dashboard
neleus config show	Show current config
neleus config validate	Validate configuration

Configuration

Project Config (config.yaml)

project:
  name: "my_project"

venues:
  hyperliquid:
    enabled: true
    mode: paper  # backtest | paper | live

instruments:
  - symbol: BTC
    venue: hyperliquid
    type: perp

risk:
  max_position_size: 1.0
  max_drawdown_pct: 10.0
  daily_loss_limit: 500.0

backtest:
  start_date: "2024-01-01"
  end_date: "2024-12-31"
  initial_capital: 10000.0

Strategy Config (configs/my_strategy.yaml)

strategy:
  name: "MyStrategy"
  enabled: true

parameters:
  lookback: 20
  threshold: 0.02
  position_size: 0.1

instruments:
  - symbol: BTC
    venue: hyperliquid
    type: perp

Environment Variables (.env)

# Venue Credentials
HYPERLIQUID_PRIVATE_KEY=
HYPERLIQUID_TESTNET=true
LIGHTER_API_KEY=
LIGHTER_API_SECRET=

# Override Config
NELEUS_LOG_LEVEL=INFO
NELEUS_MAX_POSITION_SIZE=1.0
NELEUS_DASHBOARD_PORT=8080

Python API

from neleus import (
    Strategy,
    StrategyContext,
    BacktestNode,
    BacktestConfig,
    load_project_config,
    start_dashboard,
)

# Load config
config = load_project_config()

# Create strategy
class MyStrategy(Strategy):
    def on_data(self, ctx, data):
        pass

# Run backtest
from datetime import datetime
bt_config = BacktestConfig(
    start_time=datetime(2024, 1, 1),
    end_time=datetime(2024, 6, 1),
)
node = BacktestNode(bt_config)
node.add_strategy(MyStrategy())
results = node.run()
print(results.summary())

# Generate report
from neleus import generate_html_report
generate_html_report(results, "report.html")

# Start dashboard
start_dashboard(port=8080)

Supported Venues

Venue	Market Data	Trading	Status
Hyperliquid			Active
Lighter			Active

Requirements

• Python 3.10+
• No native dependencies (pure Python + optional Rust bindings)
• Works on Linux, macOS, Windows

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
ruff check .

# Type check
mypy neleus

Distribution & Publishing

⚠️ Important: This package uses binary-only distribution to protect IP.

Neleus is distributed as pre-compiled wheels (.whl files) only. The Rust source code is compiled into binary form and is not included in published packages.

Quick Start: Build & Publish

# Build binary wheels (current platform)
cd python
./build_wheels.sh

# Publish to PyPI
./publish_wheels.sh

Cross-Platform Builds

For full platform support, use GitHub Actions (.github/workflows/build-wheels.yml) or build manually on each platform:

• Linux (x86_64, aarch64)
• macOS (Intel, Apple Silicon)
• Windows (x86_64)

Resources

• BINARY_DISTRIBUTION.md - Complete distribution guide
• QUICK_REFERENCE.sh - Quick commands reference
• ./build_wheels.sh - Automated build script with security checks
• ./publish_wheels.sh - Interactive publishing tool

Security Notes

✓ Binary wheels contain NO source code ✓ Rust implementation remains private ✓ Users install normally with pip install neleus ✗ Never run python setup.py sdist (creates source distribution) ✗ Never commit dist/ or .pypirc to version control

For detailed instructions, see BINARY_DISTRIBUTION.md.

License

MIT License - see LICENSE file.