# Quick Start Guide

**Canonical source for installation and first run.** For full documentation index see [docs/DOCUMENTATION_INDEX.md](docs/DOCUMENTATION_INDEX.md).

## Installation (1 minute)

**Option 1: Install from PyPI (easiest)**

```bash
pip install upgrade-policy-optimizer
```

This installs the latest release from [PyPI](https://pypi.org/project/upgrade-policy-optimizer/). After this, run `python3 -m upo.cli` from any directory.

**Option 2: Install from source (for development)**

```bash
git clone https://github.com/eonof/upgrade-policy-optimizer
cd upgrade-policy-optimizer
pip3 install -e .   # Basic install
# Or with development dependencies (testing tools):
pip3 install -e ".[dev]"
```

**Important**: Use the same Python interpreter that has the package. If using `uv pip`, you may need `uv run python3 -m upo.cli` instead.

**Option 3: Use without installing (quick testing from a clone)**

```bash
pip3 install -r requirements.txt
PYTHONPATH=src python3 -m upo.cli examples/configs/manufacturing_process.json
```

Or from Python: `sys.path.insert(0, 'src')` then `from upo import solve_from_json`.

## Test It Works (30 seconds)

```bash
pytest tests/ -v
```

Expected: 32 passed. For coverage and full testing guide see [TESTING.md](TESTING.md).

## Run an Example (30 seconds)

**If package is installed:**

```bash
python3 -m upo.cli examples/configs/manufacturing_process.json
# or: upo-solve examples/configs/manufacturing_process.json
```

**If not installed:**

```bash
PYTHONPATH=src python3 -m upo.cli examples/configs/manufacturing_process.json
```

More example configs: [examples/configs/README.md](examples/configs/README.md).

## Your First MDP (2 minutes)

Create `my_first_mdp.py`:

```python
import sys
sys.path.insert(0, 'src')  # Omit if package is installed

from upo import MDP, solve_mdp_value_iteration

mdp = MDP.from_dict(
    states=["start", "goal"],
    terminal_states=["goal"],
    transitions_dict={
        "start": {
            "quick": {"goal": 0.6, "start": 0.4},
            "careful": {"goal": 0.9, "start": 0.1}
        }
    },
    costs_dict={"start": {"quick": 1.0, "careful": 2.0}}
)

result = solve_mdp_value_iteration(mdp)
print(f"Optimal action: {result.get_policy('start')}")
print(f"Expected total cost: {result.get_value('start'):.2f}")
```

Run: `python3 my_first_mdp.py`. You should see optimal action **quick** and expected cost ~1.67 (quick is cheaper overall despite lower success rate).

## Next Steps

- **API reference and more examples**: [README.md](README.md#api-reference)
- **When to use this tool / real-world examples**: [docs/PRACTICAL_GUIDE.md](docs/PRACTICAL_GUIDE.md)
- **JSON format**: [docs/JSON_GUIDE.md](docs/JSON_GUIDE.md)
- **Algorithm explanation**: [docs/WALKTHROUGH.md](docs/WALKTHROUGH.md)
- **Full documentation index**: [docs/DOCUMENTATION_INDEX.md](docs/DOCUMENTATION_INDEX.md)

Requirements: Python 3.9+, numpy. MIT License.
