PolicyNIM

PolicyNIM is a policy-aware engineering preflight layer for AI coding agents.

It helps an agent retrieve policy evidence and review complete selected policy bodies with citations. It fails closed when complete source ownership or exact source references are unavailable.

PolicyNIM currently ships with two main user-facing surfaces:

• a JSON-first CLI for local developer workflows
• an MCP server for integrations such as Codex and Claude Code

What Works Today

• Deterministic Markdown ingest with heading-aware chunking and source line spans.
• Ingest-time compilation of runtime_rules frontmatter into the persisted runtime rules artifact.
• NVIDIA-hosted embeddings and reranking for retrieval.
• Local sqlite-vec storage for the retrievable policy index.
• Task-aware policy routing with citation-preserving selected-policy packets.
• Source-extractive policy compilation and preflight: models select compact IDs, then services quote whole pinned policy bodies with canonical citations. Output semantics and limits describe the empty advisory fields, source budgets and required applicability review.
• Opt-in preflight evidence traces that link chunks, selected policies, compiled source quotations, and conformance checks.
• Opt-in policy-backed regeneration for preflight and eval preflight cases, reusing the same compiled packet and typed conformance failures as retry triggers. Repeated attempts retain the same quoted source set; they can't rewrite policy text or establish a policy repair.
• Eval backend selection with optional policy-conformance scoring for compiled plans and preflight outputs, with compact traces embedded in eval result artifacts and local Phoenix reporting for non-headless runs.
• Runtime-rule decisions plus SQLite-backed evidence for allowed, confirmed, blocked, and failed runtime actions.
• Interactive init, quickstart, and doctor setup plus JSON-first CLI commands for ingest, dump-index, search, route, compile, preflight, eval, mcp, mcp-config, mcp-smoke, support-bundle, beta-admin, runtime, and evidence.
• MCP tools for policy_search, policy_compile, policy_preflight and policy_preflight_evidence, with versioned policy resources and a review prompt.
• Hosted HTTP streamable-http with /healthz, a self-serve /beta portal, and bearer auth on /mcp.

The MCP server supports protocol 2026-07-28 and legacy clients through the official Python SDK 2.2.0, with typed tool outputs and stateless HTTP. Set POLICYNIM_MCP_MAX_CONCURRENT_OPERATIONS to bound expensive tool calls per server (default 10). Excess calls receive a retry-later error. See the MCP workflow for transport and public-origin configuration. For evaluations that need to survive client disconnects, see durable evaluation jobs.

See grounded MCP guidance for tool schemas, evidence and immutable resource links.

The maintained source baseline includes application-security and MCP trust guidance with pinned references, role boundaries, and authored scenarios. See the coverage matrix and source licenses. Policy text has source-specific notices; software licensing remains separate. Source contents don't establish the hosted service's indexed generation.

Inspect Policies Without An API Key

These new commands are available from this source checkout or a wheel built from it. The existing v0.1.0 release predates them.

uv run policynim policies list --source
uv run policynim policies show SEC-AUTH-001 --source
uv run policynim policies validate --source --format json
uv run policynim inventory --format json

These examples inspect mutable sources with --source. Without that flag, catalog commands inspect the active generation when one exists.

The catalog commands list policy IDs, source text, pack versions, and content revisions. Inventory inspects the selected Markdown sources and local SQLite index without setup, model credentials, network calls, or data changes. Source documents, source chunks, indexed policy IDs, and indexed chunks are reported separately. Unavailable counts stay null in JSON and unknown in text. The report describes this process's files; it doesn't inspect a remote deployment or prove that source content matches an existing index.

Run uv run policynim doctor for setup checks and recovery instructions. A wheel built from this revision uses the direct policynim entrypoint. See the local profile composition guide, policy inventory and recovery guide and policy pack format.

What To Run First

If you want the shortest path to a real preflight run, start with policynim quickstart --target hosted-mcp instead of cloning the repo.

Install The CLI Without Cloning

Use the Python package path when you already have Python 3.11 or 3.12 and want pipx or uv to manage an isolated CLI environment:

pipx install --python 3.11 policynim
uv tool install --python 3.11 policynim
policynim --help
policynim init
policynim ingest

If your default Python is already supported, the shorter pipx install policynim and uv tool install policynim forms are also valid.

Use --python 3.12 instead when Python 3.12 is your managed runtime. If your machine does not expose 3.11 or 3.12 by name, pass the full path to that Python executable.

Use the GitHub release installers when you want a standalone policynim binary without managing Python dependencies yourself:

curl -fsSL https://github.com/nnennandukwe/policyNIM/releases/latest/download/install.sh | sh

irm https://github.com/nnennandukwe/policyNIM/releases/latest/download/install.ps1 | iex

Both installer paths verify release checksums before installing. After install, run policynim init, then policynim ingest, then policynim --help whenever you need to confirm the entrypoint is available.

If you want the CLI to print a no-network first-run plan for your setup, run:

policynim quickstart --target hosted-mcp
policynim quickstart --target local-cli
policynim quickstart --target local-mcp

Self-Serve Hosted Beta

1. Open https://<railway-domain>/beta.
2. Sign in with GitHub.
3. Generate or rotate your hosted API key.
4. Export the token and add the hosted MCP server to your client.

export POLICYNIM_TOKEN=<generated-beta-token>
codex mcp add policynim --url https://<railway-domain>/mcp --bearer-token-env-var POLICYNIM_TOKEN
claude mcp add --transport http policynim https://<railway-domain>/mcp --header "Authorization: Bearer $POLICYNIM_TOKEN"

Then ask your client to call the MCP tools directly:

• Use policy_preflight for: Implement a refresh-token cleanup background job.
• Use policy_search for: refresh token cleanup background job

Use docs/hosted-beta-operations.md for:

• hosted beta recovery topics
• container build and local hosted-image checks
• Railway deploy setup and smoke-test notes

Existing installations changing embedding models must follow the source-preserving provider recovery runbook. policynim ingest builds a complete immutable generation and atomically activates it. Existing standalone installations require explicit migration. See policy generations for inspection, rollback, retention, and offline deployment bundles.

Local Contributor Setup

Use this path only if you want to run PolicyNIM from a local checkout.

uv sync --group test --group dev
export NVIDIA_API_KEY=<your-nvidia-api-key>
uv run policynim ingest
uv run pytest -q

If you want the CLI to prompt for the required values and write the local config file for you, run:

uv run policynim init

In a source checkout, init writes the checkout .env file that PolicyNIM loads by default. Installed copies should keep using the direct policynim init entrypoint described below.

If you want a quick local readiness check after setup, run:

uv run policynim doctor
uv run policynim mcp-smoke --format json

If you prefer to manage .env manually, copy the template first:

cp .env.development.example .env

After the index is built, the fastest local sanity checks are:

uv run policynim search --query "refresh token cleanup background job" --top-k 5
uv run policynim route --task "Implement a refresh-token cleanup background job" --top-k 5
uv run policynim compile --task "Implement a refresh-token cleanup background job" --top-k 5
uv run policynim preflight --task "Implement a refresh-token cleanup background job" --top-k 5
uv run policynim preflight --task "Implement a refresh-token cleanup background job" --top-k 5 --trace
uv run policynim preflight --task "Implement a refresh-token cleanup background job" --top-k 5 --regenerate --backend nemo

Use docs/contributor-guide.md for environment templates, runtime settings, optional NVIDIA eval and Guardrails extras, and contributor quality gates. Optional evaluation adapters use uv sync --locked --extra nvidia-eval --group test --group dev; the internal Guardrails output-rail wrapper uses uv sync --locked --extra nvidia-guardrails. The separate upstream launcher setup is described in installation profiles.

If you are using an installed copy instead of a source checkout, run policynim init once first so PolicyNIM can write the standalone config file and data-path defaults before policynim ingest. Use uv run only when running commands from the source checkout's uv-managed project environment.

Use docs/workflows.md for the CLI, MCP, runtime, eval, and troubleshooting handbook.

Docs Map

Start here when you want the longer version of a specific path:

• docs/index.md: documentation hub by audience and task
• docs/contributor-guide.md: local setup, env vars, model references, and quality gates
• docs/workflows.md: CLI surfaces, first-run quickstart/diagnostics, ingest/search/route/compile/preflight, eval, MCP, runtime/evidence, and troubleshooting
• docs/hosted-beta-operations.md: hosted beta quickstart, recovery, container build flow, and Railway deploy notes
• docs/hosted-authorization.md: external issuer foundation, operation scopes, migration, and remaining OAuth acceptance checks
• docs/release.md: CLI packaging, GitHub release, PyPI publish, and smoke-test checklist
• docs/architecture.md: package boundaries, runtime flow, and interface rules
• docs/architecture-diagram.md: Mermaid diagram of the current package layout and runtime flow
• docs/demo-script.md: step-by-step demo for the hero use case
• docs/limitations.md: current product limits and non-goals
• docs/public-source-grounding.md: provenance notes for the shipped sample corpus
• tests/README.md: current automated coverage
• examples/codex/README.md: Codex MCP setup example
• examples/claude-code/README.md: Claude Code MCP setup example

Talks And Workflow Notes

• docs/ai-engineer-miami-context-plane.md: centralized context-plane talk notes and project framing
• docs/extreme-programming-with-agents.md: XP, TDD, and agent workflow notes

Limits And Scope

Current limitations are intentional:

• the system is local-first and aimed at a single developer workflow
• CI is offline-only and does not run live NVIDIA end-to-end checks by default
• the sample corpus is narrow and synthetic, not a broad enterprise handbook
• grounded answers may fail closed even when raw retrieval finds useful chunks

See docs/limitations.md for the full list and future expansion areas.

Install the optional Phoenix UI command in a separate tool environment; see installation profiles. policynim eval --headless needs no Phoenix server.