Metadata-Version: 2.4
Name: llm-quick-tools
Version: 0.1.0
Summary: Prompt evaluation and mock LLM for testing
Home-page: https://github.com/aryanator/llm-tools
Author: Aryan
Author-email: aryanator01@gmail.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21.0
Requires-Dist: transformers>=4.26.0
Requires-Dist: torch>=1.13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# LLM Tools 🧰

![PyPI](https://img.shields.io/pypi/v/llm-tools)
![Python](https://img.shields.io/pypi/pyversions/llm-tools)

A dual-purpose library for:
1. **Prompt Evaluation** - Score and improve LLM inputs
2. **Mock LLM** - Simulate API responses during development

## Installation

```bash
pip install llm-tools
```

---

## 1. Prompt Scoring 🔍

Evaluate prompt quality across multiple dimensions.

### Quick Start
```python
from llm_tools import PromptEvaluator

evaluator = PromptEvaluator()
scores = evaluator.evaluate(
    "Explain quantum computing to a 5-year-old",
    task="education"
)

print(scores)
```
**Output:**
```python
{
    'length': 0.38,        # Optimal 20-100 chars
    'clarity': 0.9,        # Sentence structure
    'toxicity': 0.02,      # Harmful content risk
    'task_alignment': 0.8  # Relevance to education
}
```

### Scoring Metrics
| Metric | Range | Ideal | Description |
|--------|-------|-------|-------------|
| Length | 0-1 | 0.3-0.7 | Prompt character length |
| Clarity | 0-1 | >0.8 | Sentence complexity |
| Toxicity | 0-1 | <0.1 | Risk of harmful content |
| Task Alignment | 0-1 | >0.7 | Relevance to specified task |

---

## 2. Mock LLM 🤖

Simulate LLM responses without API calls.

### Response Modes
```python
from llm_tools import MockLLM

# Initialize with different modes
echo_llm = MockLLM(mode="echo")
template_llm = MockLLM(mode="template")
```

#### Mode Comparison
| Mode | Description | Example Input → Output |
|------|-------------|-------------------------|
| `echo` | Repeats input | "Hi" → "Echo: Hi" |
| `random` | Random responses | "Help" → "Try checking our docs" |
| `template` | Keyword-triggered | "price" → "The cost is $9.99" |

### Template Management
```python
# Add custom templates
template_llm.add_template(
    "contact support",
    "Email us at help@company.com"
)

# Load from JSON
template_llm.load_templates("path/to/templates.json")

# Generate responses
print(template_llm.generate("How to contact support?"))
# Output: "Email us at help@company.com"
```

#### Pre-Loaded Templates
```python
{
    "hello": "Hi! How can I help?",
    "goodbye": "Have a nice day!",
    "pricing": "Our plans start at $9.99/mo",
    "refund": "Refunds take 5-7 business days",
    "tech support": "Try restarting your device"
}
```

---

## Advanced Usage

### Combined Workflow
```python
# 1. Evaluate prompt
scores = evaluator.evaluate("Tell me a joke about AI")

# 2. Generate mock response
if scores['toxicity'] < 0.1:
    response = template_llm.generate("Tell me a joke about AI")
else:
    response = "I can't comply with that request"
```

### Custom Template JSON
```json
// custom_templates.json
{
    "feature request": "Added to our roadmap",
    "bug report": "We'll investigate this issue",
    "order {} status": "Order #{} ships in 2 days"
}
```

---

## Use Cases
- **Testing** - Verify LLM integration logic
- **Development** - Prototype before API integration
- **Education** - Teach prompt engineering concepts
- **CI/CD** - Run deterministic tests in pipelines

---

## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit changes (`git commit -m 'Add feature'`)
4. Push (`git push origin feature/AmazingFeature`)
5. Open a PR

---

## License
MIT © [Aryan](https://github.com/aryanator)
