agents

The Problem

Manual interaction with Polymarket’s prediction‑market API is error‑prone and requires repetitive data‑fetch, prompt‑engineering, and order‑signing steps. Teams that want autonomous trading must stitch together API clients, a vector store for news retrieval, and LLM calls themselves, which slows experimentation and increases risk of bugs.

What This Does

The repo implements a modular framework that ties Polymarket API clients (agents/polymarket/polymarket.py, agents/polymarket/gamma.py) to LLM‑driven trading logic (agents/application/executor.py, agents/application/trade.py). Connectors for external data (agents/connectors/chroma.py, agents/connectors/news.py) supply Retrieval‑Augmented Generation (RAG) inputs. The command‑line interface in scripts/python/cli.py exposes three high‑level actions:

• run_autonomous_trader – runs a full trade loop using the best‑available market.
• create_market – selects and creates a market based on LLM‑generated recommendations.
• ask_polymarket_llm – forwards an arbitrary prompt to the Polymarket‑specific LLM prompt set.

All code lives under the agents/ package; the Dockerfile and accompanying Bash scripts enable containerised execution.

How It Is Wired

Execution begins at the entry point scripts/python/cli.py. The most used command, run_autonomous_trader (line 119), invokes the following chain (counts are from the static call graph):

1. CLI → run_autonomous_trader calls one_best_trade in agents/application/trade.py (6 functions, 1 class).
2. one_best_trade → source_best_trade (via self.llm.invoke) in agents/application/executor.py. This is the only LLM‑inference hop, accounting for 6 outbound model calls across the repo.
3. source_best_trade → get_llm_response → market_analyst prompt defined in agents/application/prompts.py.
4. Trade execution ultimately reaches Polymarket class (agents/polymarket/polymarket.py) which performs signed HTTP calls (httpx) to the Polymarket DEX.

The hub modules are:

• agents/application/executor.py – 15 functions, 1 class, called from 3 files, mediates LLM calls and token estimation.
• agents/polymarket/polymarket.py – 22 functions, 1 class, called from 4 files, handles all network interactions.
• agents/polymarket/gamma.py – 13 functions, 1 class, supplies market listings used by both creator and trade flows.

The largest blast radius is agents/application/executor.py (instability 0.63) because many modules import it and it forwards LLM requests; a change here can affect trade, market‑creation, and CLI commands. No circular imports were detected, simplifying refactoring.

File‑level responsibilities (excerpt):

Unmapped areas: background scheduling (agents/application/cron.py) and the web server (scripts/python/server.py) are present but not traversed by the current entry‑point analysis.

How To Use It

# Clone the exact repository
git clone https://github.com/moses-y/agents
cd agents

# Build and run via Docker (recommended)
./scripts/bash/build-docker.sh
./scripts/bash/run-docker-dev.sh   # launches the CLI inside the container

# Or run locally
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Populate environment variables
cp .env.example .env
# Edit .env and set POLYGON_WALLET_PRIVATE_KEY and OPENAI_API_KEY

# Execute the autonomous trader
python scripts/python/cli.py run_autonomous_trader

The README already lists these steps; the commands above follow them verbatim.

Real‑World Use

A quant‑fund could schedule run_autonomous_trader via cron (see agents/application/cron.py) to evaluate all tradable Polymarket events nightly, let the LLM pick the highest‑expected‑value market, and automatically place a signed order. The flow would be:

from agents.application.executor import Executor
from agents.application.trade import Trade

executor = Executor()
trade = Trade(executor)
trade.run_autonomous_trader()   # same logic as the CLI command

All network traffic is confined to the Polymarket API and the LLM provider, while local state (e.g., cached markets) lives in the agents/connectors/chroma.py SQLite store.

Code Health & Issues

• MEDIUM – GITHUB_TOKEN permissions – .github/workflows/docker-image.yml lacks an explicit permissions block.
• MEDIUM – Dependabot missing – No .github/dependabot.yml despite a requirements.txt.
• MEDIUM – Docker base image not pinned – Dockerfile uses python:3.9 tag instead of a digest.
• MEDIUM – Checkout persists credentials – .github/workflows/python-app.yml does not set persist-credentials: false.
• LOW – Job timeouts undefined – .github/workflows/dependency-review.yml has no timeout-minutes.
• MEDIUM – Broad exception handling – agents/application/trade.py catches generic except blocks, masking errors.
• MEDIUM – Duplicated code – Similar 6‑line blocks appear in agents/application/creator.py and agents/application/trade.py; extracting helpers would improve DRYness.
• Low risk – No lockfile; builds rely on requirements.txt only, which can lead to non‑reproducible environments.

Other hygiene points: CI is present, Dockerfile exists, MIT licence is included, no secrets detected.

The Bottom Line

The repository delivers a clear, modular stack for LLM‑driven Polymarket trading, with a well‑defined CLI and Docker workflow. However, the codebase contains medium‑severity operational risks (unrestricted token permissions, missing dependency automation, broad exception handling) that should be addressed before production use. It is suited for developers comfortable with Python 3.9, LLM APIs, and containerised deployment, who can tolerate modest refactoring to tighten security and reproducibility.