Metadata-Version: 2.5
Name: codepraxis-arena
Version: 0.5.0
Summary: CodePraxis platform client and pluggable scoring interface for hackathons, challenges, and learning sessions.
Author: CodePraxis
License: Proprietary
Keywords: cli,coding-assessment,grading,hackathon
Requires-Python: >=3.9
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == 'server'
Requires-Dist: pytest>=7; extra == 'server'
Requires-Dist: uvicorn>=0.27; extra == 'server'
Description-Content-Type: text/markdown

# codepraxis-arena

CodePraxis platform client and a pluggable **scoring interface**. Candidates
submit code from their own machine with a small CLI; the platform grades it
through one `Scorer` contract. Built to serve hackathons, coding challenges, and
learning sessions from the same seam.

## Install

```bash
pip install codepraxis-arena            # developer CLI (standard library only)
pip install "codepraxis-arena[server]"  # also install the local grading test server
```

Installed as **`codepraxis-arena`**; the typed command is **`codepraxis-arena`** and the import
package is **`codepraxis_arena`**.
This is the **developer** (competitor) CLI. The separate **company/authoring**
tool is **`codepraxis`** (`pip install codepraxis`, see `../praxis-cli`).

## Candidate CLI

Configure once against your hackathon/challenge URL + token, then submit from
your working directory:

```bash
codepraxis-arena config --server https://grade.codepraxis.co --token <your-token> --question two-sum
codepraxis-arena pull        # fetch the starter files
codepraxis-arena submit      # grade the current directory, print the score
```

Example output:

```
  ✓ test_basic
  ✓ test_last_pair
  ✓ test_middle_pair
  • hidden cases: 2/4 passed

  [█████████████████░░░░░░░]  5/7 cases
  SCORE: 71.4 / 100.0
```

## The scoring interface

Everything is a client of one contract, so new question types plug in without
touching the server or the CLI:

```python
class Scorer(ABC):
    name: str
    def score(self, question, submission_dir) -> ScoreResult: ...
```

- `codepraxis-arena.scoring.interface` — `Scorer`, `ScoreResult`, `TestCaseResult`.
  `ScoreResult.public_dict()` shows only *visible* cases (candidate view);
  `to_dict()` is the full result.
- `codepraxis-arena.scoring.scorers` — built-in backends (pytest today), each
  self-registering; drop a new one here for a new challenge type.
- `codepraxis-arena.scoring.question` — loads a challenge from `question.json`.
- `codepraxis-arena.scoring.registry` — `name -> Scorer`, keyed on a question's `scorer`.

Add a backend (SQL, web, agent-match, …) by implementing `Scorer` and
registering it; every question that names it becomes gradeable.

## Structure & extending

The CLI (`codepraxis-arena/cli/`) and scoring (`codepraxis-arena/scoring/`) are layered packages
(absolute imports throughout, like `backendServer`), built so a new challenge,
challenge *type*, or CLI command slots in without touching existing code. See
**[EXTENDING.md](EXTENDING.md)** for the layout and the three extension points.

## Local test server

```bash
pip install "codepraxis-arena[server]"
uvicorn codepraxis-arena.server.app:app --port 8099
# POST /api/submissions {question_id, files} -> run_id ; GET /api/submissions/{id} -> score
```

A sample question lives in `examples/questions/two-sum/` (starter that fails,
reference that passes, visible + hidden tests).

## Status

Early prototype. The candidate CLI and the scoring interface are stable in
shape; the bundled server is a reference implementation for local use.
