Metadata-Version: 2.4
Name: kickoff-cli
Version: 0.1.0
Summary: Turn a vague project idea into concrete first steps — instantly.
License: MIT
Keywords: cli,developer-tools,productivity,scaffolding
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.24
Requires-Dist: python-levenshtein>=0.21
Requires-Dist: rich>=13.0
Requires-Dist: thefuzz>=0.20
Description-Content-Type: text/markdown

<!-- Badges -->
![PyPI version](https://img.shields.io/badge/pypi-v0.1.0-blue)
![Python](https://img.shields.io/badge/python-3.9+-brightgreen)
![License](https://img.shields.io/badge/license-MIT-orange)
![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)

```
 ██╗  ██╗ ██╗  ██████╗ ██╗  ██╗ ██████╗ ███████╗███████╗
 ██║ ██╔╝ ██║ ██╔════╝ ██║ ██╔╝██╔═══██╗██╔════╝██╔════╝
 █████╔╝  ██║ ██║      █████╔╝ ██║   ██║█████╗  █████╗
 ██╔═██╗  ██║ ██║      ██╔═██╗ ██║   ██║██╔══╝  ██╔══╝
 ██║  ██╗ ██║ ╚██████╗ ██║  ██╗╚██████╔╝██║     ██║
 ╚═╝  ╚═╝ ╚═╝  ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝
```

> **Turn a vague project idea into concrete first steps — instantly.**

You have an idea. You know it's *something* to do with bots, or scrapers, or
machine learning. But you don't know which library to reach for, how to
structure the folder, or what the first five commands should be.

`kickoff` answers all three in two seconds, completely offline.

---

## Install

```bash
pip install kickoff
```

---

## Usage

### Offline mode (no API key needed)

```bash
kickoff "I want to build a REST API"
kickoff "scrape a website for prices"
kickoff "automate my daily report"
kickoff "train a model to classify images"
```

kickoff fuzzy-matches your description against a curated recipe database and
prints:

- The best-matched **project type**
- **Libraries** to reach for (with a one-line reason for each)
- **5 real terminal commands** to run right now
- A **folder layout** sketch
- The one **gotcha** that trips up beginners every time

### AI mode (Claude-powered custom advice)

```bash
export ANTHROPIC_API_KEY=sk-ant-...
kickoff "a Slack bot that summarises threads using GPT-4" --ai
```

With `--ai`, kickoff sends your idea to Claude and gets back a fully
customised recipe — same beautiful output, tailored exactly to what you
described. Falls back to offline mode silently if the API is unavailable.

---

## How it works

```
User input
    │
    ▼
matcher.py
    ├─ Exact keyword scan  ──── confidence: 100%
    └─ thefuzz partial_ratio ── confidence: 50–99%
            │ score < 50?
            └──► generic fallback
    │
    ▼ (with --ai flag)
ai.py  ──► POST /v1/messages  ──► claude-haiku-4-5-20251001
    │        JSON response parsed into recipe shape
    └─ failure? silent fallback to matcher.py
    │
    ▼
display.py  (Rich panels, colours, logo)
```

1. **matcher.py** first scans for verbatim keyword hits (e.g. `"api"` in the
   input triggers the REST API recipe with 100 % confidence). If nothing
   matches exactly, it uses `thefuzz.partial_ratio` to find the closest
   recipe. Scores below 50 fall back to the generic "Software Project" recipe.

2. **ai.py** (optional) calls the Anthropic API with a strict JSON-only system
   prompt and normalises the response into the same recipe shape that
   `display.py` expects.

3. **display.py** renders everything with Rich: a logo header, colour-coded
   panels, bold library names, green terminal commands, and a yellow gotcha
   warning.

---

## Contributing recipes

Want to add a new project type? Open `kickoff/recipes.py` and add a new entry
to the `RECIPES` dictionary. Each recipe needs:

| Key | Type | Description |
|-----|------|-------------|
| `name` | `str` | Human-readable project type name |
| `keywords` | `list[str]` | Words that trigger this recipe |
| `libraries` | `list[tuple[str, str]]` | `(package_name, one_line_reason)` pairs |
| `steps` | `list[str]` | **Exactly 5** real terminal commands |
| `structure` | `str` | Multi-line folder layout string |
| `gotcha` | `str` | One specific, non-generic beginner mistake |

The `steps` must be **real, runnable terminal commands** — not descriptions.
The `gotcha` should be something you personally got burned by, not a generic
reminder to write tests.

Once you've added the recipe, open a PR! The more specific and opinionated
the better.
