Metadata-Version: 2.4
Name: devils-help
Version: 1.0.1
Summary: A password-locked personal AI assistant to solve coding problems from text or screenshots
Home-page: https://github.com/madhav/devils-help
Author: Madhav
License: MIT
Keywords: ai,assistant,groq,llama,competitive-programming,solver,vision
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: groq>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"
Dynamic: license-file

# 🔥 devils-help

> **Your Personal AI Devil — a password-locked coding assistant powered by Groq's Llama 4 Scout model.**

`devils-help` solves competitive programming problems and software engineering challenges directly from plain text or screenshots. The Groq API key is pre-baked into the package — you only need a password to unlock it.

---

## Installation

```bash
pip install devils-help
```

**Requires Python ≥ 3.9**

---

## Quick Start

```python
import devil

# 1. Authenticate — raises AuthenticationError on wrong password
cn = devil.connect(pwd="devil123")

# 2. Solve from plain text (returns Python code only)
cn.ask(text="Find the longest increasing subsequence", mode="code", lang="python")

# 3. Explain a problem from a screenshot
cn.ask(image="problem.png", mode="explain")

# 4. Full solution — explanation + code, saved to a file
cn.ask(
    text="Solve this",
    image="q.png",
    mode="both",
    lang="cpp",
    prompt="Optimize for O(n log n)",
    save="output/solution.txt",
)
```

---

## `ask()` Parameters

| Parameter | Type   | Required | Description                                                              |
|-----------|--------|----------|--------------------------------------------------------------------------|
| `text`    | `str`  | Optional* | The problem description as a plain-text string.                         |
| `image`   | `str`  | Optional* | File path to a screenshot or image of the problem (`.png`, `.jpg`, `.webp`). |
| `mode`    | `str`  | Optional | Response style — `"code"`, `"explain"`, or `"both"` (default: `"both"`). |
| `lang`    | `str`  | Optional | Target programming language, e.g. `"python"`, `"cpp"`, `"java"`.       |
| `prompt`  | `str`  | Optional | Additional custom instruction appended to the system prompt.             |
| `save`    | `str`  | Optional | File path to save the response to (parent dirs are created as needed).   |

> \* At least one of `text` or `image` must be provided. Both can be used together.

---

## Modes

| Mode      | What it does                                                                               |
|-----------|-------------------------------------------------------------------------------------------|
| `"code"`  | Returns **only raw executable code** — no explanations, no markdown, no backticks.       |
| `"explain"` | Returns a **structured explanation** — summary, observations, algorithm, complexity — no code. |
| `"both"`  | Returns an **explanation followed by complete code**, separated by `--- CODE ---`.         |

---

## Supported Image Formats

| Extension          | MIME type      |
|--------------------|----------------|
| `.png`             | `image/png`    |
| `.jpg` / `.jpeg`   | `image/jpeg`   |
| `.webp`            | `image/webp`   |

---

## Notes

- **API key** — Pre-configured inside the package. End-users never need to set or see it.
- **Password** — Required to access the assistant via `devil.connect(pwd=...)`. The password is never stored in plaintext — only its SHA-256 hash is used for verification.
- **Model** — Uses Groq's `meta-llama/llama-4-scout-17b-16e-instruct` (vision-capable).

---

## License

MIT © 2025 Madhav
