Metadata-Version: 2.4
Name: skillvault
Version: 0.1.2
Summary: Agent Skill Management System with self-growth capabilities
Project-URL: Homepage, https://github.com/yourusername/skillvault
Project-URL: Documentation, https://github.com/yourusername/skillvault#readme
Project-URL: Repository, https://github.com/yourusername/skillvault.git
Project-URL: Issues, https://github.com/yourusername/skillvault/issues
License: MIT
License-File: LICENSE
Keywords: agent,ai,knowledge-management,llm,skill,sqlite,vector-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: sqlite-vec>=0.1.0
Provides-Extra: cli
Requires-Dist: click>=8.0.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: local-embed
Requires-Dist: sentence-transformers>=2.0.0; extra == 'local-embed'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Requires-Dist: tiktoken>=0.5.0; extra == 'openai'
Description-Content-Type: text/markdown

# Skill Manager

[![PyPI](https://img.shields.io/pypi/v/skillvault)](https://pypi.org/project/skillvault/)

Agent Skill Management System with self-growth capabilities.

Published on PyPI: **https://pypi.org/project/skillvault/**

## Features

- **Skill Storage**: SQLite + sqlite-vec for local storage with vector search
- **Semantic Query**: ANN retrieval + dependency expansion + token budget cropping
- **Self-Growth**: Automatically extract knowledge from conversations and tasks
- **Human-in-the-Loop**: Review queue for approving/rejecting draft skills
- **Permission Separation**: Agent code can only write drafts, humans control canonical
- **CLI Tool**: Command-line interface for skill management (optional)

## Installation

```bash
# Core (SQLite storage + vector search)
pip install skillvault

# With OpenAI embedding support
pip install skillvault[openai]

# With CLI tool
pip install skillvault[cli]

# Everything
pip install skillvault[openai,cli]
```

## Quick Start

```python
import json
from openai import OpenAI
from skillvault import SkillManager
from skillvault.models import Skill, Chunk

client = OpenAI()

# embed_fn: text -> list[float] (1536 dimensions for text-embedding-3-small)
def embed(text: str) -> list[float]:
    resp = client.embeddings.create(model="text-embedding-3-small", input=[text])
    return resp.data[0].embedding

sm = SkillManager("skills.db", embed_fn=embed)

# Register a skill
skill = Skill(
    id="frontend-react",
    name="Frontend React",
    chunks=[
        Chunk(
            id="frontend-react::hooks",
            skill_id="frontend-react",
            section="React Hooks",
            content="## useEffect\n\nUse useEffect for side effects...",
            tokens=50,
        )
    ]
)
sm.register(skill)

# Query skills
context = sm.query("React hooks best practices", budget=2000)
print(context)
```

## Self-Growth (Extract knowledge from conversations)

```python
import json
from openai import OpenAI
from skillvault import SkillManager

client = OpenAI()

def embed(text: str) -> list[float]:
    resp = client.embeddings.create(model="text-embedding-3-small", input=[text])
    return resp.data[0].embedding

# llm_fn: text -> dict (analyze context for reusable knowledge)
def extract_knowledge(text: str) -> dict:
    resp = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": f"""Analyze this conversation and extract reusable knowledge.

{text}

Return JSON:
{{
    "has_knowledge": true/false,
    "title": "short title",
    "playbook": "step-by-step instructions in markdown",
    "examples": "code examples in markdown",
    "when_to_use": "specific scenarios",
    "dependencies": ["related-skill-id"]
}}"""}],
        response_format={"type": "json_object"},
    )
    return json.loads(resp.choices[0].message.content)

sm = SkillManager("skills.db", embed_fn=embed, llm_fn=extract_knowledge)

# Extract from conversation (returns draft_id or None)
draft_id = sm.extract([
    {"role": "user", "content": "How do I handle errors in async Python?"},
    {"role": "assistant", "content": "Use try/except with asyncio.gather..."},
])

# Review and approve
if draft_id:
    pending = sm.review_queue()
    sm.approve(draft_id)
```

## Agent Mode (Restricted permissions)

```python
from skillvault import SkillManager

# Same embed_fn as above
sm = SkillManager("skills.db", embed_fn=embed, mode="agent")

sm.query("...")           # OK - reads canonical skills only
sm.extract(messages)      # OK - creates drafts
sm.register(skill)        # raises PermissionError
sm.approve(draft_id)      # raises PermissionError
```

## CLI Usage

Requires `pip install skillvault[cli]`.

```bash
# List skills
python -m skillvault.cli list

# Review queue
python -m skillvault.cli review-queue

# Approve/reject
python -m skillvault.cli approve draft::skill-id
python -m skillvault.cli reject draft::skill-id --reason "Not useful"

# Export/Import
python -m skillvault.cli export frontend-react react.json
python -m skillvault.cli import react.json

# Statistics
python -m skillvault.cli stats
```

## Architecture

```
SkillManager (one class)
    │
    ├── query(text, budget)        → Search + assemble context
    ├── register(skill)            → Save canonical skill
    ├── extract(context)           → LLM extraction → draft
    ├── approve/reject(skill_id)   → Review workflow
    └── export/import              → JSON serialization
    │
    ├── storage.py    (SQLite + sqlite-vec)
    ├── query.py      (embed + ANN + budget)
    └── growth.py     (LLM analysis + auto-promote)
```

## Development

```bash
# Install in dev mode
pip install -e ".[dev,openai,cli]"

# Run tests
pytest

# Format & lint
black src/ tests/
ruff check src/ tests/
```

## License

MIT
