# sigil-agent

Python SDK for the Sigil persona registry. Pull personas and inject them into LLM system prompts.

## Installation

```bash
pip install sigil-agent
```

## Quick Start

```python
from sigil import SigilClient

# Initialize client
client = SigilClient(api_key="sk_...", base_url="https://api.sigil.l8ntlabs.com")

# Fetch a persona
persona = client.get("staccato")

# Inject into system prompt
system_prompt = persona.inject()

# Or combine with a base prompt
system_prompt = persona.inject(base="You are a helpful assistant.")
```

## Usage

### Fetching Personas

```python
from sigil import SigilClient

client = SigilClient(api_key="sk_...")

# Get latest version
persona = client.get("staccato")

# Pin a specific version
persona = client.get("staccato", version="1.0.0")
```

### Accessing Persona Fields

```python
persona = client.get("staccato")

# Core fields
print(persona.name)      # "staccato"
print(persona.version)   # "1.0.0"
print(persona.soul)      # The full soul/system text

# Voice configuration
print(persona.voice.tone)      # ["direct", "clear"]
print(persona.voice.dos)       # ["Be brief", ...]
print(persona.voice.donts)     # ["Ramble", ...]

# Values (sorted by priority)
for value in persona.values:
    print(f"{value.name}: {value.description} (priority: {value.priority})")

# Behavioral map
for key, behavior in persona.behavioral_map.items():
    print(f"{key}: {behavior.posture}")
```

### Injecting into Prompts

The `inject()` method composes a well-formatted system prompt:

```python
# Basic injection
system_prompt = persona.inject()

# With a base prompt prepended
system_prompt = persona.inject(base="You are an AI assistant for Acme Corp.")
```

The inject method combines:
1. Base prompt (if provided)
2. Soul text
3. Voice rules (tone, dos, donts, example phrases)
4. Values (sorted by priority)
5. Behavioral guidelines

## Configuration

### Environment Variables

```bash
export SIGIL_API_KEY="sk_..."
export SIGIL_BASE_URL="https://api.sigil.l8ntlabs.com"
```

```python
# Client will use env vars if not provided
client = SigilClient()
```

### Client Options

```python
client = SigilClient(
    api_key="sk_...",           # Required (or SIGIL_API_KEY env var)
    base_url="http://...",       # Default: http://localhost:8100
    timeout=10,                  # Request timeout in seconds
)
```

## Error Handling

```python
from sigil import SigilClient, SigilError, SigilNotFoundError, SigilAuthError

client = SigilClient(api_key="sk_...")

try:
    persona = client.get("nonexistent")
except SigilNotFoundError:
    print("Persona not found")
except SigilAuthError:
    print("Invalid API key")
except SigilError as e:
    print(f"API error: {e.message} (status: {e.status_code})")
```

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy sigil

# Linting
ruff check sigil tests
```

## License

MIT
