Scoria is the public facade for starting, inspecting, and resuming AI work inside a Phoenix app.

Start here when wiring Scoria into an application. The normal path is:

1. Normalize request or session context with identity/1
2. Start a durable run with start_run/2
3. Persist the returned run_id
4. Inspect or resume that exact run through the same module

session_id is the host-owned continuity key that groups related turns. run_id is Scoria's exact durable handle for one run. Reuse a session_id across turns, but resume only by run_id.

Use this facade from controllers, LiveViews, jobs, or service modules when the host app already owns identity, authorization, policy values, prompts, and business meaning. Scoria records the durable execution trace and returns public Scoria.Runtime.RunSummary / Scoria.Runtime.RunDetail data.

For the first-run walkthrough, see guides/getting-started.md and guides/golden-path.md. For the ownership split, see Scoria.Identity and guides/ownership-boundary.md. For lower-level lifecycle APIs behind this facade, see Scoria.Runtime.

Examples

iex> identity =
...>   Scoria.identity(%{
...>     actor_id: "user_123",
...>     tenant_id: "tenant_456",
...>     session_id: "session_789"
...>   })
iex> {identity.actor_id, identity.tenant_id, identity.session_id}
{"user_123", "tenant_456", "session_789"}
iex> identity.metadata
%{}