Metadata-Version: 2.4
Name: llama-index-tools-algovault
Version: 0.1.0
Summary: AlgoVault ToolSpec for LlamaIndex — composite BUY/SELL/HOLD trade calls, market-regime classification, and cross-venue funding-arbitrage scans for crypto perpetual futures, backed by the AlgoVault MCP server.
Project-URL: Homepage, https://algovault.com
Project-URL: Repository, https://github.com/AlgoVaultLabs/llama-index-tools-algovault
Project-URL: Track Record, https://algovault.com/track-record
Project-URL: MCP Server, https://api.algovault.com/mcp
Author-email: AlgoVault Labs <admin@algovault.com>
Maintainer-email: AlgoVault Labs <admin@algovault.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,algovault,crypto,funding-arbitrage,llama-index,llamaindex,mcp,signals,tools,toolspec,trade-call,trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: <4.0,>=3.10
Requires-Dist: llama-index-core<0.15,>=0.13.0
Requires-Dist: mcp<2,>=1.24.0
Description-Content-Type: text/markdown

# LlamaIndex Tools: AlgoVault

Composite **BUY / SELL / HOLD** trade calls, market‑regime classification, and cross‑venue funding‑arbitrage scans for crypto perpetual futures — exposed as native [LlamaIndex](https://github.com/run-llama/llama_index) tools, backed by the [AlgoVault](https://algovault.com) MCP server.

> One import, zero MCP wiring, **keyless free tier** by default. Built by **AlgoVault Labs**.

```bash
pip install llama-index-tools-algovault
```

## Why

AlgoVault is an API‑first signal‑interpretation layer for AI agents: it turns raw market data into a single **composite verdict** with a queryable, public track record. This `ToolSpec` gives a LlamaIndex agent four AlgoVault tools out of the box — no API key required to start (free tier), and a one‑line `api_key` for paid tiers.

The performance the verdicts are scored against (PFE win‑rate) is published live at **[algovault.com/track-record](https://algovault.com/track-record)** and via the MCP `signal-performance` resource.

## Quick start (branded ToolSpec)

```python
from llama_index.tools.algovault import AlgoVaultToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

# Keyless free tier (100 calls / month). Pass api_key="..." or set
# ALGOVAULT_API_KEY for paid tiers.
algovault = AlgoVaultToolSpec()

agent = FunctionAgent(
    tools=algovault.to_tool_list(),
    llm=OpenAI(model="gpt-4o"),
    system_prompt="You are a crypto trading research assistant.",
)

resp = await agent.run("What's the current trade call for BTC?")
print(resp)
```

Call a tool directly:

```python
algovault = AlgoVaultToolSpec()
print(algovault.get_trade_call("BTC"))                       # free
print(algovault.get_trade_call("ETH", timeframe="4h", exchange="BYBIT"))
print(algovault.get_market_regime("SOL", timeframe="1d"))    # paid tier
print(algovault.scan_funding_arb(min_spread_bps=5, limit=5)) # paid tier
```

### Authentication

| Mode | How | Tier |
|---|---|---|
| Keyless (default) | `AlgoVaultToolSpec()` | Free — 100 calls / month |
| API key | `AlgoVaultToolSpec(api_key="...")` or `ALGOVAULT_API_KEY` env | Paid tiers |

The key (when set) is sent as an `Authorization: Bearer <key>` header to `https://api.algovault.com/mcp`.

## Tools

| Tool | Tier | Signature | Returns |
|---|---|---|---|
| `get_trade_call` | **Free** | `coin`, `timeframe?`, `exchange?`, `include_reasoning=True`, `asset_class?` | Composite BUY/SELL/HOLD verdict + confidence, price, indicators, regime, reasoning |
| `get_trade_signal` | Free | *(same as `get_trade_call`)* | Alias of `get_trade_call`, kept for back‑compat |
| `get_market_regime` | Paid | `coin`, `timeframe="4h"`, `exchange="HL"` | Regime: `TRENDING_UP` / `TRENDING_DOWN` / `RANGING` / `VOLATILE` |
| `scan_funding_arb` | Paid | `min_spread_bps=5`, `limit=10` | Cross‑venue funding‑rate spreads (long one venue, short the other) |

`timeframe` ∈ `1m 3m 5m 15m 30m 1h 2h 4h 8h 12h 1d` (regime: `1h 4h 1d`). `exchange` ∈ `HL BINANCE BYBIT OKX BITGET ASTER EDGEX GATE MEXC KUCOIN PHEMEX BINGX HTX WEEX BITMART XT WHITEBIT`. Defaults match the AlgoVault server (`timeframe=15m`, `exchange=BINANCE` for trade calls). On the free tier `scan_funding_arb` caps `limit` at 5.

## Alternative: generic MCP client (no package)

AlgoVault is a standard Streamable‑HTTP MCP server, so any LlamaIndex agent can reach the same tools through the generic [`llama-index-tools-mcp`](https://pypi.org/project/llama-index-tools-mcp/) adapter — **by configuration alone, no AlgoVault‑specific code**:

```python
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

# keyless free tier
client = BasicMCPClient("https://api.algovault.com/mcp")
# paid tiers:
# client = BasicMCPClient(
#     "https://api.algovault.com/mcp",
#     headers={"Authorization": "Bearer <ALGOVAULT_API_KEY>"},
# )

spec = McpToolSpec(
    client=client,
    allowed_tools=["get_trade_call", "get_trade_signal", "get_market_regime", "scan_funding_arb"],
)
tools = spec.to_tool_list()          # or: await spec.to_tool_list_async()
```

This package (`llama-index-tools-algovault`) is the **branded, zero‑config, schema'd** wrapper of that same surface: one import, the four tools pre‑wired with typed signatures and docstrings, keyless by default. Use whichever fits — they call the identical MCP endpoint.

## Listing

Per run‑llama's current contribution policy, new integrations are **published to PyPI independently** rather than added to the `run-llama/llama_index` monorepo (which no longer accepts new integration packages). This package is therefore distributed via [PyPI](https://pypi.org/project/llama-index-tools-algovault/) and [GitHub](https://github.com/AlgoVaultLabs/llama-index-tools-algovault); a LlamaHub catalog entry is requested separately through the directory's "Request an Integration" flow.

## Development

```bash
uv run -- pytest -m "not live"   # unit tests
uv run -- pytest -m live -s      # live keyless call against api.algovault.com/mcp
uv build                         # sdist + wheel
```

## Links

- Website — <https://algovault.com>
- Track record (live PFE win‑rate) — <https://algovault.com/track-record>
- MCP server — `https://api.algovault.com/mcp`

---

Built by [AlgoVault Labs](https://algovault.com). MIT licensed.
