starflask 0.1.7

# starflask

Rust SDK for the [Starflask](https://starflask.com) AI agent platform.

## Installation

```toml
[dependencies]
starflask = "0.1"
```

## Quick start

```rust,no_run
use starflask::Starflask;

#[tokio::main]
async fn main() -> Result<(), starflask::Error> {
    let sf = Starflask::new("sk_...", None)?;

    // List your agents
    let agents = sf.list_agents().await?;

    // Send a message and wait for the response
    let session = sf.query(&agents[0].id, "Hello!").await?;
    println!("{:?}", session.result);

    Ok(())
}
```

## Query

Send a chat message to an agent and wait for the response. The SDK handles session creation and polling automatically.

```rust,no_run
// Simple query — uses the agent's soul prompt
let session = sf.query(&agent_id, "What can you do?").await?;
println!("{:?}", session.result);

// Query with a specific persona
let session = sf.query_with_persona(
    &agent_id,
    "Design a retro game UI palette",
    Some("palette_generator_reactive"),
).await?;
```

When you specify a `persona`, the agent's soul prompt is still used as the base system context, but the named persona's prompt is appended — giving the agent a specific behavioral mode for that query.

## Hooks

For structured workflows where an agent pack defines event-specific persona templates with variable substitution, use hooks:

```rust,no_run
// Fire and wait
let session = sf.fire_hook_and_wait(
    &agent_id,
    "generate_palette",
    serde_json::json!({ "premise": "sunset over the ocean" }),
).await?;

// Fire without waiting
let session = sf.fire_hook(&agent_id, "heartbeat", serde_json::json!({})).await?;
```

## Packs

Packs define an agent's soul, personas, and hooks. Use `provision_pack` to create and install a pack in one step.

```rust,no_run
let result = sf.provision_pack(&agent_id, serde_json::json!({
    "soul": {
        "name": "my_agent",
        "description": "A helpful assistant",
        "content": "You are a helpful assistant.",
        "tags": ["assistant"],
    },
    "personas": [
        {
            "name": "default",
            "description": "Default persona",
            "content": "Respond concisely and helpfully.",
        }
    ],
    "pack": {
        "name": "my_pack",
        "description": "My agent pack",
        "hooks": {
            "greet": {
                "persona": "default",
                "template": "Say hello to {{name}}.",
            }
        }
    }
})).await?;
println!("Provisioned with hash: {}", result.content_hash);
```

Provisioning is idempotent — calling it again with the same content is a no-op (matched by `content_hash`). Calling it with updated content replaces the agent's existing pack.

If you already have a `content_hash` from a previous provision, you can install it directly:

```rust,no_run
sf.install_agent_pack(&agent_id, &content_hash).await?;
```

## Features

- **Agents** — create, list, update, activate/deactivate, and delete agents
- **Query** — send messages to agents with automatic session polling, optional persona selection
- **Hooks** — fire hook events with payload variable substitution
- **Sessions** — list and inspect session history
- **Packs** — install and provision agent packs
- **Integrations** — manage platform integrations (Discord, etc.)
- **Tasks** — create and list scheduled agent tasks
- **Memories** — list agent memories

## Custom base URL

```rust,no_run
let sf = Starflask::new("sk_...", Some("https://starflask.xyz/api"))?;
```

## License

MIT