Metadata-Version: 2.4
Name: valodesk
Version: 0.1.0
Summary: Conversational CLI agent for VCT esports match/stats questions
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: langchain
Requires-Dist: langgraph
Requires-Dist: langchain-openai
Requires-Dist: langchain-mcp-adapters
Requires-Dist: mcp
Requires-Dist: python-dotenv
Requires-Dist: requests
Requires-Dist: rich

# ValoDesk

A conversational CLI agent for VCT (Valorant Champions Tour) esports questions. Ask about
upcoming matches, a team's map stats, head-to-heads, or region player leaderboards, in plain
English, from your terminal.

```
You: What's G2's record on Ascent?
Agent: G2's record on Ascent is as follows:
- Total games: 41
- Wins: 26
- Losses: 15
- Win percentage: 63%
```

## How it works

- An LLM-based agent (LangGraph + GPT-4o-mini) decides which tool to call based on your question.
- Tools are served over MCP (Model Context Protocol) by a local server process, which wraps a
  data client hitting `vlrggapi`, an unofficial vlr.gg API wrapper.
- Conversation memory means follow-up questions ("and on Bind?") work without repeating context.

## Requirements

- Python 3.11+
- Your own OpenAI API key
- A running `vlrggapi` instance (self-hosted; see below)

## Install

```
pipx install valodesk
```

## Set up vlrggapi

`valodesk` depends on a separate, self-hosted API that scrapes vlr.gg. Clone and run it
separately:

```
git clone https://github.com/axsddlr/vlrggapi
cd vlrggapi
# follow its own README to install deps and run it
# it should be listening on http://127.0.0.1:3001
```

## First run

```
valodesk <your-openai-api-key>
```

This saves your key to `~/.valodesk/.env`. Every run after that, just:

```
valodesk
```

## Tools available

| Tool | What it answers |
|---|---|
| `get_matches` | Upcoming matches, optionally for one team, optionally limited to N results |
| `get_map_stats` | A team's win/loss record on one map, or every map |
| `get_h2h` | Past matches between two specific teams |
| `get_region_stats` | A region's player stats leaderboard, optionally for one team's players |

## Known limitations

- `get_matches` only sees roughly the next week of scheduled matches (a limitation of the
  upstream API's "upcoming" query, which doesn't support pagination).
- Cross-tool questions like "best map" or "who's performing best" work by the agent reasoning
  over one tool's full data, not a dedicated tool for every possible question.
