sigil-agent

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

Installation

pip install sigil-agent

Quick Start

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

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

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:

# 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

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

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

Client Options

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

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

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

# Run tests
pytest

# Type checking
mypy sigil

# Linting
ruff check sigil tests

License

MIT