# Python Package

The Python package `talocode-skilllane` provides an HTTP client and CLI for interacting with a running SkillLane API server.

---

## Installation

```bash
pip install talocode-skilllane
```

**Requirements:** Python >= 3.10

---

## Client

```python
from talocode_skilllane import SkillLaneClient

client = SkillLaneClient(
    base_url="http://localhost:3080",
    auth_token=None  # optional
)
```

### Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SKILLLANE_URL` | `http://localhost:3080` | API server URL |
| `SKILLLANE_TOKEN` | (none) | Auth token |

---

## Methods

### health()

Check API health status.

```python
print(client.health())
# {"status": "ok", "version": "0.1.0"}
```

### doctor()

Run diagnostic checks.

```python
print(client.doctor())
# {"healthy": True, "checks": [...]}
```

### init()

Initialize SkillLane environment.

```python
print(client.init())
# {"initialized": True}
```

### list_skills(tag=None, category=None)

List available skills.

```python
skills = client.list_skills()
skills = client.list_skills(category="engineering")
skills = client.list_skills(tag="debugging")
```

### search_skills(query)

Search skills by query string.

```python
results = client.search_skills("debug")
```

### validate_skill(path, strict=False)

Validate a skill at the given filesystem path.

```python
result = client.validate_skill("./my-skill")
result = client.validate_skill("./my-skill", strict=True)
print(result["valid"])  # True
print(result["score"])  # 85
```

### run_skill(name, task, context=None, target=None)

Run a skill by name.

```python
result = client.run_skill(
    name="systematic-debugging",
    task="Debug a TypeError",
    context={"error": "Cannot read property of undefined at line 42"},
    target="opencode",
)
print(result["prompt"])
```

### demo()

Run the SkillLane demo.

```python
print(client.demo())
```

---

## Data Models

```python
from talocode_skilllane import (
    SkillMetadata,
    SkillDefinition,
    SkillValidationResult,
    SkillRunResult,
    RegistryEntry,
)
```

### SkillMetadata

```python
@dataclass
class SkillMetadata:
    name: str
    version: str = "0.1.0"
    description: str = ""
    author: str = ""
    tags: list[str] = field(default_factory=list)
    category: str = ""
    license: str = ""
    homepage: str = ""
```

### SkillDefinition

```python
@dataclass
class SkillDefinition:
    metadata: SkillMetadata
    entry_point: str = ""
    instructions: str = ""
    config: dict[str, Any] = field(default_factory=dict)
    dependencies: list[str] = field(default_factory=list)
    files: list[str] = field(default_factory=list)
```

### SkillValidationResult

```python
@dataclass
class SkillValidationResult:
    valid: bool = True
    errors: list[str] = field(default_factory=list)
    warnings: list[str] = field(default_factory=list)
    path: str = ""
```

### SkillRunResult

```python
@dataclass
class SkillRunResult:
    success: bool = True
    output: str = ""
    error: str = ""
    duration_ms: float = 0.0
    metadata: dict[str, Any] = field(default_factory=dict)
```

### RegistryEntry

```python
@dataclass
class RegistryEntry:
    name: str
    version: str = ""
    description: str = ""
    installed: bool = False
    path: str = ""
    tags: list[str] = field(default_factory=list)
    category: str = ""
```

---

## Error Handling

```python
from talocode_skilllane.client import SkillLaneError

try:
    result = client.run_skill("nonexistent", "test")
except SkillLaneError as e:
    print(f"Error: {e}")
    print(f"HTTP status: {e.status_code}")
```

---

## CLI

The `skilllane-py` command-line interface connects to a running API server.

```bash
skilllane-py --help
skilllane-py health
skilllane-py doctor
skilllane-py init
skilllane-py list
skilllane-py list --category engineering
skilllane-py search debug
skilllane-py validate ./my-skill
skilllane-py validate ./my-skill --strict
skilllane-py run systematic-debugging --task "Fix the bug"
skilllane-py demo
```

### CLI options

| Option | Description |
|--------|-------------|
| `--tag TAG` | Filter by tag |
| `--category CAT` | Filter by category |
| `--strict` | Strict validation |
| `--task TASK` | Task for run command |
| `--context-file PATH` | JSON context file |
| `--target TARGET` | Agent target |
| `--version` | Show version |
| `--help` | Show help |