Metadata-Version: 2.4
Name: ready-player-one
Version: 0.1.0
Summary: A gamified terminal project builder: build with AI characters, earn XP, and beat an AI opponent in coding contests - free-tier models only.
Keywords: ai,textual,tui,crewai,google-adk,gamified,learning
Author: Samarth
Author-email: Samarth <samarthgoss@gmail.com>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Topic :: Software Development
Requires-Dist: crewai>=1.15.22
Requires-Dist: google-adk>=2.9.1,<3
Requires-Dist: google-genai>=2.24.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: litellm>=1.101.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pyjwt>=2.14.0
Requires-Dist: pytest>=9.1.1
Requires-Dist: python-dotenv>=1.2.3
Requires-Dist: redis>=8.1.0
Requires-Dist: rich>=14.3.4
Requires-Dist: textual>=8.2.8
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Ready Player One

A gamified project builder for your terminal. You build a real project in your
current folder with AI characters at your side, earn XP, level up, and can
challenge an AI opponent to a coding contest. It runs entirely on **free-tier**
models: nothing here needs a paid plan.

- **ADK** is the harness: session, XP, routing, the Doctor -> Healer workflow.
- **CrewAI** powers every character.
- **Textual** is the interface.

## Install

```bash
pip install ready-player-one      # or: uv tool install ready-player-one
```

Python 3.12+.

## Getting your free API keys

The game talks to AI models, and each player uses **their own free keys**. No key is
included in the package, and nothing is charged: every provider below has a free tier.
You need at least one; **Gemini is the recommended main key**, and the other two are backups for
when Gemini's free limit is used up.

| Provider | Needed? | What it is for | Get a key |
|---|---|---|---|
| **Gemini** (Google AI Studio) | **Recommended** | The main model | <https://aistudio.google.com/apikey> |
| **Groq** | Optional | First fallback: several free models | <https://console.groq.com/keys> |
| **OpenRouter** | Optional | Last fallback: free models only | <https://openrouter.ai/keys> |

### 1. Create the keys
For each provider: sign in (a free account is enough), choose **Create API key**, and copy it.
Treat a key like a password. Don't paste it into chats, screenshots or public repositories.

### 2. Put them in a `.env` file
Create a file named `.env` in the folder where you will run `rpo` (a parent folder also works):

```
GOOGLE_API_KEY=paste-your-gemini-key-here
GEMINI_API_KEY=paste-the-same-gemini-key-here
GROQ_API_KEY=paste-your-groq-key-here            # optional
OPENROUTER_API_KEY=paste-your-openrouter-key-here  # optional
```

- Use the **same Gemini key on both lines**: one is read by the framework that routes your
  requests, the other by the one that runs the characters.
- Leave out any line you don't have a key for.
- No quotes and no spaces around the `=`.
- Prefer not to keep a file? Export the variables in your shell instead, for example
  `export GOOGLE_API_KEY=... GEMINI_API_KEY=...`.

The game never reads, writes or shows your `.env` from inside a session, and your keys are
removed from the environment of every test it runs.

### 3. Check it worked
```bash
rpo providers
```
You should see your models listed as `ready`, for example Gemini first, then any Groq and
OpenRouter models that were found. If it says "No providers configured", no key was found: check
that `.env` is in the folder you ran the command from.

### Good to know
- **Free limits are small.** Gemini's free tier allows only a few requests a minute and a
  daily cap. When it runs out, the game moves on to Groq and then OpenRouter (if you added
  those keys) and tells you which model answered. With only a Gemini key, you may occasionally
  see a "rate limited" message: wait a minute and try again.
- **Limits change.** Providers adjust their free tiers and available models from time to time.
  `rpo providers` shows what your keys can reach today.
- **A warning about two Gemini keys** ("Both GOOGLE_API_KEY and GEMINI_API_KEY are set") is
  harmless and goes to the log file, not your screen.
- **Key leaked or lost?** Delete it in the provider's console, create a new one, and update
  your `.env`.

## Use

```bash
rpo                 # launch the game (login, pick a class, main menu)
rpo login          # sign in or create a local profile
rpo whoami | logout
rpo leaderboard    # local XP ranking
rpo providers      # fallback chain status
rpo --version
```

**Character classes:** Architect, Hacker, Artisan, Explorer.

**Build Harness** - chat with your characters about the project in the current
folder:

| Character | Role |
|---|---|
| Friend | writes code with you |
| Mentor | explains and reviews |
| Alchemy | transforms/refactors code |
| Doctor | diagnoses failures |
| Healer | fixes what the Doctor found |

Every file write asks for your approval first. `.env*`, `.git` and `.rpo` are
never touched.

**Contest Lobby** - pick Easy, Medium or Hard, get a brief and hand-code a
solution with no helpers. An AI opponent builds its own. Hidden tests score
correctness (70 pts) and a blind judge, The Arbiter, scores style (30 pts).
Winning earns XP by difficulty; unfinished contests can be resumed from the
lobby. Work lives in `<project>/.rpo/contests/`.

## Fallback chain and cache

Gemini first, then every free Groq model that supports tools, then free
OpenRouter models. Only rate limits, quota, overload and bad keys move a call
along; the conversation context is carried across switches. Cooldowns, model
discovery and context are cached in SQLite (`~/.ready_player_one`), or in Redis
if `REDIS_URL` is set. Optional settings are listed in `.env.example`.

## Data and privacy

Profiles, the JWT session, cache and log (`rpo.log`) live in
`~/.ready_player_one`. JWTs are issued and verified locally. API keys are
stripped from the environment of every subprocess that runs tests. Your code is
sent only to the model providers you configured.

## Troubleshooting

- *"rate limited"*: add a Groq/OpenRouter key so the chain has somewhere to go.
- *Not a terminal*: `rpo` needs an interactive terminal.
- Anything odd: check `~/.ready_player_one/rpo.log`.

## Development and publishing

```bash
uv sync --dev
uv run pytest
# optional: also test the cache against a real Redis
docker run --rm -d --name rpo-redis -p 6390:6379 redis:7-alpine
RPO_TEST_REDIS_URL=redis://localhost:6390/0 uv run pytest tests/test_cache_redis_live.py
uv build              # writes dist/
uv publish            # needs a PyPI token; choose a license first
```

## License

Proprietary, all rights reserved. You may install and run Ready Player One; you may not copy,
modify or redistribute it. See `LICENSE`.
