Metadata-Version: 2.4
Name: imc-prospector
Version: 0.1.0
Summary: CLI submitter and algorithm validator for IMC Prosperity competition
Author: arJ-V
License: MIT License
        
        Copyright (c) 2026 arJ-V
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/arJ-V/imc-prospector
Project-URL: Issues, https://github.com/arJ-V/imc-prospector/issues
Keywords: imc,prosperity,submit,submitter,checker,validator,trading,algorithm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: keyring>=25.6.0
Requires-Dist: requests>=2.32.3
Requires-Dist: requests-toolbelt>=1.0.0
Requires-Dist: typer>=0.15.2
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.15.0; extra == "dev"
Requires-Dist: ruff>=0.9.7; extra == "dev"
Requires-Dist: types-requests>=2.32.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# imc-prospector

CLI submitter and algorithm validator for IMC Prosperity competition.

`imc-prospector` combines a static analysis checker with a command-line submitter to help you validate and submit your IMC Prosperity trading algorithms with confidence.

## Features

- ✅ **Static Analysis Checker**: Validates your algorithm against IMC Prosperity requirements before submission
- 🚀 **CLI Submitter**: Submit algorithms directly from the command line
- ⚙️ **Configurable**: Customize allowed imports and severity levels via YAML config
- 🔒 **Secure**: Uses system keyring for token storage
- 📦 **PyPI Package**: Easy installation via pip

## Installation

```bash
pip install imc-prospector
```

## Quick Start

### Check an Algorithm

```bash
# Basic check
imc-prospector check my_trader.py

# Strict mode (warnings as errors)
imc-prospector check my_trader.py --strict

# Use custom config file
imc-prospector check my_trader.py --config my_config.yaml

# JSON output for CI
imc-prospector check my_trader.py --json

# Hide info messages
imc-prospector check my_trader.py --no-info

# Don't prompt, just exit with code
imc-prospector check my_trader.py --no-prompt
```

### Submit an Algorithm

```bash
# Submit with automatic checking (default)
imc-prospector submit my_trader.py

# Submit without running checker
imc-prospector submit my_trader.py --no-check

# Submit with custom config file
imc-prospector submit my_trader.py --config my_config.yaml

# Force submission even with errors/warnings (not recommended)
imc-prospector submit my_trader.py --force

# Specify output log file
imc-prospector submit my_trader.py --out logs/my_submission.log

# Don't download logs
imc-prospector submit my_trader.py --no-out

# Combine options: strict checking with custom config
imc-prospector submit my_trader.py --config custom.yaml --strict
```

## What the Checker Validates

| Category | Checks |
|----------|--------|
| **Structure** | `Trader` class exists, `run(self, state)` method present |
| **Imports** | Only official allowed libraries (pandas, numpy, statistics, math, typing, jsonpickle) |
| **Return** | Must return 3-tuple `(result, conversions, traderData)` |
| **Timeouts** | Catches infinite loops, `time.sleep()`, deep nesting |
| **State** | Warns about instance variables (Lambda is stateless) |

## Configuration

Create `.prosperity.yaml` in your project root:

```yaml
# Override severity levels
severity:
  E001: error      # Forbidden import
  W040: warning    # Instance vars warning
  I030: off        # Disable print warnings

# Add custom allowed imports
imports:
  scipy: warn      # Allow with warning
  my_utils: true   # Custom module

# Adjust limits
limits:
  timeout_ms: 900
  max_loop_depth: 3
```

### Config Search Order

The checker searches for config files in this order:

1. `--config` argument (if provided via `check` or `submit` command)
2. `.prosperity.yaml` (current directory)
3. `.prosperity.yml` (current directory)
4. `prosperity.yaml` (current directory)
5. `prosperity_config.yaml` (current directory)
6. `~/.prosperity.yaml` (home directory)

The first config file found is used, with values merged into the default configuration.

**Note:** You can use `--config` with both `check` and `submit` commands to override the config file.

See `prosperity_config.yaml` for all available options.

## Submitting to Prosperity

### First Time Setup

On first submission, you'll be prompted for your Prosperity ID token. This token is stored securely in your system's keyring.

**How to get your token:**
1. Open the Prosperity website in your browser
2. Press F12 to open developer tools
3. Go to Application (Chrome) or Storage (Firefox) tab
4. Click on Local Storage → select the Prosperity website
5. Find the key: `CognitoIdentityServiceProvider.<some id>.<email>.idToken`
6. Copy the token value

The token is stored securely and you'll only need to update it when it expires.

### Submission Process

1. **Check** (optional, runs by default): Validates your algorithm
   - Errors block submission by default (use `--force` to bypass)
   - Warnings prompt for confirmation (use `--force` to skip prompt)
2. **Submit**: Uploads to Prosperity API
3. **Monitor**: Watches submission status
4. **Download**: Saves logs to `submissions/<timestamp>.log` (unless `--no-out`)

### Submission Options

| Option | Description |
|--------|-------------|
| `--no-check` | Skip running the checker before submission |
| `--config`, `-c` | Use a custom YAML config file for the checker |
| `--strict` | Treat checker warnings as errors |
| `--force` | Force submission even if checker finds errors/warnings (not recommended) |
| `--out`, `-o` | Specify output log file path |
| `--no-out` | Don't download submission logs |

## Handling Checker Errors and Warnings

When submitting, the checker runs automatically and handles issues as follows:

- **Errors**: Block submission by default. Use `--force` to bypass (not recommended).
- **Warnings**: Prompt for confirmation. Use `--force` to skip the prompt and continue automatically.

**Example:**
```bash
# Checker finds errors - submission blocked
$ imc-prospector submit my_trader.py
Running algorithm checker...
❌ Checker found 2 error(s) and 1 warning(s):
  ❌ [E001]:5 Forbidden import: 'os'
  ❌ [E033]:45 run() returns only a dict, must return 3-tuple
  ⚠️  [W040]:10 Instance vars {'position'} may not persist

❌ Submission aborted due to errors. Fix issues and try again.
   Use --force to bypass errors (not recommended).

# Force submission despite errors (use with caution)
$ imc-prospector submit my_trader.py --force
Running algorithm checker...
⚠️  Errors found but --force flag used. Continuing with submission...
```

## Error Codes

| Code | Severity | Description |
|------|----------|-------------|
| E001 | Error | Forbidden/unsupported import |
| E002 | Error | Missing datamodel import |
| E003 | Error | Missing Trader class |
| E004 | Error | Missing run method |
| E010 | Error | Invalid run() signature |
| E020 | Error | Infinite loop detected |
| E021 | Error | time.sleep() detected |
| E030 | Error | Missing return statement |
| E031 | Error | Returns None |
| E032 | Error | Wrong return tuple size |
| E033 | Error | Returns dict instead of tuple |
| W020 | Warning | Risky while True loop |
| W021 | Warning | Loop variable not modified |
| W022 | Warning | Deep loop nesting |
| W030 | Warning | Can't verify return tuple |
| W040 | Warning | Instance variables won't persist |

## Example Output

```
============================================================
  IMC Prosperity Checker: my_trader.py
============================================================

ERRORS (2):
----------------------------------------
  ❌ [E001]:2 Forbidden import: 'os'
   💡 Remove 'import os'. Official allowed: pandas, numpy, statistics, math, typing, jsonpickle

  ❌ [E033]:45 run() returns only a dict, must return 3-tuple
   💡 return result, conversions, traderData

============================================================
Official requirements:
  • Imports: pandas, numpy, statistics, math, typing, jsonpickle
  • Return: (result, conversions, traderData)
  • Timeout: <900ms per run() call
============================================================
```

## Minimal Valid Trader

```python
from datamodel import OrderDepth, TradingState, Order
from typing import List

class Trader:
    
    def run(self, state: TradingState):
        result = {}
        
        for product in state.order_depths:
            orders: List[Order] = []
            # Your trading logic here
            result[product] = orders
        
        traderData = ""  # Use jsonpickle to persist state
        conversions = 0
        
        return result, conversions, traderData
```

## Development

```bash
# Clone the repository
git clone https://github.com/arJ-V/imc-prospector.git
cd imc-prospector

# Install in development mode
pip install -e ".[dev]"

# Run linter
ruff check imcprospector/

# Run type checker
mypy imcprospector/
```

## License

MIT

## Acknowledgments

- Based on the checker from `imc-prospector` and submitter structure from `imc-prosperity-3-submitter`
- Uses the same API endpoint as the official Prosperity platform
