Ingot.ForgeClient behaviour (Ingot v0.1.0)
View SourceBehaviour for fetching samples and artifacts from Forge.
Ingot uses read-only operations; no sample creation/mutation. Supports pluggable adapters for different deployment scenarios:
- MockAdapter: For testing without running Forge
- ElixirAdapter: Direct in-process calls when deployed together
- HTTPAdapter: REST API calls for separate deployments (future)
Summary
Callbacks
Fetch next sample from queue for the given user.
Fetch all artifacts for a sample.
Fetch a sample by ID.
Health check for Forge service.
Get queue statistics.
Mark sample as skipped by the user.
Functions
Fetch next sample from queue for the given user.
Generate new batch of samples.
Fetch all artifacts for a sample.
Fetch a sample by ID.
Health check for Forge service.
Get queue statistics.
Mark sample as skipped by the user.
Types
Callbacks
@callback fetch_next_sample(user_id :: String.t()) :: {:ok, map()} | {:error, :queue_empty | error()}
Fetch next sample from queue for the given user.
Legacy API - maintained for backward compatibility.
@callback get_artifacts(sample_id()) :: {:ok, [Ingot.DTO.Artifact.t()]} | {:error, error()}
Fetch all artifacts for a sample.
Artifacts are media files (images, audio, etc.) with signed URLs.
@callback get_sample(sample_id()) :: {:ok, Ingot.DTO.Sample.t()} | {:error, error()}
Fetch a sample by ID.
Returns the sample DTO with embedded artifacts and metadata.
@callback health_check() :: {:ok, :healthy} | {:error, error()}
Health check for Forge service.
Returns :ok if Forge is reachable and healthy, otherwise returns an error.
Get queue statistics.
Returns aggregate statistics about sample queues.
Mark sample as skipped by the user.
Legacy API - maintained for backward compatibility.
Functions
Fetch next sample from queue for the given user.
Examples
iex> ForgeClient.fetch_next_sample("user-123")
{:ok, %{id: "sample-1", narrative_a: "...", ...}}Generate new batch of samples.
Legacy API - maintained for backward compatibility.
Fetch all artifacts for a sample.
Examples
iex> ForgeClient.get_artifacts("sample-123")
{:ok, [%Ingot.DTO.Artifact{...}]}Fetch a sample by ID.
Examples
iex> ForgeClient.get_sample("sample-123")
{:ok, %Ingot.DTO.Sample{id: "sample-123", ...}}
iex> ForgeClient.get_sample("nonexistent")
{:error, :not_found}Health check for Forge service.
Examples
iex> ForgeClient.health_check()
{:ok, :healthy}
iex> ForgeClient.health_check()
{:error, :not_available}Get queue statistics.
Examples
iex> ForgeClient.queue_stats()
{:ok, %{total: 100, completed: 50, remaining: 50}}Mark sample as skipped by the user.
Examples
iex> ForgeClient.skip_sample("sample-1", "user-123")
:ok