nullain-sdk

Core engine of the Nullain Agent SDK — a production-grade autonomous coding agent for Python, built on Hexagonal Architecture and immutable Event Sourcing.

This package provides the agent loop, LLM provider adapters, model routing, context management, memory, MCP/LSP clients, the permission/sandbox security layer, and the plugin system. Built-in tools (read_file, bash, grep, ...) live in the separate nullain-tools package, which nullain-sdk depends on.

Install

pip install nullain-sdk

Quick start

import asyncio
from nullain import Agent


async def main() -> None:
    agent = Agent(workspace_root=".")
    result = await agent.run("list the python files in this workspace")
    print(result.final_text)


asyncio.run(main())

A synchronous facade is also available for scripts:

from nullain import Agent

result = Agent(workspace_root=".").run_sync("say hello")
print(result.final_text)

Agent assembles safe defaults — an Ollama Cloud provider, the built-in tool registry, fail-closed permission policy, and the platform sandbox — so most callers never need to construct the lower-level AgentLoop directly.

What's inside

  • AgentLoop — the Plan/Act/Verify ReAct loop, with self-correction, loop detection, and adaptive step/token budgets.
  • Conversation — immutable, append-only event sourcing with a deterministic fold; conversation state is always derivable from history.
  • ModelRouter — task classification into fast/balanced/deep tiers with circuit breakers and fallback chains.
  • ContextManager — automatic compaction at 75% context-window capacity, preserving active task state and instruction re-injection.
  • PermissionPolicy + Sandbox — 3-tier command/file permissions (allow/ask/deny) plus an OS-level, fail-closed subprocess sandbox (Landlock on Linux, Seatbelt on macOS, Job Object on Windows).
  • Authority — subagent capability intersection: a spawned subagent's effective authority is the meet of parent, delegation, definition, and policy — never wider than any one of them.
  • PluginLoader — signed, capability-manifested, SBOM'd plugin bundles (Ed25519 verification via the optional signing extra).

Documentation

The full docs, architecture diagrams, configuration reference, and CLI usage live in the monorepo README and docs/ — this package is one piece of that whole; the CLI (nullain) and built-in tools are what most users interact with day to day.

License

MIT — see LICENSE.

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.4.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for nettylinux from gravatar.com nettylinux

Credits

Author: Nullain

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Provides Extra

postgres rag signing

Tags

agent agentic ai coding-agent llm mcp ollama sandbox sdk

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nullain_sdk-0.3.2.tar.gz (160.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

nullain_sdk-0.3.2-py3-none-any.whl (206.4 kB view details)

Uploaded Python 3

File details

Details for the file nullain_sdk-0.3.2.tar.gz.

File metadata

  • Download URL: nullain_sdk-0.3.2.tar.gz
  • Upload date:
  • Size: 160.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for nullain_sdk-0.3.2.tar.gz
Algorithm Hash digest
SHA256 608aa3c4c20f1bc3561b11a1918cf652828ad4120287c74b09e33881b2ba3040
MD5 385484d2bca87652421c8712dc61e791
BLAKE2b-256 026368fc2532b438ce5be986042a1fefd0134a486bdc0598ce151ffc819468bb

See more details on using hashes here.

Provenance

The following attestation bundles were made for nullain_sdk-0.3.2.tar.gz:

Publisher: release.yml on netty-linux/nullain-agent-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nullain_sdk-0.3.2-py3-none-any.whl.

File metadata

  • Download URL: nullain_sdk-0.3.2-py3-none-any.whl
  • Upload date:
  • Size: 206.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for nullain_sdk-0.3.2-py3-none-any.whl
Algorithm Hash digest
SHA256 49fad33bda0ede1b3d64bc2fc306c572e7b00d8582450d6ccd288c167caca73e
MD5 d181179e658cfb7acc0497687c2ca22e
BLAKE2b-256 7fb0ca29d2ce19666213293da44be71e70430b7bf3ec5db598d252c012a1cfe7

See more details on using hashes here.

Provenance

The following attestation bundles were made for nullain_sdk-0.3.2-py3-none-any.whl:

Publisher: release.yml on netty-linux/nullain-agent-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page