Metadata-Version: 2.4
Name: intentkit-py
Version: 0.3.0
Summary: An open-source Python library for building intent classification and execution systems that work with any AI backend.
Author-email: Stephen Collins <stephen@stephencollins.tech>
License: MIT
Project-URL: Homepage, https://github.com/Stephen-Collins-tech/intent-kit
Project-URL: Documentation, https://docs.intentkit.io
Project-URL: Repository, https://github.com/Stephen-Collins-tech/intent-kit
Project-URL: Bug Tracker, https://github.com/Stephen-Collins-tech/intent-kit/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: all
Requires-Dist: anthropic>=0.54.0; extra == "all"
Requires-Dist: google-genai>=0.1.0; extra == "all"
Requires-Dist: networkx>=3.5; extra == "all"
Requires-Dist: ollama>=0.1.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: pyvis>=0.3.2; extra == "all"
Requires-Dist: pyyaml>=6.0.2; extra == "all"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.54.0; extra == "anthropic"
Provides-Extra: dev
Requires-Dist: black[jupyter]>=24.4.2; extra == "dev"
Requires-Dist: black>=24.4.2; extra == "dev"
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: coverage>=7.0; extra == "dev"
Requires-Dist: intentkit-py[all]; extra == "dev"
Requires-Dist: ipykernel>=6.0.0; extra == "dev"
Requires-Dist: mkdocs-literate-nav>=0.6.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.5.17; extra == "dev"
Requires-Dist: mkdocs>=1.5.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest>=8.4.1; extra == "dev"
Requires-Dist: python-dotenv>=1.1.1; extra == "dev"
Requires-Dist: pyyaml; extra == "dev"
Requires-Dist: ruff>=0.4.7; extra == "dev"
Requires-Dist: tqdm; extra == "dev"
Requires-Dist: twine>=5.1.0; extra == "dev"
Requires-Dist: types-networkx>=3.5.0.20250701; extra == "dev"
Requires-Dist: types-pyyaml>=6.0.12.20250516; extra == "dev"
Provides-Extra: google
Requires-Dist: google-genai>=0.1.0; extra == "google"
Provides-Extra: ollama
Requires-Dist: ollama>=0.1.0; extra == "ollama"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: viz
Requires-Dist: networkx>=3.5; extra == "viz"
Requires-Dist: pyvis>=0.3.2; extra == "viz"
Provides-Extra: evals
Requires-Dist: pyyaml>=6.0.2; extra == "evals"
Dynamic: license-file

<p align="center">
  <img src="assets/logo.png" alt="Intent Kit Logo" height="100" style="border-radius: 16px;"/>
</p>

<h1 align="center">Intent Kit</h1>
<p align="center">Build intelligent workflows that understand what users want</p>

<p align="center">
  <a href="https://github.com/Stephen-Collins-tech/intent-kit/actions/workflows/ci.yml">
    <img src="https://github.com/Stephen-Collins-tech/intent-kit/actions/workflows/ci.yml/badge.svg" alt="CI"/>
  </a>
  <a href="https://codecov.io/gh/Stephen-Collins-tech/intent-kit">
    <img src="https://codecov.io/gh/Stephen-Collins-tech/intent-kit/branch/main/graph/badge.svg" alt="Coverage Status"/>
  </a>
  <a href="https://docs.intentkit.io">
    <img src="https://img.shields.io/badge/docs-online-blue" alt="Documentation"/>
  </a>
  <a href="https://pypi.org/project/intentkit-py">
    <img src="https://img.shields.io/pypi/v/intentkit-py" alt="PyPI"/>
  </a>
</p>

---

## What is Intent Kit?

Intent Kit helps you build AI-powered applications that understand what users want and take the right actions. Think of it as a smart router that can:

- **Understand user requests** using any AI model (OpenAI, Anthropic, Google, or your own)
- **Extract important details** like names, dates, and preferences automatically
- **Take actions** like sending messages, making calculations, or calling APIs
- **Handle complex requests** that involve multiple steps
- **Keep track of conversations** so your app remembers context

The best part? You stay in complete control. You define exactly what your app can do and how it should respond.

---

## Why Intent Kit?

### 🎯 **You're in Control**
Define every possible action upfront. No surprises, no unexpected behavior.

### 🚀 **Works with Any AI**
Use OpenAI, Anthropic, Google, Ollama, or even simple rules. Mix and match as needed.

### 🔧 **Easy to Build**
Simple, clear API that feels natural to use. No complex abstractions to learn.

### 🧪 **Testable & Reliable**
Built-in testing tools let you verify your workflows work correctly before deploying.

### 📊 **See What's Happening**
Visualize your workflows and track exactly how decisions are made.

---

## Quick Start

### 1. Install Intent Kit

```bash
pip install intentkit-py
```

For AI features, add your preferred provider:
```bash
pip install 'intentkit-py[openai]'    # OpenAI
pip install 'intentkit-py[anthropic]'  # Anthropic
pip install 'intentkit-py[all]'        # All providers
```

### 2. Build Your First Workflow

```python
from intent_kit import IntentGraphBuilder, action, llm_classifier

# Define what your app can do
greet = action(
    name="greet",
    description="Greet the user by name",
    action_func=lambda name: f"Hello {name}!",
    param_schema={"name": str}
)

weather = action(
    name="weather",
    description="Get weather for a location",
    action_func=lambda city: f"Weather in {city}: 72°F, Sunny",
    param_schema={"city": str}
)

# Create a classifier to understand user requests
classifier = llm_classifier(
    name="main",
    children=[greet, weather],
    llm_config={"provider": "openai", "model": "gpt-3.5-turbo"}
)

# Build your workflow
graph = IntentGraphBuilder().root(classifier).build()

# Test it!
result = graph.route("Hello Alice")
print(result.output)  # → "Hello Alice!"
```

### 3. Try More Examples

```python
# Get weather
result = graph.route("What's the weather in San Francisco?")
print(result.output)  # → "Weather in San Francisco: 72°F, Sunny"

# Handle multiple requests
result = graph.route("Greet Bob and check weather in NYC")
print(result.output)  # → Handles both requests!
```

---

## How It Works

Intent Kit uses a simple but powerful pattern:

1. **Actions** - Define what your app can do (send messages, make API calls, etc.)
2. **Classifiers** - Understand what the user wants using AI or rules
3. **Graphs** - Connect everything together into a workflow
4. **Context** - Remember conversations and user preferences

The magic happens when a user sends a message:
- The classifier figures out what they want
- Intent Kit extracts the important details (names, locations, etc.)
- The right action runs with those details
- You get back a response

---

## Real-World Testing

Most AI frameworks are black boxes that are hard to test. Intent Kit is different.

### Test Your Workflows Like Real Software

```python
from intent_kit.evals import run_eval, load_dataset

# Load test cases
dataset = load_dataset("tests/greeting_tests.yaml")

# Test your workflow
result = run_eval(dataset, graph)

print(f"Accuracy: {result.accuracy():.1%}")
result.save_report("test_results.md")
```

### What You Can Test

- **Accuracy** - Does your workflow understand requests correctly?
- **Performance** - How fast does it respond?
- **Edge Cases** - What happens with unusual inputs?
- **Regressions** - Catch when changes break existing functionality

This means you can deploy with confidence, knowing your AI workflows work reliably.

---

## Key Features

### 🧠 **Smart Understanding**
- Works with any AI model (OpenAI, Anthropic, Google, Ollama)
- Extracts parameters automatically (names, dates, preferences)
- Handles complex, multi-step requests

### 🔄 **Multi-Step Workflows**
- Chain actions together
- Handle "do X and Y" requests
- Remember context across conversations

### 🎨 **Visualization**
- See your workflows as interactive diagrams
- Track how decisions are made
- Debug complex flows easily

### 🛠️ **Developer Friendly**
- Simple, clear API
- Comprehensive error handling
- Built-in debugging tools
- JSON configuration support

### 🧪 **Testing & Evaluation**
- Test against real datasets
- Measure accuracy and performance
- Catch regressions automatically

---

## Common Use Cases

### 🤖 **Chatbots & Virtual Assistants**
Build intelligent bots that understand natural language and take appropriate actions.

### 🔧 **Task Automation**
Automate complex workflows that require understanding user intent.

### 📊 **Data Processing**
Route and process information based on what users are asking for.

### 🎯 **Decision Systems**
Create systems that make smart decisions based on user requests.

---

## Installation Options

```bash
# Basic installation (Python only)
pip install intentkit-py

# With specific AI providers
pip install 'intentkit-py[openai]'      # OpenAI
pip install 'intentkit-py[anthropic]'    # Anthropic  
pip install 'intentkit-py[google]'       # Google AI
pip install 'intentkit-py[ollama]'       # Ollama

# With visualization tools
pip install 'intentkit-py[viz]'

# Everything (all providers + tools)
pip install 'intentkit-py[all]'

# Development (includes testing tools)
pip install 'intentkit-py[dev]'
```

---

## Project Structure

```
intent-kit/
├── intent_kit/        # Main library code
├── examples/          # Working examples
├── docs/             # Documentation
├── tests/            # Test suite
└── pyproject.toml    # Project configuration
```

---

## Getting Help

- 📚 **[Full Documentation](https://docs.intentkit.io)** - Guides, API reference, and examples
- 🚀 **[Quickstart Guide](https://docs.intentkit.io/quickstart/)** - Get up and running fast
- 💡 **[Examples](https://docs.intentkit.io/examples/)** - See how others use Intent Kit
- 🐛 **[GitHub Issues](https://github.com/Stephen-Collins-tech/intent-kit/issues)** - Report bugs or ask questions

---

## Contributing

We welcome contributions! Here's how to get started:

```bash
git clone git@github.com:Stephen-Collins-tech/intent-kit.git
cd intent-kit
pip install -e ".[dev]"
pytest tests/
```

See our [Contributing Guide](https://github.com/Stephen-Collins-tech/intent-kit/blob/main/CONTRIBUTING.md) for more details.

---

## License

MIT License - feel free to use Intent Kit in your projects!
