Skip to content

NucleusIQ Documentation

Build AI agents as durable software systems, not one-off demos.

Get Started Core Concepts

What We Are Building

NucleusIQ is an open-source, agent-first Python framework for teams that want to ship agents into real products.

The core idea is simple: agents should be engineered like serious software systems:

  • maintainable by teams over time
  • testable and observable in production
  • provider-portable as the ecosystem changes
  • structured for tools, memory, policy, and validation

An agent is not just one model call. It is a managed runtime with responsibilities.

Why NucleusIQ Exists

Modern models can produce impressive demos quickly.
The hard part is owning those systems for months and years.

NucleusIQ is designed to close that gap between:

  • what AI can generate fast, and
  • what engineering teams can safely maintain long term.

This means less fragile glue code, less accidental complexity, and clearer architecture as systems grow.

Our Philosophy

NucleusIQ follows a practical philosophy for dependable agent engineering:

1) Agent-first thinking

Design around the full agent lifecycle (execution, tools, memory, policy), not isolated model calls.

2) Harness over hype

Reliability comes from good scaffolding: boundaries, artifacts, visibility, and feedback loops.

3) Progressive complexity

Start simple, add orchestration only when the task justifies it.

4) Open integration, closed coupling

Integrate broadly with providers and tools, but keep the core architecture stable and portable.

5) Reliability is a feature

Validation, structured output, policy controls, and observability are first-class parts of the framework.

Build Path

Choose your path based on where you are today:

What's new in v0.7.12 — coordinated stable release ✨

Every alpha/beta provider promoted to Stable in one coordinated release

v0.7.12 is the largest release since the project began — a single, coordinated promotion that takes every alpha/beta provider to its first stable line and ships the cross-cutting native-tool observability that powers it.

Package Before Now Status
nucleusiq 0.7.11 0.7.12 🟢 Core release
nucleusiq-anthropic 0.1.0a1 (alpha) 0.2.0 🟢 Stable — Phase B feature-complete
nucleusiq-ollama 0.1.0a1 (alpha) 0.2.0 🟢 Stable — + vision wire
nucleusiq-groq 0.1.0b1 (beta) 0.1.0 🟢 Stable
nucleusiq-mcp 0.1.0b1 (beta) 0.1.0 🟢 Stable
nucleusiq-openai 0.6.4 0.7.0 🟢 Stable (native-tool obs)
nucleusiq-gemini 0.2.6 0.3.0 🟢 Stable (native-tool obs)

All providers floor on nucleusiq>=0.7.12. 3,705+ tests passing across the monorepo (incl. 6 live Anthropic Phase B tests against the real API). After this release the project returns to a bug-fix / single-provider cadence.

Release notes — v0.7.12 · Changelog

Anthropic 0.2.0 Stable — Phase B feature-complete 🚀

nucleusiq-anthropic graduates from alpha to Production/Stable with full Phase B support: native server tools, prompt caching, extended thinking, and first-class server-tool observability.

  • AnthropicTool factory — web_search(), web_fetch(), code_execution() with dated wire types and auto anthropic-beta headers.
  • Prompt caching — cache_system=True / cache_tools=True cuts repeated-prompt token cost dramatically.
  • Extended thinking — thinking="low"|"medium"|"high"|"max" resolved to a token budget at wire time.
  • Server-tool observability — server_tool_use + per-tool *_tool_result blocks (code_execution_tool_result, web_search_tool_result, …) surface as ServerToolCall + ToolCallRecord(executed_by="provider") automatically.
  • 3 runnable Phase B example scripts + 6 live integration tests against the real Anthropic API.
  • 151 unit tests, 95.91% coverage (gate ≥ 95%).

Anthropic provider guide · Native server tools · Prompt caching · Extended thinking

Provider-agnostic native-tool observability in core

A new field on every traced tool call — ToolCallRecord.executed_by: Literal["local","provider"] — lets you split locally-run tools from provider-executed ones (Anthropic web_search, OpenAI code_interpreter / file_search / web_search, Gemini google_search / code_execution, Groq compound tools) with one query.

LLMCallRecord also gained provider, request_id, organization_id, stop_reason, cache_read_input_tokens, cache_creation_input_tokens, and a generic metadata dict — populated by every provider in this release.

Observability guide

Ollama 0.2.0 Stable — vision wire

nucleusiq-ollama graduates to Stable. The wire layer now splits OpenAI-style multimodal content lists into Ollama's message.content + message.images fields, with proper handling of data:image/...;base64,... URLs and warnings for HTTP image URLs.

Ollama provider guide

What was new in v0.7.11

MCP tool adapter (now Stable in v0.7.12)

nucleusiq-mcp 0.1.0 — Stable (was beta in v0.7.11)

Universal Model Context Protocol adapter — plug any MCP server (GitHub, Slack, Postgres, Stripe, your own) into a NucleusIQ agent in one line, across any LLM provider. Built on the official mcp SDK.

  • Transports: stdio + Streamable HTTP + SSE (auto-detected).
  • Auth: BearerAuth, OAuthAuth (OAuth 2.1 + PKCE), EnvAuth, CustomHeadersAuth — typed strategies + auth="..." shorthand.
  • Resilience: on_connect_failure="skip", health_check=True, runtime MCPTool.ping().
  • Observability: every tool call carries source="mcp://server=<name> ..." for tracing.
  • Tests: 235 unit (98.68% coverage) + 13 live integration tests across all three transports.

MCP integration guide · MCP quickstart

v0.7.10 (latest tagged core)

Core security extras + Ollama alpha

  • nucleusiq 0.7.10 — optional nucleusiq[http]; urllib3 resolution hardening in locks; structured-output resolver recognizes Ollama / Groq LLMs for OutputSchema payloads.
  • nucleusiq-ollama 0.1.0a1 (alpha) — local / remote Ollama via official ollama SDK: BaseOllama, tools, streaming, structured format, think / keep_alive. Requires nucleusiq>=0.7.10.

Changelog · Ollama provider · Ollama quickstart · Migration (0.7.9 → 0.7.10)

v0.7.9

LLM rate limits + Groq beta

  • nucleusiq.llms.retry_policy — shared 429 handling: Retry-After parsing, capped backoff, ceiling (120s default single sleep cap).
  • Providers: nucleusiq-openai 0.6.4, nucleusiq-gemini 0.2.6, nucleusiq-groq 0.1.0b1 (public beta) — dependency floor nucleusiq>=0.7.9.
  • Groq — stream open uses the same 429 policy as chat; strict_model_capabilities on GroqLLMParams; nucleusiq_groq.capabilities allowlist for parallel_tool_calls (warnings vs strict InvalidRequestError).

Changelog · Groq provider · Groq quickstart · Migration (0.7.8 → 0.7.9)

v0.7.8

Run-local context state + Groq alpha debut

  • Workspace / evidence / lexical corpus — per-run in-memory analyst state with optional framework tools (budget-exempt).
  • L4.5 activation, phase control, evidence gate, synthesis package, autonomous fixes — see Run-local context state.
  • Groq landed first as nucleusiq-groq 0.1.0a1 (since superseded by 0.1.0b1 + nucleusiq>=0.7.9).

Changelog · Migration (0.7.7 → 0.7.8)

v0.7.7

Context Management v2 + execution fixes

  • Stable V2 pipeline — compaction, masking, recall/rehydration tuned for PDF-heavy agents (squeeze_threshold=0.70 default).
  • Optional @tool(idempotent=True) — safe dedup for pure tools; default remains non-idempotent.
  • AgentResult + tool caps — clearer status=error and ToolCallLimitError when limits bite; tools-free synthesis when the tool cap is hit (synthesis on).
  • Providers: nucleusiq-openai 0.6.3, nucleusiq-gemini 0.2.5 — aligned with core 0.7.7.

Changelog · Migration (0.7.6 → 0.7.7)

v0.7.6

Context Window Management

Automatic context management for tool-heavy agents — prevents context overflow and ensures the LLM always has room to respond.

from nucleusiq.agents.context import ContextConfig, ContextStrategy

config = AgentConfig(
    context=ContextConfig(strategy=ContextStrategy.PROGRESSIVE),
)

Context management guide

Breaking: Prompt System Refactor

prompt is now mandatory on Agent. The narrative field has been removed. role and objective are labels only — they are not sent to the LLM.

from nucleusiq.prompts.zero_shot import ZeroShotPrompt

agent = Agent(
    name="analyst",
    prompt=ZeroShotPrompt().configure(
        system="You are a data analyst. Provide detailed analysis.",
    ),
    llm=llm,
)

Migration guide

Synthesis Pass + ObservabilityConfig

  • Synthesis pass — after multi-round tool loops, the agent makes one final LLM call without tools to produce the full deliverable
  • ObservabilityConfig — unified config replacing verbose + enable_tracing
  • Context telemetry — peak utilization, compaction events, token savings in AgentResult

Observability docs

v0.7.5

  • Gemini native + custom tool mixing — transparent proxy pattern, zero code changes
  • Full observability wiring — PluginEvent, MemorySnapshot, AutonomousDetail in AgentResult

v0.7.4

  • ExecutionTracer — full LLM/tool call observability
  • Pyrefly static type checking — 121 type errors fixed, CI-gated
  • Exhaustive error wiring — typed exceptions everywhere

v0.7.2-0.7.3

  • Unified exception hierarchy — 10 error families
  • AgentResult response contract — typed, immutable Pydantic model
  • Gemini tool-calling fixes — $ref/$defs inlining

Current packages (all 🟢 Stable as of v0.7.12 / 2026-05-26): nucleusiq 0.7.12, nucleusiq-openai 0.7.0, nucleusiq-gemini 0.3.0, nucleusiq-anthropic 0.2.0, nucleusiq-groq 0.1.0, nucleusiq-ollama 0.2.0, nucleusiq-mcp 0.1.0. All providers floor on nucleusiq>=0.7.12.

See the full changelog.