Obscura.Profile (obscura v0.1.0)

Copy Markdown View Source

Product profiles and runtime requirement checks.

Stable profiles are user-facing aliases over benchmarked implementation profiles. Experimental aliases and existing implementation profiles remain available for explicit evaluation use. Only stable aliases and public return shapes follow the 0.1.x policy in docs/public-api-stability.md.

Summary

Types

experimental_name()
name()
stability()
stable_name()
t()

Functions

available?(profile, opts \\ [])

Returns whether a product profile is ready without running inference.

classification(profile)

Returns the stability classification for a known profile.

describe(profile)

Returns report-safe profile metadata.

experimental_names()

Lists opt-in product aliases outside the compatibility promise.

fetch(profile)

Returns a stable or explicitly experimental product profile descriptor.

implementation_profiles()

Lists all implementation profiles accepted for backward compatibility.

names()

Lists stable user-facing profile names.

normalize(profile)

Returns the requested profile and resolved implementation profile.

preflight(profile, opts \\ [])

Returns a report-safe readiness result without analyzing PII.

prepare(profile, opts \\ [])

Explicitly prepares reusable resources for a product profile.

requirements(profile)

Returns the runtime requirements for a product profile.

resolve(profile)

Resolves a product alias or known implementation profile.

validate_runtime(profile, opts \\ [])

Validates dependencies and reusable runtime assets without running inference.

Types

experimental_name()

@type experimental_name() :: :hybrid_gliner_urchade | :openmed_pii

name()

@type name() :: stable_name() | experimental_name()

stability()

@type stability() :: :stable | :advanced | :experimental | :historical | :deprecated

stable_name()

@type stable_name() :: :fast | :balanced | :accurate

t()

@type t() :: %Obscura.Profile{
  automatic_download: boolean(),
  backend_policy: atom(),
  benchmark_ids: [String.t()],
  category: atom(),
  default_models: [atom()],
  implementation_profile: atom(),
  name: name(),
  optional_dependencies: [atom()],
  recognizer_mode: atom(),
  required_assets: [atom()],
  required_dependencies: [atom()],
  stability: stability(),
  supported_entities: [atom()]
}

Functions

available?(profile, opts \\ [])

@spec available?(
  name() | String.t(),
  keyword()
) :: boolean()

Returns whether a product profile is ready without running inference.

classification(profile)

@spec classification(atom() | String.t()) ::
  {:ok, stability()} | {:error, Obscura.Diagnostic.t()}

Returns the stability classification for a known profile.

describe(profile)

@spec describe(name() | String.t()) :: {:ok, map()} | {:error, Obscura.Diagnostic.t()}

Returns report-safe profile metadata.

experimental_names()

@spec experimental_names() :: [experimental_name()]

Lists opt-in product aliases outside the compatibility promise.

Experimental aliases remain callable for controlled evaluation, but they are not generally recommended and may change or be removed before release.

fetch(profile)

@spec fetch(name() | String.t()) :: {:ok, t()} | {:error, Obscura.Diagnostic.t()}

Returns a stable or explicitly experimental product profile descriptor.

implementation_profiles()

@spec implementation_profiles() :: [atom()]

Lists all implementation profiles accepted for backward compatibility.

names()

@spec names() :: [stable_name()]

Lists stable user-facing profile names.

normalize(profile)

@spec normalize(atom() | String.t()) ::
  {:ok, %{requested: atom(), implementation: atom()}}
  | {:error, Obscura.Diagnostic.t()}

Returns the requested profile and resolved implementation profile.

preflight(profile, opts \\ [])

@spec preflight(
  name() | String.t(),
  keyword()
) :: {:ok, map()} | {:error, Obscura.Diagnostic.t(), map()}

Returns a report-safe readiness result without analyzing PII.

Local checks are the default. prepare: true explicitly permits runtime and model preparation.

prepare(profile, opts \\ [])

@spec prepare(
  name() | String.t(),
  keyword()
) :: {:ok, Obscura.Profile.Runtime.t()} | {:error, Obscura.Diagnostic.t()}

Explicitly prepares reusable resources for a product profile.

This is the only product-profile API which may load model assets. Ordinary analysis never calls it implicitly. Remote downloads require allow_download: true; preparation is cache-only by default and offline: true always forbids network access.

Model-backed preparation runs in a monitored worker with a 30-minute overall timeout and a five-minute inactivity timeout by default. Set timeout or inactivity_timeout to a positive millisecond value or :infinity. progress: fn event -> ... end receives safe lifecycle events; callback failures are isolated from preparation. Online preparation retries one transient model or tokenizer load failure. Offline preparation never retries asset access. Authorized recovery quarantines unreferenced partial files and reports cache recovery before replacement download progress.

requirements(profile)

@spec requirements(name() | String.t()) ::
  {:ok, map()} | {:error, Obscura.Diagnostic.t()}

Returns the runtime requirements for a product profile.

resolve(profile)

@spec resolve(atom() | String.t()) :: {:ok, atom()} | {:error, Obscura.Diagnostic.t()}

Resolves a product alias or known implementation profile.

validate_runtime(profile, opts \\ [])

@spec validate_runtime(
  name() | String.t(),
  keyword()
) :: :ok | {:error, Obscura.Diagnostic.t()}

Validates dependencies and reusable runtime assets without running inference.