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:
Latest release

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.4.0.tar.gz (160.7 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.4.0-py3-none-any.whl (206.5 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: nullain_sdk-0.4.0.tar.gz
  • Upload date:
  • Size: 160.7 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.4.0.tar.gz
Algorithm Hash digest
SHA256 64c3bf3198b31e48d866b472b9883a54ff7db59babc471bbd5943ac2693514c5
MD5 8cccc51027ab3c9f798004684dba3b30
BLAKE2b-256 4efea33709cb748dd3d71fe8567774307c0152cc883794d2fec32bacf06ae5c7

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: nullain_sdk-0.4.0-py3-none-any.whl
  • Upload date:
  • Size: 206.5 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.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 4b7f6d0a76e04ab3e5da5e1e58ee977d09786d4b4f30c6a4fd6bb9c9b6c4db9f
MD5 21e3cfe1f72ce039eb9aa7f5cf0a96d5
BLAKE2b-256 a4ebf1187e4dfeaeedcfc7c9baf8a1d0cec44cefa106b9a24388aba04015564d

See more details on using hashes here.

Provenance

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