Skip to content

Core Concept: Tasks

A Task represents one concrete user request.

from nucleusiq.agents.task import Task

task = Task(
    id="task-1",
    objective="Summarize this report",
    metadata={"priority": "high"},
)

Task fields

  • id: unique task identifier
  • objective: concrete user instruction
  • context: optional auxiliary facts. Rendered (v0.7.14) as a bounded ## Task Context block immediately before the objective. Previously accepted and silently dropped.
  • resources: optional list of documents / files / records this task must cover (v0.7.14)
  • metadata: optional tags / structured metadata
  • attachments: optional multimodal inputs

Grounded resources (v0.7.14)

When the job is about a known set of documents, declare them on the task — do not paste the same list into objective. The Decomposer, coverage follow-up, and Critic all use this list.

from nucleusiq.agents.task import Task

task = Task(
    id="inv-1",
    objective="Extract vendor and total from every invoice.",
    resources=["invoices/acme.pdf", "invoices/globex.pdf"],
    context={"currency": "EUR", "customer": "ACME"},
)

task.effective_resources() returns a de-duplicated list. context["resources"] is accepted as a fallback; the typed resources field wins when both are present.

In Autonomous mode:

  1. The Decomposer grounds Gate 4 on the list (same sources / one record → SIMPLE).
  2. Every COMPLEX child must claim a slice.
  3. After execution, unprocessed = resources − touched lands in result.metadata["coverage"] and result.diagnostics.coverage.
  4. One bounded follow-up runs on the gap (coverage_followup=True, default).
  5. evidence_gate_enforce=True turns a residual gap into status=ABSTAINED / abstention_code="coverage_incomplete".

Without resources, coverage reconciliation is a no-op.

MessageBuilder emits one bounded ## Task Context / ## Resources (N) user message. Resources beyond 60 are summarised as a count. Tasks without context / resources produce the same messages as before v0.7.14.

Do not paste the same facts into objective unless you want the classifier, Critic, and validator to see them twice.

Attachment example

from nucleusiq.agents.attachments import Attachment, AttachmentType
from nucleusiq.agents.task import Task

task = Task(
    id="task-2",
    objective="Extract key points from this PDF",
    attachments=[
        Attachment(type=AttachmentType.PDF, data=pdf_bytes, name="report.pdf"),
    ],
)

See also