# Context Providers

Context providers inject dynamic runtime data as system messages into the LLM context on every call. Unlike tools (which the model calls on demand), providers run automatically before every LLM request.

## Use cases

- Server's own public URL (built-in: `public_url`)
- Current hostname or environment name
- Active feature flags
- Short status summaries that should always be visible

---

## How it works

On every LLM call, `Agent._collect_context_injections(profile)` runs all active providers and returns their output as `role="system"` messages. These are inserted right after the memory summary, before conversation history.

**Which providers run for a given call:**
1. All providers where `global_provider = True` (always, regardless of profile)
2. Providers listed in the profile's `context_providers` config field

---

## Built-in providers

| Name | global | Description |
|---|---|---|
| `public_url` | yes | Injects `PUBLIC_URL` from settings so Navi always knows her own address |

---

## User providers

Drop a `.py` file in `context_providers/` at project root. Call `reload_tools` to activate.

### Module format

```python
name = "my_provider"
description = "What this injects."
global_provider = False  # True = all profiles, False = opt-in per profile

async def get_context() -> str | None:
    return "[System] ..."  # or None to skip
```

### Template

See `context_providers/_template.py` for a copy-paste starting point.

---

## Profile configuration

Add provider names to `context_providers` in `config.json` to opt in to non-global providers:

```json
{
  "context_providers": ["hostname", "active_project"]
}
```

Default is an empty list — only global providers run.

---

## Reload

`reload_tools` reloads both user tools and user context providers in one call. Built-in providers (in `navi/context_providers/`) are loaded at startup only.

---

## Writing providers (Navi)

Use `tool_manual("write_context_provider")` for the full format reference and examples before writing a provider file.

---

## File locations

| Path | Purpose |
|---|---|
| `navi/context_providers/` | Built-in providers (server code) |
| `context_providers/` | User-written providers (hot-reloadable) |
| `context_providers/_template.py` | Format reference (not loaded) |
| `manuals/write_context_provider.md` | Navi's how-to guide |