# `PtcRunner.Context`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/context.ex#L1)

Manages context, memory, and tools for program execution.

- `ctx`: External input data (read-only)
- `memory`: Mutable state passed through evaluation
- `tools`: Tool registry

See `PtcRunner.SubAgent` for usage in agentic loops.

# `t`

```elixir
@type t() :: %PtcRunner.Context{
  ctx: map(),
  journal: map() | nil,
  memory: map(),
  tools: map(),
  turn_history: list()
}
```

Context structure containing external data, memory, and tool registry.

- `journal`: Optional journal map for `(task)` idempotent execution.
  When non-nil, task results are cached by ID. When nil, tasks execute
  without caching (with a trace warning).

# `get_ctx`

```elixir
@spec get_ctx(t(), String.t()) :: {:ok, any()} | {:error, {atom(), String.t()}}
```

Retrieves a value from context (external data).

Returns `{:ok, nil}` if key doesn't exist.

## Examples

    iex> ctx = PtcRunner.Context.new(%{"users" => [1, 2, 3]})
    iex> PtcRunner.Context.get_ctx(ctx, "users")
    {:ok, [1, 2, 3]}

    iex> ctx = PtcRunner.Context.new()
    iex> PtcRunner.Context.get_ctx(ctx, "missing")
    {:ok, nil}

# `get_memory`

```elixir
@spec get_memory(t(), String.t()) :: {:ok, any()} | {:error, {atom(), String.t()}}
```

Retrieves a value from memory (mutable state).

Returns `{:ok, nil}` if key doesn't exist.

## Examples

    iex> ctx = PtcRunner.Context.new(%{}, %{"counter" => 42})
    iex> PtcRunner.Context.get_memory(ctx, "counter")
    {:ok, 42}

    iex> ctx = PtcRunner.Context.new()
    iex> PtcRunner.Context.get_memory(ctx, "missing")
    {:ok, nil}

# `new`

```elixir
@spec new(map(), map(), map(), list(), map() | nil) :: t()
```

Creates a new context with external data, memory, tools, and optional turn history.

## Examples

    iex> ctx = PtcRunner.Context.new(%{"users" => [1, 2, 3]})
    iex> ctx.ctx
    %{"users" => [1, 2, 3]}

    iex> ctx = PtcRunner.Context.new(%{}, %{"counter" => 0})
    iex> ctx.memory
    %{"counter" => 0}

# `put_memory`

```elixir
@spec put_memory(t(), String.t(), any()) :: t()
```

Sets a value in memory.

## Examples

    iex> ctx = PtcRunner.Context.new()
    iex> ctx = PtcRunner.Context.put_memory(ctx, "result", 100)
    iex> ctx.memory
    %{"result" => 100}

---

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