How to Use NucleusIQ Direct Mode (Beginner Guide + Examples)

TL;DR

Direct mode is the fastest execution path in NucleusIQ.
Use it for simple, low-risk tasks where speed matters most.
Add memory and basic plugins (like call limits and PII guard) for safer production behavior.
Move to Standard mode when tasks need deeper tool orchestration.

What Is Direct Mode in NucleusIQ?

Direct Mode is the fastest execution path in the NucleusIQ framework. It is designed for tasks that do not need heavy orchestration.

Use Direct mode when you need:

quick answers,
low latency,
minimal token/tool overhead,
simple and predictable interactions.

In practical terms, Direct mode is your default for lightweight workloads like FAQs, short summaries, formatting tasks, and assistant-style chat.

When to Choose NucleusIQ Direct Mode

Choose Direct mode if most of these are true:

Task is single-turn or near single-turn,
No complex tool choreography is required,
Occasional imperfection is acceptable,
Response speed is critical.

Avoid Direct mode when:

answers must be independently validated,
workflows require many tool calls,
Business risk is high (compliance, legal, finance).

If your workload grows in complexity, move to Standard mode first.

Quick Start: Your First Direct Mode Agent

import asyncio
from nucleusiq.agents import Agent
from nucleusiq.agents.config import AgentConfig, ExecutionMode
from nucleusiq_openai import BaseOpenAI

agent = Agent(
    name="direct_bot",
    role="Fast assistant",
    objective="Give concise, accurate answers quickly",
    llm=BaseOpenAI(model_name="gpt-4o-mini"),
    config=AgentConfig(execution_mode=ExecutionMode.DIRECT),
)

async def main():
    await agent.initialize()
    result = await agent.execute({"id": "q1", "objective": "Explain NucleusIQ in one sentence."})
    print(result)

asyncio.run(main())

What this gives you:

minimal setup,
fast runtime path,
easy baseline for production onboarding.

Direct Mode With Basic Memory

Even fast mode benefits from memory in multi-turn conversations.

import asyncio
from nucleusiq.agents import Agent
from nucleusiq.agents.config import AgentConfig, ExecutionMode
from nucleusiq.memory.factory import MemoryFactory, MemoryStrategy
from nucleusiq_openai import BaseOpenAI

memory = MemoryFactory.create_memory(MemoryStrategy.FULL_HISTORY)

agent = Agent(
    name="chat_bot",
    llm=BaseOpenAI(model_name="gpt-4o-mini"),
    memory=memory,
    config=AgentConfig(execution_mode=ExecutionMode.DIRECT),
)

async def main():
    await agent.initialize()
    await agent.execute({"id": "1", "objective": "My name is Ravi."})
    reply = await agent.execute({"id": "2", "objective": "What is my name?"})
    print(reply)

asyncio.run(main())

If context becomes long, combine Direct mode with a context control plugin or use a memory strategy like a sliding window.

Direct Mode With Lightweight Guardrails

You can still apply plugins in Direct mode for safer behavior.

import asyncio
from nucleusiq.agents import Agent
from nucleusiq.agents.config import AgentConfig, ExecutionMode
from nucleusiq.plugins.builtin import ModelCallLimitPlugin, PIIGuardPlugin
from nucleusiq_openai import BaseOpenAI

agent = Agent(
    name="safe_direct_bot",
    llm=BaseOpenAI(model_name="gpt-4o-mini"),
    config=AgentConfig(execution_mode=ExecutionMode.DIRECT),
    plugins=[
        ModelCallLimitPlugin(max_calls=5),
        PIIGuardPlugin(pii_types=["email", "phone"], strategy="redact"),
    ],
)

async def main():
    await agent.initialize()
    result = await agent.execute({"id": "s1", "objective": "Summarize this customer message safely."})
    print(result)

asyncio.run(main())

This pattern keeps responses fast while adding policy controls.

Performance and Cost Tips for Direct Mode

Use smaller/efficient models for high-volume traffic.
Keep prompts short and explicit.
Avoid unnecessary tools in low-risk requests.
Add call limits to prevent runaway behavior.
Measure the correction rate, not only latency.

Direct mode is best when your product value comes from speed and scale.

Common Mistakes

Mistake 1: Using Direct Mode for Every Task

Complex tasks usually need Standard or Autonomous mode.

Mistake 2: No Guardrails in Public-Facing Flows

Use plugins like PII guard and call limits early.

Mistake 3: Ignoring Escalation

Add a rule to upgrade complex requests from Direct to Standard mode.

Execution Flow: What Happens Internally in Direct Mode

Understanding the execution lifecycle helps teams debug behavior faster. In NucleusIQ Direct mode, the runtime path is intentionally short:

The task is normalized into agent input format.
Memory context (if configured) is loaded into the request.
Plugin hooks are applied around model call/tool call stages.
The model is called with the configured mode and optional tools.
If tool calls are produced, Direct mode can still execute a bounded tool loop.
Final content is returned, and memory is updated.

This is why Direct mode is fast: fewer orchestration layers, fewer decisions, lower runtime overhead. At the same time, it is not a “toy mode.” You still get memory, plugins, and bound tool support.

Fully Commented Example (Direct + Streaming + Guardrails)

The next example shows a practical Direct-mode setup with comments for each important line.

import asyncio
from nucleusiq.agents import Agent
from nucleusiq.agents.config import AgentConfig, ExecutionMode
from nucleusiq.plugins.builtin import ModelCallLimitPlugin, PIIGuardPlugin
from nucleusiq.streaming.events import StreamEventType
from nucleusiq_openai import BaseOpenAI

# Build a fast model client. Keep model choice cost-efficient for high traffic.
llm = BaseOpenAI(model_name="gpt-4o-mini")

agent = Agent(
    name="direct_stream_bot",
    role="Fast support assistant",
    objective="Answer quickly while protecting user data",
    llm=llm,
    # Direct mode gives shortest path for low-risk requests.
    config=AgentConfig(execution_mode=ExecutionMode.DIRECT),
    # Plugins add essential safety without heavy orchestration.
    plugins=[
        ModelCallLimitPlugin(max_calls=5),  # Prevent runaway call patterns.
        PIIGuardPlugin(
            pii_types=["email", "phone"],
            strategy="redact",
            apply_to_output=True,  # Also sanitize model output if needed.
        ),
    ],
)

async def main():
    await agent.initialize()
    task = {
        "id": "direct-001",
        "objective": "Summarize this user issue in two bullet points."
    }

    # Stream output so UI can render tokens in real time.
    async for event in agent.execute_stream(task):
        if event.type == StreamEventType.TOKEN:
            print(event.token, end="", flush=True)
        elif event.type == StreamEventType.COMPLETE:
            print("\n\n[done]")

asyncio.run(main())

Example Result Snapshot

When running the previous example, output may look like:

- User cannot access account after password reset.
- User requests immediate login recovery support.

[done]

And when PII appears in the input/output flow, redaction can produce output like:

Customer email [REDACTED_EMAIL] reported login failure after reset.
Contacted via [REDACTED_PHONE] for escalation.

These concrete results are useful in demos and acceptance tests because they verify both response quality and safety policy behavior.

Direct Mode + Memory: Multi-Turn Behavior Demonstration

A frequent beginner question is whether Direct mode can handle conversational continuity. It can, as long as you configure memory correctly.

import asyncio
from nucleusiq.agents import Agent
from nucleusiq.agents.config import AgentConfig, ExecutionMode
from nucleusiq.memory.factory import MemoryFactory, MemoryStrategy
from nucleusiq_openai import BaseOpenAI

# Use a memory strategy appropriate for the session length.
memory = MemoryFactory.create_memory(MemoryStrategy.SLIDING_WINDOW)

agent = Agent(
    name="direct_memory_bot",
    llm=BaseOpenAI(model_name="gpt-4o-mini"),
    memory=memory,
    config=AgentConfig(execution_mode=ExecutionMode.DIRECT),
)

async def main():
    await agent.initialize()
    await agent.execute({"id": "turn-1", "objective": "My product codename is Helios."})
    await agent.execute({"id": "turn-2", "objective": "I need a launch checklist tomorrow."})
    result = await agent.execute({"id": "turn-3", "objective": "What is my product codename?"})
    print(result)

asyncio.run(main())

Expected response pattern:

Your product codename is Helios.

If this does not happen, common causes are missing memory assignment, incorrect session handling, or too-aggressive context trimming.

Troubleshooting Direct Mode in Production

Symptom: Responses are fast but often shallow

Cause: task complexity is above Direct mode comfort zone.
Fix: route those requests to Standard mode based on complexity/risk classifier.

Symptom: Inconsistent recall across turns

Cause: no memory or insufficient memory window.
Fix: add MemoryFactory strategy and validate state retention behavior.

Symptom: Unexpected cost spikes

Cause: unconstrained retries or long prompts.
Fix: add model call limits and enforce prompt-size guardrails.

Symptom: Policy violations in output

Cause: missing safety plugin coverage.
Fix: add PIIGuardPlugin and output sanitization rules.

Suggested KPI Dashboard for Direct Mode

To operate Direct mode confidently, track these metrics weekly:

p50/p95 latency by endpoint
average token usage per successful response
user correction rate (how often users re-ask)
policy intervention rate (PII redactions, blocked output)
escalation rate from Direct -> Standard

A low-latency system with high correction rate is not truly efficient. Use these KPIs together, not in isolation.

Direct Mode Rollout Plan (Week-by-Week)

If your team is adopting NucleusIQ for the first time, a phased rollout avoids rework:

Week 1: Baseline

implement Direct mode on one low-risk endpoint,
capture latency and correction baseline,
validate initialization + execution lifecycle.

Week 2: Safety

add ModelCallLimitPlugin and PIIGuardPlugin,
define response formatting rules,
verify policy behavior with test prompts containing sensitive values.

Week 3: Continuity

add memory strategy for multi-turn interactions,
test recall quality at turns 1, 5, and 10,
tune context controls for stable token usage.

Week 4: Smart routing

introduce escalation rule from Direct to Standard,
route high-complexity prompts automatically,
compare quality and cost deltas between routes.

By the end of this cycle, Direct mode becomes a reliable, measurable first-tier execution path rather than a temporary prototype setting.

Final Takeaway

NucleusIQ Direct mode is not “basic only.” It is a deliberate speed-optimized execution path.

Use it where the problem is simple, latency is critical, and risk is controlled. For multi-step workflows, route to Standard mode. For high-stakes analysis, route to Autonomous mode.

Footnotes:

Additional Reading

OK, that’s it, we are done now. If you have any questions or suggestions, please feel free to comment. I’ll come up with more topics on Machine Learning and Data Engineering soon. Please also comment and subscribe if you like my work, any suggestions are welcome and appreciated.

Post Views: 8