intentkit-py 0.4.0

An open-source Python library for building intent classification and execution systems that work with any AI backend.

Intent Kit

Build intelligent workflows that understand what users want

---

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

pip install intentkit-py

For AI features, add your preferred provider:

pip install 'intentkit-py[openai]'    # OpenAI
pip install 'intentkit-py[anthropic]'  # Anthropic
pip install 'intentkit-py[all]'        # All providers

2. Build Your First Workflow

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

# 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

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

# 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

# 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 - Guides, API reference, and examples
• 🚀 Quickstart Guide - Get up and running fast
• 💡 Examples - See how others use Intent Kit
• 🐛 GitHub Issues - Report bugs or ask questions

---

Development & Contribution

Pre-commit Hooks & Version Management

This project uses pre-commit hooks to ensure code quality and version consistency:

• Version Sync: The version in pyproject.toml is automatically synced to intent_kit/__init__.py on commit.
• Changelog Check: Commits are blocked if the current version is not present in CHANGELOG.md.

To set up pre-commit hooks:

uv pip install pre-commit
uv run pre-commit install

Build, Test, and Lint

All development tasks use uv for fast, reproducible Python workflows.

• Install dependencies:

  uv sync --group dev
  

• Run tests:

  uv run pytest
  

• Lint:

  uv run lint
  uv run black --check .
  uv run typecheck
  

• Build package:

  uv build
  

GitHub Actions CI/CD

• CI: Lint, typecheck, test, and evaluate using uv in GitHub Actions.
• Deploy: On new tags, the package is built and published to PyPI, and documentation is deployed to Cloudflare Pages. (Publishing is handled by maintainers via CI/CD.)

Utility Scripts

See scripts/README.md for documentation on developer scripts, including automated changelog generation with intent-kit and LLMs.

---

Contributing

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

git clone [e-mail]:Stephen-Collins-tech/intent-kit.git
cd intent-kit
uv sync --group dev
uv run pytest

See our Contributing Guide for more details.

---

License

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