Glossary

Consistent terminology across docs, code, and issues. Phase 1 terms are fully defined; future-phase terms are marked so integrators know what is not live yet.

Core entities (Phase 1)

Agent

A configured AI system that makes LLM calls through the IBEX proxy, scoped to an organization. In Phase 1, agents are rows in ibex_core.agents validated on every protected proxy request via X-IBEX-Agent-ID.

Key fields: agent_id, org_id, name, status

See Org & project model and Concepts.

Organization (Org / Tenant)

The tenant boundary. All customer data is scoped to an organization. Org A must never access Org B data — enforced by RLS and application-layer filters.

Invariant: cross-tenant resource access returns 403, never 404.

User

A human operator who manages org agents and tokens via the dashboard or API. Not the same as an agent — users are operators; agents are compute identities.

Dashboard session flows are Phase 2+; Phase 1 focuses on PAT-based SDK access.

Project

A grouping within an org for agents and resources. Present in the schema and migrations; management APIs expand in later phases.

Personal Access Token (PAT)

A long-lived bearer credential for SDK and automation use. Issued via auth gRPC CreateToken, stored as an Argon2id hash, shown in plaintext exactly once.

Wire format: ibex_pat_{uuid}_{secret} per ADR-0007.

Security and isolation

RLS (Row-Level Security)

PostgreSQL policy that restricts rows to the current org context. Every tenant table includes org_id; connections set SET LOCAL app.current_org_id per transaction.

Defense in depth: application queries still filter by org_id even when RLS is enabled. See Tenant isolation.

Permission bitmap

A 64-bit field on tokens encoding allowed operations (read memory, create session, proxy chat, etc.). Canonical layout in ADR-0009.

Fail closed

When auth or tenant isolation dependencies fail, the system denies access rather than granting cached or anonymous permissions. Phase 1 proxy returns 503 SERVICE_DEGRADED when auth gRPC is unreachable.

Fail open (rate limiting)

When Redis is unavailable, the proxy rate limiter allows requests through rather than blocking all traffic — availability trade-off documented in Rate limiting.

Proxy and API

LLM Proxy

The Go HTTP edge service (default port 8080) that authenticates requests, enforces agent identity, rate limits, normalizes chat payloads, and (Phase 2+) forwards to provider adapters.

Phase 1 middleware: request ID → auth → agent verify → rate limit → normalize.

Provider adapter

A module translating normalized internal requests to provider-specific APIs (OpenAI, Anthropic, etc.). Not configured in Phase 1 — chat routes return 501 PROVIDER_NOT_CONFIGURED.

Error envelope

Stable JSON shape for proxy HTTP errors: error.code, error.message, error.request_id, optional error.docs_url. Defined in ADR-0013.

Request ID

UUID v7 correlation identifier in X-Request-ID (configurable). Assigned by proxy middleware; echoed in logs and error responses.

Observability

Trace

A record of an inference call with timing, token counts, and injected memory IDs. Trace ingestion to ClickHouse is Phase 2+; Phase 1 emits structured logs and Prometheus metrics.

Span

A sub-unit of distributed tracing (OpenTelemetry). Example spans: auth validation, rate limit check, provider call.

Health vs readiness

• Liveness (/health): process is up; no dependency probes.
• Readiness (/ready): critical dependencies (auth gRPC, Redis) are reachable.

See Health checks and ADR-0022.

Future-phase terms

These appear in architecture docs and roadmap but are not implemented in Phase 1.

Session

Unit of agent execution over time: crash recovery, trace grouping, directive versioning. State machine: initializing → active → suspended → resuming → completed/failed/abandoned.

Memory

Persistent knowledge unit with embeddings, category, confidence, and lifecycle status. Memory CRUD and injection ship in Phase 3+.

Directive

Versioned system prompt defining agent behavior. Promotion workflow and regression scenarios are future dashboard features.

Context assembly

Building the final LLM prompt from directive, history, and retrieved memories under token and latency budgets. Python context engine — Phase 3+.

Token budget

Maximum context window allocation minus response reserve. IBEX prioritizes: directive → history → memories → tools.

Related

• Concepts — org, agent, token mental model
• Architecture overview — system diagram
• Security overview — threat model and objectives