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.3.2)

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.1.tar.gz (159.9 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.1-py3-none-any.whl (205.6 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: nullain_sdk-0.3.1.tar.gz
  • Upload date:
  • Size: 159.9 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.1.tar.gz
Algorithm Hash digest
SHA256 d1f5095aca89575a1e80ef3668d17ba57e5b772b1c1d2b09a6a2de14e05e0a0a
MD5 519273722937d9be57a57f60b763e679
BLAKE2b-256 89081e976dce70823939e474200d5387d37155a8e9c645987b8e5a3f0b65939d

See more details on using hashes here.

Provenance

The following attestation bundles were made for nullain_sdk-0.3.1.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.1-py3-none-any.whl.

File metadata

  • Download URL: nullain_sdk-0.3.1-py3-none-any.whl
  • Upload date:
  • Size: 205.6 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.1-py3-none-any.whl
Algorithm Hash digest
SHA256 6e3aeedf20bebb95fb6060318228f1ae3e2bc015a484809a32f03cbf939be632
MD5 56bcb423733565fc790a6c92dae8c322
BLAKE2b-256 46296eb94e0c040af073acc686cf9533b4bf9286b245d2b065b6b9be4adad96c

See more details on using hashes here.

Provenance

The following attestation bundles were made for nullain_sdk-0.3.1-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