Metadata-Version: 2.4
Name: nullain-sdk
Version: 0.4.0
Summary: Production agentic framework for Python — model routing, plan/act/verify, fail-closed sandboxing, and provable subagent authority
Project-URL: Homepage, https://github.com/netty-linux/nullain-agent-sdk
Project-URL: Repository, https://github.com/netty-linux/nullain-agent-sdk
Project-URL: Documentation, https://github.com/netty-linux/nullain-agent-sdk/tree/master/docs
Project-URL: Issues, https://github.com/netty-linux/nullain-agent-sdk/issues
Author: Nullain
License-Expression: MIT
License-File: LICENSE
Keywords: agent,agentic,ai,coding-agent,llm,mcp,ollama,sandbox,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: anyio>=4.3.0
Requires-Dist: colorama>=0.4.6; sys_platform == 'win32'
Requires-Dist: httpx>=0.27.0
Requires-Dist: nullain-tools>=0.3.0
Requires-Dist: opentelemetry-api>=1.24.0
Requires-Dist: opentelemetry-sdk>=1.24.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: rich>=13.7.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: tenacity>=8.3.0
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29.0; extra == 'postgres'
Provides-Extra: rag
Requires-Dist: fastembed>=0.4.0; extra == 'rag'
Requires-Dist: qdrant-client>=1.10.0; extra == 'rag'
Provides-Extra: signing
Requires-Dist: cryptography>=42.0.0; extra == 'signing'
Description-Content-Type: text/markdown

# nullain-sdk

Core engine of the [Nullain Agent SDK](https://github.com/netty-linux/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`](https://pypi.org/project/nullain-tools/) package, which
`nullain-sdk` depends on.

## Install

```bash
pip install nullain-sdk
```

## Quick start

```python
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:

```python
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/`](https://github.com/netty-linux/nullain-agent-sdk) —
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](https://github.com/netty-linux/nullain-agent-sdk/blob/master/nullain-sdk/LICENSE).
