Nanitics

Python SDK for building single-agent and multi-agent AI systems.

Compose agents from typed primitives. Trace every decision through the built-in Observatory. No framework lock-in.

Why Nanitics?

• Composable primitives, not a framework. Pick the pieces you need — agent strategies, coordination patterns, memory, evaluation, HITL, tools — and compose them. No runtime or opinionated workflow shape is imposed. Apache-2.0, typed, with an explicit public API (nanitics.__all__).
• Trace-first observability. Every agent loop, tool call, and coordination event emits a structured event. The built-in Observatory trace viewer turns that into a live debugging surface from day one. No instrumentation to add.
• Real-services validation. Public components are validated against real LLM providers before release, not just mocks. Mocks drive fast tests; real services prove correctness.

Features

Start here

The minimum you need to build something useful.

• ReAct agent — the default reasoning loop. Add a tool, give it a task, get a result.
• Tools — function tools, MCP tools, and built-in tools (web search, HTTP, file read, code execution) with automatic schema generation.
• Working memory — structured state that survives across steps.
• Human-in-the-Loop — approval and revision gates, with durable suspension for long-running workflows.
• Multi-agent foundations — agent-as-tool, handoff, broadcast: the primitives that compose two agents.

Also in core

Reasoning and CodeAct agents, the remaining memory types (episodic, long-term, semantic, shared), Sequential / Parallel / DAG orchestration, orchestrator, supervisor, blackboard, and judge-router coordination, evaluators, planning, event-based tracing with the Observatory, and safety primitives.

Advanced patterns

Specialized primitives in nanitics.specialized — Reflexion, ReWOO, LATS, Tree of Thought, bidding, debate, consensus, message bus, peer network, hierarchical planning, and more workflow shapes. Reach for them deliberately. See the Advanced Patterns index.

Public API surface

The SDK exposes three namespaces. nanitics is the recommended core — primitives and load-bearing compositions for building most agentic systems. nanitics.patterns exposes named compositions over the core (sugar over primitives — create_orchestrator, the structured handoff stack). nanitics.specialized exposes specialized primitives that are structurally distinct but niche — reach for them deliberately rather than by default. nanitics.__all__ (plus nanitics.patterns.__all__ and nanitics.specialized.__all__) is the authoritative list.

Quick Start

For a full end-to-end run against a real LLM, see the deployment guide.

Install Nanitics:

pip install nanitics

Create a ReAct agent with a tool, driven by a scripted MockLLMClient so the snippet runs without an API key:

import asyncio
from nanitics.infrastructure import LLMResponse, MockLLMClient
from nanitics.strategies import ReActAgent, tool
from nanitics.tracing import InMemoryEmitter, ToolCall, Usage

@tool("greet", "Greet someone by name")
async def greet(name: str) -> str:
    return f"Hello, {name}!"

async def main():
    llm = MockLLMClient(responses=[
        LLMResponse(
            content="I'll greet them.",
            tool_calls=[ToolCall(id="1", name="greet", arguments={"name": "world"})],
            usage=Usage(input_tokens=50, output_tokens=20),
            model="mock",
            stop_reason="tool_use",
        ),
        LLMResponse(
            content="Hello, world!",
            tool_calls=[],
            usage=Usage(input_tokens=80, output_tokens=15),
            model="mock",
            stop_reason="end_turn",
        ),
    ])
    agent = ReActAgent(
        name="my-agent",
        llm_client=llm,
        emitter=InMemoryEmitter("trace-001"),
        system_prompt="You are a helpful assistant.",
        tools=[greet],
    )
    result = await agent.run("Say hello to the world")
    print(result.output)

asyncio.run(main())

To run the same agent against a real provider, set ANTHROPIC_API_KEY and swap MockLLMClient(...) for AnthropicLLMClient(model="claude-haiku-4-5"). Everything else above is unchanged.

See the Getting Started guide for a full walkthrough. For the full API, read the docstrings in the source tree under nanitics/.

LLM Providers

Nanitics supports multiple LLM providers:

For testing and development, use MockLLMClient — no API keys required.

Examples

The examples directory contains runnable examples covering every SDK component. All examples use MockLLMClient for deterministic, API-key-free execution.

See the examples README for a complete index.

Documentation

The full guides index organizes everything in four tiers — Start here, Build on it, Ship it, and Advanced patterns. The fastest entry points:

Project

• Status: Pre-1.0. The public API is nanitics.__all__; see the deprecation policy for the change contract.
• Contributing: CONTRIBUTING.md for guidelines, DEVELOPMENT.md for setup.
• Governance: GOVERNANCE.md covers decisions and release cadence; MAINTAINERS.md names the current maintainers.
• Trademark: TRADEMARK.md for who owns the Nanitics name and what uses are permitted.
• Questions and ideas: GitHub Discussions; Getting Help for the channel split.
• Security: report vulnerabilities via SECURITY.md; SDK security posture in the security guide.

About

Nanitics is maintained by Propodeum.

License

Apache License 2.0. See LICENSE for the full text.