# `Obscura.Profile`
[🔗](https://github.com/hfiguera/obscura/blob/v0.2.0/lib/obscura/profile.ex#L1)

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.2.x` policy in `docs/public-api-stability.md`.

# `experimental_name`

```elixir
@type experimental_name() :: :hybrid_gliner_urchade | :openmed_pii | :spacy_cpu
```

# `name`

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

# `stability`

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

# `stable_name`

```elixir
@type stable_name() :: :fast | :efficient | :balanced | :accurate
```

# `t`

```elixir
@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()]
}
```

# `available?`

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

Returns whether a product profile is ready without running inference.

# `classification`

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

Returns the stability classification for a known profile.

# `describe`

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

Returns report-safe profile metadata.

# `experimental_names`

```elixir
@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`

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

Returns a stable or explicitly experimental product profile descriptor.

# `implementation_profiles`

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

Lists all implementation profiles accepted for backward compatibility.

# `names`

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

Lists stable user-facing profile names.

# `normalize`

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

Returns the requested profile and resolved implementation profile.

# `preflight`

```elixir
@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`

```elixir
@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`

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

Returns the runtime requirements for a product profile.

# `resolve`

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

Resolves a product alias or known implementation profile.

# `validate_runtime`

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

Validates dependencies and reusable runtime assets without running inference.

---

*Consult [api-reference.md](api-reference.md) for complete listing*