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.x

v0.7.7 (latest)

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: nucleusiq 0.7.7, nucleusiq-openai 0.6.3, nucleusiq-gemini 0.2.5

See the full changelog.