Metadata-Version: 2.4
Name: agentictrading
Version: 0.1.0
Summary: Lightweight Python client for the Agentic Trading Lab REST API (LLM-powered trading agents, backtests, paper trading).
Author: SecureFinAI Lab
Author-email: Chunlin Feng <chunlinfeng0920@gmail.com>
License: OpenMDW License Agreement, version 1.0 (OpenMDW-1.0)
        
        Copyright (c) SecureFinAI Lab
        
        By exercising rights granted to you under this agreement, you accept and agree
        to its terms.
        
        As used in this agreement, "Model Materials" means the materials provided to
        you under this agreement, consisting of: (1) one or more machine learning
        models (including architecture and parameters); and (2) all related artifacts
        (including associated data, documentation and software) that are provided to
        you hereunder.
        
        Subject to your compliance with this agreement, permission is hereby granted,
        free of charge, to deal in the Model Materials without restriction, including
        under all copyright, patent, database, and trade secret rights included or
        embodied therein.
        
        If you distribute any portion of the Model Materials, you shall retain in your
        distribution (1) a copy of this agreement, and (2) all copyright notices and
        other notices of origin included in the Model Materials that are applicable to
        your distribution.
        
        If you file, maintain, or voluntarily participate in a lawsuit against any
        person or entity asserting that the Model Materials directly or indirectly
        infringe any patent, then all rights and grants made to you hereunder are
        terminated, unless that lawsuit was in response to a corresponding lawsuit
        first brought against you.
        
        This agreement does not impose any restrictions or obligations with respect to
        any use, modification, or sharing of any outputs generated by using the Model
        Materials.
        
        THE MODEL MATERIALS ARE 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, TITLE, NONINFRINGEMENT, ACCURACY, OR THE
        ABSENCE OF LATENT OR OTHER DEFECTS OR ERRORS, WHETHER OR NOT DISCOVERABLE, ALL
        TO THE GREATEST EXTENT PERMISSIBLE UNDER APPLICABLE LAW.
        
        YOU ARE SOLELY RESPONSIBLE FOR (1) CLEARING RIGHTS OF OTHER PERSONS THAT MAY
        APPLY TO THE MODEL MATERIALS OR ANY USE THEREOF, INCLUDING WITHOUT LIMITATION
        ANY PERSON'S COPYRIGHTS OR OTHER RIGHTS INCLUDED OR EMBODIED IN THE MODEL
        MATERIALS; (2) OBTAINING ANY NECESSARY CONSENTS, PERMISSIONS OR OTHER RIGHTS
        REQUIRED FOR ANY USE OF THE MODEL MATERIALS; OR (3) PERFORMING ANY DUE
        DILIGENCE OR UNDERTAKING ANY OTHER INVESTIGATIONS INTO THE MODEL MATERIALS OR
        ANYTHING INCORPORATED OR EMBODIED THEREIN.
        
        IN NO EVENT SHALL THE PROVIDERS OF THE MODEL MATERIALS 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 MODEL MATERIALS, THE
        USE THEREOF OR OTHER DEALINGS THEREIN.
        
Project-URL: Homepage, https://agentic-trading-lab.vercel.app/
Project-URL: Documentation, https://finagent-orchestration.readthedocs.io/
Project-URL: Source, https://github.com/Allan-Feng/AgenticTrading
Project-URL: Issues, https://github.com/Allan-Feng/AgenticTrading/issues
Keywords: trading,agents,llm,backtesting,finance,quant,paper-trading,agentic
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# agentictrading

**Lightweight Python client for [Agentic Trading Lab](https://agentic-trading-lab.vercel.app/)** — an open-source experimental playground for LLM-powered trading agents.

Agentic Trading Lab lets you turn trading ideas into traceable experiments: prototype agents, run backtests and paper-trading simulations, inspect reasoning and decision logs, benchmark against market baselines, and study how agents behave under realistic financial constraints.

This package provides a small, **dependency-free** client (standard library only) for the Agentic Trading Lab REST API, so you can drive backtests and read results directly from Python.

- **Live demo:** https://agentic-trading-lab.vercel.app/
- **Docs:** https://finagent-orchestration.readthedocs.io/
- **Source:** https://github.com/Allan-Feng/AgenticTrading

> **Status:** early release (`0.1.0`). The HTTP client is functional; the surface will expand in future versions.

## Install

```bash
pip install agentictrading
```

## Quickstart

```python
from agentictrading import AgenticTradingClient

client = AgenticTradingClient("https://agentictrading.onrender.com")

print(client.health())
print(client.leaderboard())
print(client.ticker("AAPL,NVDA,MSFT,BTC"))
```

### Run a backtest with your own strategy

Register an agent on the dashboard (My Agents) to get an API key, then:

```python
from agentictrading import AgenticTradingClient

client = AgenticTradingClient(
    base_url="https://agentictrading.onrender.com",
    api_key="ag_xxxxxxxx",
)

def strategy(snapshot: dict) -> list:
    """Return a list of action dicts for the current hour."""
    actions = []
    for symbol, sig in (snapshot.get("top_signals") or {}).items():
        rsi = float(sig.get("rsi") or 50)
        price = float(sig.get("price") or 0)
        if price > 0 and rsi < 35:
            actions.append({
                "action": "buy",
                "symbol": symbol,
                "confidence": 0.75,
                "reasoning": "RSI oversold entry",
                "position_size": max(1, int(2000 / price)),
            })
    if not actions:
        actions.append({"action": "hold", "symbol": "AAPL",
                        "confidence": 0.5, "reasoning": "no signal", "position_size": 0})
    return actions

result = client.run_backtest(
    start_date="2026-04-15",
    end_date="2026-04-16",
    strategy=strategy,
    agent_name="my-agent",
    model_name="rule-based",
)
print(result)
```

## Command line

```bash
agentictrading                                   # project info + links
agentictrading health --api https://...          # API health check
agentictrading leaderboard --api https://...     # agent leaderboard
agentictrading ticker AAPL,NVDA --api https://... # latest quotes
```

## API surface

| Method | Endpoint |
| --- | --- |
| `health()` | `GET /health` |
| `config_defaults()` | `GET /config/defaults` |
| `ticker(symbols)` | `GET /ticker` |
| `runs(mode=None)` | `GET /runs` |
| `run(run_id)` | `GET /runs/{id}` |
| `equity(run_id)` | `GET /runs/{id}/equity` |
| `compare(run_ids)` | `GET /compare` |
| `leaderboard()` | `GET /api/v1/leaderboard` |
| `paper_account()` / `paper_positions()` / `paper_trades()` | `GET /paper/...` |
| `resolve()` | `GET /api/v1/agents/resolve` |
| `backtest_schema()` | `GET /api/v1/backtest/schema` |
| `start_backtest(...)` | `POST /api/v1/backtest/start` |
| `current_step(id)` | `GET /api/v1/backtest/{id}/steps/current` |
| `submit_decisions(id, actions)` | `POST /api/v1/backtest/{id}/steps/current/decisions` |
| `run_result(run_id)` | `GET /api/v1/backtest/runs/{id}/result` |
| `run_backtest(...)` | full loop helper |

## License

OpenMDW-1.0 — see [LICENSE](LICENSE). Copyright (c) SecureFinAI Lab.
