# `Logistiki.Knowledge.KnowledgeBase`
[🔗](https://github.com/thanos/logistiki/blob/v0.1.0/lib/logistiki/knowledge/knowledge_base.ex#L1)

Loads and evaluates the accounting knowledge program for a single event.

Given a normalized event, this module:

  1. generates runtime facts (`Logistiki.Knowledge.Facts`)
  2. builds a program from `Logistiki.Knowledge.Program` (with static facts)
  3. adds the runtime facts
  4. materializes the Datalog knowledge
  5. interprets the result into a `Logistiki.Knowledge.Result`

Datalog decides facts and relationships; Elixir interprets them.

# `derived_account_roles`
*since 0.1.0* 

```elixir
@spec derived_account_roles(ExDatalog.Knowledge.t()) :: %{
  required(atom()) => String.t()
}
```

Lists all derived account roles for an event.

## Arguments

  * `knowledge` — `%ExDatalog.Knowledge{}`.

## Returns

  * `%{atom() => String.t()}` — role-to-code map.

## Examples

    iex> Logistiki.Knowledge.KnowledgeBase.derived_account_roles(knowledge)
    %{cash_account: "ASSETS:CASH:USD:NOSTRO"}

# `derived_policies`
*since 0.1.0* 

```elixir
@spec derived_policies(ExDatalog.Knowledge.t()) :: [atom()]
```

Lists all derived policy facts for an event (useful for tests).

## Arguments

  * `knowledge` — `%ExDatalog.Knowledge{}`.

## Returns

  * `[atom()]` — the derived policy atoms.

## Examples

    iex> Logistiki.Knowledge.KnowledgeBase.derived_policies(knowledge)
    [:cash_deposit]

# `evaluate`
*since 0.1.0* 

```elixir
@spec evaluate(
  Logistiki.Event.Normalized.t(),
  keyword()
) :: {:ok, Logistiki.Knowledge.Result.t()} | {:error, term()}
```

Evaluates the knowledge layer for `normalized_event` and interprets the result.

## Arguments

  * `normalized_event` — `%Logistiki.Event.Normalized{}`.
  * `opts` — `keyword()` — passed to `ExDatalog.materialize/2`.

## Returns

  * `{:ok, %Logistiki.Knowledge.Result{}}` — the interpreted result with
    `policy`, `template_postings`, `account_roles`, `blocked`, etc.
  * `{:error, term()}` — materialization failed.

## Examples

    iex> {:ok, result} = Logistiki.Knowledge.KnowledgeBase.evaluate(normalized_event)
    iex> result.policy
    :cash_deposit

# `interpret`
*since 0.1.0* 

```elixir
@spec interpret(ExDatalog.Knowledge.t(), Logistiki.Event.Normalized.t()) ::
  Logistiki.Knowledge.Result.t()
```

Interprets materialized knowledge into a `Logistiki.Knowledge.Result`.

Extracts derived policies, account roles, template postings, and required
dimensions, selects the policy (unique, first-sorted on ambiguity, or nil),
and builds the `Result`.

## Arguments

  * `knowledge` — `%ExDatalog.Knowledge{}` — materialized knowledge.
  * `normalized_event` — `%Logistiki.Event.Normalized{}` — for the event id.

## Returns

  * `%Logistiki.Knowledge.Result{}` — the interpreted result.

## Examples

    iex> {:ok, knowledge} = Logistiki.Knowledge.KnowledgeBase.materialize_for(normalized_event)
    iex> result = Logistiki.Knowledge.KnowledgeBase.interpret(knowledge, normalized_event)
    iex> result.policy
    :cash_deposit

# `materialize_for`
*since 0.1.0* 

```elixir
@spec materialize_for(
  Logistiki.Event.Normalized.t(),
  keyword()
) :: {:ok, ExDatalog.Knowledge.t()} | {:error, term()}
```

Materializes the knowledge program with the runtime facts for `event`.

## Arguments

  * `normalized_event` — `%Logistiki.Event.Normalized{}`.
  * `opts` — `keyword()` — passed to `ExDatalog.materialize/2`.

## Returns

  * `{:ok, %ExDatalog.Knowledge{}}` — materialized knowledge with all derived
    facts.
  * `{:error, term()}` — materialization failed.

## Examples

    iex> {:ok, knowledge} = Logistiki.Knowledge.KnowledgeBase.materialize_for(normalized_event)
    iex> ExDatalog.Knowledge.get(knowledge, "policy")
    MapSet.new({:evt, :cash_deposit})

# `raw_knowledge`
*since 0.1.0* 

```elixir
@spec raw_knowledge(
  Logistiki.Event.Normalized.t(),
  keyword()
) :: {:ok, ExDatalog.Knowledge.t()} | {:error, term()}
```

Returns the raw `ExDatalog.Knowledge` for inspection/debugging.

## Arguments

  * `normalized_event` — `%Logistiki.Event.Normalized{}`.
  * `opts` — `keyword()` — passed to `ExDatalog.materialize/2`.

## Returns

  * `{:ok, %ExDatalog.Knowledge{}}` | `{:error, term()}`

## Examples

    iex> {:ok, knowledge} = Logistiki.Knowledge.KnowledgeBase.raw_knowledge(normalized_event)

---

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