Metadata-Version: 2.4
Name: vorepo-agents
Version: 0.3.7
Summary: Open-source Python framework for building autonomous AI trading agents on GitHub repository momentum (paper mode).
Author: Vorepo
License: MIT
Project-URL: Homepage, https://vorepo.com
Project-URL: Repository, https://github.com/Vorepo-com/vorepo-agents
Project-URL: Issues, https://github.com/Vorepo-com/vorepo-agents/issues
Keywords: github,github-momentum,trading,agents,ai-agents,open-source,paper-trading,backtesting
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: pydantic<3.0,>=2.6
Requires-Dist: typer<1.0,>=0.12
Requires-Dist: python-dotenv>=1.0
Provides-Extra: llm
Requires-Dist: chromadb<1.0,>=0.5; extra == "llm"
Requires-Dist: openai>=1.30; extra == "llm"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Dynamic: license-file

# Vorepo Agents Framework

> Build autonomous AI trading agents for **GitHub repository momentum**.
> MIT · Paper-mode only · Python 3.10+

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
![Paper mode](https://img.shields.io/badge/mode-paper--trading-green.svg)
[![GitHub stars](https://img.shields.io/github/stars/Vorepo-com/vorepo-agents?style=social)](https://github.com/Vorepo-com/vorepo-agents/stargazers)
[![GitHub last commit](https://img.shields.io/github/last-commit/Vorepo-com/vorepo-agents)](https://github.com/Vorepo-com/vorepo-agents/commits/main)
[![GitHub issues](https://img.shields.io/github/issues/Vorepo-com/vorepo-agents)](https://github.com/Vorepo-com/vorepo-agents/issues)

---

```text
$ vorepo-agents top --limit 8

MICMARKI   2153     stars/24h  microsoft/markitdown
HARMONEY   2111     stars/24h  harry0703/MoneyPrinterTurbo
LUMUNDER   1512     stars/24h  Lum1104/Understand-Anything
CODBUILD   1125     stars/24h  codecrafters-io/build-your-own-x
COLCODEG   1108     stars/24h  colbymchenry/codegraph
NOUHERME   1050     stars/24h  NousResearch/hermes-agent
AFFEVERY   1011     stars/24h  affaan-m/everything-claude-code
MULANDRE    941     stars/24h  multica-ai/andrej-karpathy-skills
```

*Live output from the public Vorepo API. Updated continuously.*

---

## Why this exists

When a GitHub repo gets hot — stars accelerating, contributors joining,
real product traction landing — its mindshare moves before any market
reflects it. `vorepo-agents` lets you:

- **See momentum the moment it shifts.** Live star velocity, contributor
  growth, news mentions, all in one signal.
- **Stress-test your strategy** over N runs against the live
  market in paper mode (real signals, simulated execution).
  Historical replay is on the roadmap.
- **Add qualitative LLM context** on top of the quantitative signal.
  Feed Trending + Hacker News + Reddit news into RAG and let the model
  weigh the news against the velocity numbers.
- **Write your own strategy** in ~50 lines by subclassing one base class.

Built as a thin client on the public Vorepo API. Adapted from
[Polymarket/agents](https://github.com/Polymarket/agents) (MIT). Same
clean modular architecture, re-pointed at GitHub momentum instead of
prediction markets. The on-chain stack was removed; Vorepo settles via
a simple REST API.

---

## Quickstart (2 minutes)

```bash
git clone https://github.com/Vorepo-com/vorepo-agents.git
cd vorepo-agents
python3 -m venv venv && source venv/bin/activate
pip install -e .

# list tradeable repos
vorepo-agents repos --limit 10

# top repos by 24h star velocity (the momentum signal)
vorepo-agents top --limit 10

# run a strategy in PAPER mode ($100 virtual)
vorepo-agents run --strategy momentum --balance 100 --top-n 5 --per-trade 10
# strategies: momentum | dip_buy | mean_reversion

# multi-run benchmark (N runs vs the live market, aggregated stats — not a historical replay)
vorepo-agents backtest --strategy momentum --runs 5
```

Sample `agent.run_once()` output:

```json
{
  "strategy": "momentum",
  "actions_executed": 5,
  "portfolio": {
    "starting_balance": 100.0,
    "portfolio_value": 99.53,
    "pnl_pct": -0.47,
    "trades": 5
  }
}
```

Sample `backtest` output (5 runs aggregated):

```json
{
  "strategy": "momentum",
  "runs": 5,
  "avg_pnl_pct": -0.31,
  "best_pnl_pct": 0.42,
  "worst_pnl_pct": -0.89,
  "stdev": 0.51
}
```

---

## Use cases

- **Dev researchers** quantifying "is this repo hot" hypothesis-free,
  with reproducible numbers.
- **Maintainers** monitoring competitors and key dependencies for
  velocity inflection points.
- **Indie hackers** paper-trading hunches on developer-trend cycles
  before they go mainstream.
- **AI engineers** wiring repo-momentum signals into LLM pipelines and
  agent loops.
- **Educators** teaching trading-system design and backtesting without
  real-money risk.

---

## How it works

```
vorepo_agents/
  client.py              # VorepoClient — public Vorepo API (read)
  trader.py              # PaperTrader — simulated execution, virtual balance
  objects.py             # pydantic models (Repo, Quote, TradeResult)
  strategies/
    base.py              # Strategy interface (subclass + implement decide())
    momentum.py          # buy top-N by star velocity
    dip_buy.py           # buy dips that still have velocity
    mean_reversion.py    # buy oversold-vs-24h with healthy velocity
  connectors/
    news.py              # GitHub Trending + Hacker News + Reddit
  application/
    agent.py             # the autonomous decision loop
  backtest.py            # run a strategy N× vs live market, aggregate
  cli.py                 # command-line interface
```

Full architecture notes: [docs/architecture.md](docs/architecture.md).

---

## Write your own strategy

```python
from vorepo_agents.strategies.base import Strategy, Action

class MyStrategy(Strategy):
    name = "my_strategy"

    def decide(self) -> list[Action]:
        repos = self.client.get_repos(category="ai-ml", limit=50)
        picks = [r for r in repos if (r.star_velocity_24h or 0) > 100]
        return [
            Action(side="buy", ticker=r.ticker, usdc_amount=10.0,
                   reason=f"{r.full_repo_name} hot")
            for r in picks[:3]
        ]
```

Then run it via the `Agent`:

```python
from vorepo_agents.application.agent import Agent
from vorepo_agents.trader import PaperTrader

agent = Agent(strategy=MyStrategy(), trader=PaperTrader(starting_balance=100))
print(agent.run_once())
```

---

## LLM-powered strategies (optional)

```bash
pip install -r requirements-llm.txt
```

Then feed GitHub Trending + Hacker News + Reddit news through Chroma
RAG into an LLM to add qualitative context on top of the quantitative
velocity signal. Worked examples in
[docs/llm_strategy.md](docs/llm_strategy.md).

---

## Why paper-only

This framework ships **paper-trading only**. No wallet keys, no real
money, no live order endpoint. Wiring it to a funded account is
intentionally left to you, and is subject to
[Vorepo's Terms of Service](https://vorepo.com/terms.html).

We follow (and go further than) the Polymarket/agents safety pattern:
their live order is commented out behind a ToS notice. Ours simply
isn't shipped.

---

## What this framework does NOT contain

By design, this is a **client** for the public Vorepo API. It does
**not** contain, and cannot reveal, Vorepo's pricing methodology,
internal constants, or platform-side execution logic. Those are
proprietary and out of scope. This framework only consumes documented
public endpoints.

---

## Roadmap

- Historical-replay backtester (deterministic replays of past market
  data, beyond the live-market multi-run aggregation already shipping).
- More signal connectors: Lobsters, dev.to trending, npm / PyPI /
  crates.io download velocity, package-manager-level signals.
- Strategy plugin system — load custom strategies from PyPI packages.
- Notebook-friendly API for Jupyter exploration.

Open an issue or thumbs-up an existing one. Community drives priorities.

---

## Contributing

PRs welcome. Fork, branch, tests, PR. See
[CONTRIBUTING.md](CONTRIBUTING.md). Good first issues:

- New strategies (category-rotation, LLM-scored, time-of-day).
- New signal connectors (Lobsters, dev.to, package managers).
- Backtesting harness improvements.
- Edge-case test coverage.

---

## License

MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE) for the Polymarket
attribution.

---

## Stay in the loop

The Vorepo platform that powers this framework is **pre-launch**.
Early access and new-strategy announcements go to
[vorepo.com/waitlist.html](https://vorepo.com/waitlist.html) first.

---

*Vorepo Agents Framework is an independent open-source project.
Not financial advice. Trading involves risk; this framework ships in
simulation mode for education and research.*
