Metadata-Version: 2.4
Name: ai-skill-governance
Version: 0.3.0
Summary: Govern AI skill growth through intelligent merging of similar capabilities — no blocking, only consolidation. Built for LangChain, CrewAI, and custom agent systems.
Author: brody4321
License-Expression: MIT
Project-URL: Homepage, https://github.com/cleonard2341/ai-skill-governance
Project-URL: Repository, https://github.com/cleonard2341/ai-skill-governance
Project-URL: Issues, https://github.com/cleonard2341/ai-skill-governance/issues
Keywords: ai,skills,governance,merging,agent,llm,capability-management
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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 :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: fuzzy
Requires-Dist: rapidfuzz>=3.0.0; extra == "fuzzy"
Provides-Extra: cli
Requires-Dist: click>=8.0; extra == "cli"
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.2.0; extra == "semantic"
Requires-Dist: torch>=2.0.0; extra == "semantic"
Dynamic: license-file

# AI Skill Governance

**Govern AI skill growth through intelligent merging — not blocking.**

Prevent skill bloat in AI agents by automatically detecting and merging similar capabilities while preserving functionality.

[![PyPI](https://img.shields.io/pypi/v/ai-skill-governance)](https://pypi.org/project/ai-skill-governance/)
[![Python Versions](https://img.shields.io/pypi/pyversions/ai-skill-governance)](https://pypi.org/project/ai-skill-governance/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Support

If this project is useful to you, consider supporting development:

[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/brody4321)
[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?logo=buymeacoffee)](https://buymeacoffee.com/brody4321)

## Why AI Skill Governance?

Modern AI agents can accumulate dozens or hundreds of skills. This leads to:
- Context dilution
- Slower reasoning
- Conflicting behaviors
- Maintenance nightmare

**AI Skill Governance** solves this by **intelligently merging** similar skills instead of arbitrarily limiting them.

## Before / After

A support agent accumulates **12 skills** over a few iterations. Many overlap.

| Cluster   | Before                                              | After       |
|-----------|-----------------------------------------------------|-------------|
| Greetings | `greet`, `welcome`, `say_hi`, `hello_user`          | `greet`     |
| Refunds   | `refund`, `return_payment`, `issue_refund`          | `refund`    |
| Lookups   | `find_order`, `search_orders`, `get_order_by_id`    | `find_order`|
| One-offs  | `escalate`, `close_ticket`                          | `escalate`, `close_ticket` |
| **Total** | **12 skills · ~840 tool-list tokens**\*             | **5 skills · ~350 tokens** |

→ **58% fewer skills. ~58% smaller tool-list prompt.** Same coverage, faster tool selection, fewer conflicting behaviors.

<sub>\*Illustrative. Tool-list tokens depend on serialization format (OpenAI function-calling schema, Anthropic tool blocks, etc.). The skill-count reduction is deterministic; token savings scale roughly with it.</sub>

## Installation

```bash
pip install ai-skill-governance
```

For faster fuzzy matching:
```bash
pip install "ai-skill-governance[fuzzy]"
```

## Quick Start

```python
from ai_skill_governance import SkillRegistry

registry = SkillRegistry(default_threshold=0.75)

@registry.register(description="Sends a warm greeting")
def greet(name: str):
    return f"Hello, {name}!"

@registry.register(description="Welcomes the user warmly")
def welcome(name: str):
    return f"Welcome, {name}!"

# Check for suggested merges
print(registry.suggest_merges())

# Perform merge (v0.1.1: includes signature compatibility check)
merged = registry.perform_merge("greet", "welcome")
print(merged)

# Persistence (new in v0.1.1)
registry.save("my_skills.json")
registry.load("my_skills.json")
```

## Advanced Merging

The merger creates a **smart combined function** that:
- Preserves the primary behavior
- Augments with secondary skill when signatures match
- Intelligently combines string/dict results
- Maintains full traceability

## CLI

```bash
# Show status
skill-gov status --threshold 0.8

# Analyze and suggest merges
skill-gov merge --threshold 0.75

# Auto-merge similar skills
skill-gov merge --auto
```

## Configuration

- `default_threshold`: Similarity cutoff (0.0–1.0). Default: 0.75
- `merge_mode`: `"suggest"` (default) or `"auto"`

## v0.3.0 New Features

### Skill Graph Visualization
```python
from ai_skill_governance import SkillRegistry, SkillGraph

reg = SkillRegistry()
# ... register skills ...

graph = SkillGraph(reg)
print(graph.to_ascii())           # Simple text view
dot = graph.to_dot("skills.dot")  # Graphviz format
data = graph.to_json("graph.json") # For web dashboards
```

### Semantic Merging (Major Upgrade)
```bash
pip install "ai-skill-governance[semantic]"
```

```python
from ai_skill_governance import SkillRegistry

reg = SkillRegistry()
suggestions = reg.suggest_merges(method="semantic")  # Uses embeddings when available
```

### LangChain Integration
```python
from ai_skill_governance.integrations.langchain import LangChainSkillGovernor

governor = LangChainSkillGovernor()
# Use @governor.register_tool on your LangChain @tool functions
```

### CrewAI Integration
```python
from ai_skill_governance.integrations.crewai import CrewAISkillGovernor
```

## PyPI Release Notes

This package is fully prepared for PyPI publication with:
- Modern `pyproject.toml`
- Proper metadata and classifiers
- Optional dependencies (`fuzzy` for rapidfuzz)
- Comprehensive documentation
- MIT License

## Contributing

We welcome contributions that improve merging intelligence, add new similarity methods, or enhance the governance dashboard.

## License

MIT License — see [LICENSE](LICENSE) file.
