Metadata-Version: 2.5
Name: nagents
Version: 0.17.0
Summary: A lightweight, dependency-free LLM agent framework with direct HTTP-based provider integration
Project-URL: Homepage, https://github.com/abi-jey/nagents
Project-URL: Repository, https://github.com/abi-jey/nagents
Project-URL: Documentation, https://abi-jey.github.io/nagents/
Project-URL: Issues, https://github.com/abi-jey/nagents/issues
Author-email: Abbas Jafari <git@public.abja.dev>
License: MIT
License-File: LICENSE
Keywords: agent,ai,anthropic,async,claude,gemini,gpt,llm,openai,streaming
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.11
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: designer
Requires-Dist: pydantic>=2.0; extra == 'designer'
Provides-Extra: dev
Requires-Dist: fastapi; extra == 'dev'
Requires-Dist: httpx>=0.28.1; extra == 'dev'
Requires-Dist: mypy>=1.14.0; extra == 'dev'
Requires-Dist: numpy>=2.4.6; (python_version < '3.12') and extra == 'dev'
Requires-Dist: numpy>=2.5.2; (python_version >= '3.12') and extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pydantic>=2.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: sounddevice>=0.5.0; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27.0; extra == 'docs'
Provides-Extra: server
Requires-Dist: fastapi>=0.100; extra == 'server'
Requires-Dist: pydantic>=2.0; extra == 'server'
Requires-Dist: uvicorn>=0.24; extra == 'server'
Requires-Dist: websockets<17,>=13; extra == 'server'
Provides-Extra: tui
Requires-Dist: textual>=8.2.8; extra == 'tui'
Provides-Extra: voice
Requires-Dist: sounddevice>=0.5.6; extra == 'voice'
Provides-Extra: web
Requires-Dist: aiortc<2,>=1.14; extra == 'web'
Requires-Dist: fastapi>=0.100; extra == 'web'
Requires-Dist: pydantic>=2.0; extra == 'web'
Requires-Dist: uvicorn>=0.24; extra == 'web'
Requires-Dist: websockets<17,>=13; extra == 'web'
Description-Content-Type: text/markdown

# nagents

[![PyPI version](https://img.shields.io/pypi/v/nagents.svg)](https://pypi.org/project/nagents/)
[![Python versions](https://img.shields.io/pypi/pyversions/nagents.svg)](https://pypi.org/project/nagents/)
[![CI](https://github.com/abi-jey/nagents/actions/workflows/ci.yml/badge.svg)](https://github.com/abi-jey/nagents/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/abi-jey/nagents/branch/main/graph/badge.svg)](https://codecov.io/gh/abi-jey/nagents)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://abi-jey.github.io/nagents/)

A lightweight LLM agent framework with direct HTTP-based provider integration.

## Features

- **Multi-Provider Support**: OpenAI, Anthropic Claude, and Google Gemini APIs
- **Streaming Events**: Real-time text chunks, tool calls, and usage statistics
- **Tool Execution**: Register Python functions as tools with automatic schema generation
- **Session Management**: SQLite-based conversation persistence
- **Batch Processing**: Process multiple requests efficiently
- **Python Harness Extensions**: Custom context transforms, lifecycle hooks, and replaceable compaction algorithms
- **Optional Terminal Client**: `ngn` provides interactive coding, approvals, sessions, and headless JSON events
- **Minimal Dependencies**: Only `aiohttp` and `aiosqlite` required

## Library Installation

```bash
pip install nagents
```

## ngn Terminal Client

`ngn` is an optional terminal and headless coding harness, available in published
distributions with the `tui` extra. Published wheels also include `ngn serve`,
the `web` extra, and built frontend assets, verified in
[v0.15.0](https://github.com/abi-jey/nagents/releases/tag/v0.15.0). This README
describes the **current source checkout**, which may include newer changes. See
[release availability](docs/guide/ngn-installation.md#release-availability) when
checking the commands and fixes in an installed distribution.

Keep the existing Poetry workflow from the repository root:

```bash
poetry install -E dev -E tui
poetry run ngn --demo
```

For a new local editable environment with uv, from the repository root:

```bash
uv venv --python 3.13
uv pip install --python .venv/bin/python -e '.[tui]'
uv run --no-project --python .venv/bin/python ngn --demo
```

Do not recreate an existing Poetry-managed `.venv`; keep using Poetry or choose
a separate local environment. This uv workflow does not require `uv sync`,
`uv lock`, or changes to the existing `uv.lock`. The explicit interpreter needs
no activation. See [ngn installation](docs/guide/ngn-installation.md) for optional
activation, headless-only installation, and isolated `uvx`/`uv tool` alternatives.

The offline demo needs no API key, makes no model requests, skips Python plugins,
and performs no workspace edits or shell commands. It does save demo
conversations locally. Send `demo approval` to try a change-preview dialog or
`demo subagents` to exercise three native async jobs without provider calls.

For a real model, set the provider key outside YAML and launch through the same
environment, for example `poetry run ngn --auth api-key --model MODEL_ID` or
`uv run --no-project --python .venv/bin/python ngn --auth api-key --model MODEL_ID`.
With the environment activated, use `ngn run --json "your prompt"` for headless
integration. Non-interactive approvals fail closed.

Type `/` for selectable commands from the harness, skills, and trusted plugins.
Shift+Enter inserts a newline; Tab cycles agent profiles. Input queues while work
is active, or use `--submit-mode interrupt`. The default `terminal` theme inherits
terminal colors; try `--theme graphite`, `ocean`, or `ember`, and disable motion
with `--no-animations`. Build-capable delegation uses the built-in `agent` profile
by default, never exceeds the parent's permissions, and defaults to depth two
(root 0, child 1, grandchild 2).

For ChatGPT/Codex subscription access, start `ngn` without `--demo` and use
`/login`, or run `ngn login chatgpt` (same as `--device-auth`). Device login must
be enabled in your ChatGPT security/workspace settings. This uses a separate
Codex Responses route, not a general-purpose OpenAI API key. `ngn login` also
selects OpenRouter through a browser sign-in or stores API keys for OpenAI,
Anthropic, Gemini, and custom OpenAI-compatible endpoints; keys are entered
hidden or referenced with `--api-key-env`, and `ngn login --status`/`ngn logout`
manage the saved selection. See the guide for credential storage and `--auth`
selection. Saved credentials are never sent to custom endpoints.

Configuration uses top-level YAML, **not an `ngn:` wrapper**. Priority is built-ins
< saved `ngn login` selection < `NGN_*` environment defaults < global YAML <
trusted project YAML < explicit YAML < CLI. The global file is
`~/.config/ngn/config.yaml` (respecting `XDG_CONFIG_HOME`); workspace
`.ngn/config.yaml` needs `--trust-project`, or explicit selection with `--config`.
Any explicitly selected config file is trusted.
See the [full schema and recipes](docs/guide/ngn-configuration.md) for types,
defaults, ranges, profile replacement, relative paths, and LiteLLM endpoints.

Python plugins can change how the agent builds context, compacts history, and
executes tools. The TUI uses the same harness as the headless client; Textual
remains an optional dependency. See the [ngn usage guide](docs/guide/ngn.md),
[custom Python behavior example](examples/harness/custom_behavior.py), and
[upstream research](docs/development/harness-research.md).

## HTTP Interfaces

The current checkout includes a web-only **Agent Designer**: a YAML-backed agent
canvas with per-agent providers, instructions, selected tools/MCPs, delegation,
chat, and persisted context/request inspection. See the
[Agent Designer guide](docs/guide/agent-designer.md) for configuration and terminal
execution with `ngn --design`.

These are separate applications, not interchangeable launch commands:

| Command | Purpose | Installation |
| --- | --- | --- |
| `python -m nagents.server` | Legacy HTTP/SSE API server. The current source has no bundled chat UI. | Current checkout with `[server]`; see the [legacy API server guide](docs/guide/server.md) for token, bind, and deployment setup. |
| `ngn serve` | Local React client for the ngn coding harness, sharing its workspace sessions and approvals. Also the Docker image's default command. | Install `nagents[web]` for a published wheel with built frontend assets, or build an editable checkout. See the [local web client guide](docs/guide/ngn-web.md). |

The frontend source lives in `src/nagents/web-ui/`; its Vite build goes to
`src/nagents/web/static/`. Plain `ngn serve` uses the bundled assets without
building or reloading. Use `ngn serve --dev` in an editable checkout to build stale
assets and reload after frontend or Python edits. Source build/check commands are in
[Contributing](docs/development/contributing.md#web-client-development).
For the runtime image's no-config startup, mounted YAML and Kubernetes Secret or
environment-variable examples, see the [container configuration guide](docs/guide/ngn-container.md).

The legacy server's authentication hardening and removal of its old UI are also
post-`0.5.0` changes. Do not apply the current security guarantees to that older
wheel or an unverified container image. Both applications are trusted-operator
tools, not sandboxes or multi-user services.

## Quick Start

```python
import asyncio
from pathlib import Path
from nagents import Agent, Provider, ProviderType, SessionManager


async def main():
    # Create a provider
    provider = Provider(
        provider_type=ProviderType.OPENAI_COMPATIBLE,
        api_key="your-api-key",
        model="gpt-4o-mini",
    )

    # Create an agent
    agent = Agent(
        provider=provider,
        session_manager=SessionManager(Path("sessions.db")),
        streaming=True,
    )

    # Run a conversation
    async for event in agent.run("Hello, how are you?"):
        if hasattr(event, "chunk"):
            print(event.chunk, end="")

    await agent.close()


asyncio.run(main())
```

## Providers

nagents supports three provider types:

| Provider | Type | Models |
|----------|------|--------|
| OpenAI | `ProviderType.OPENAI_COMPATIBLE` | gpt-4o, gpt-4o-mini, etc. |
| Anthropic | `ProviderType.ANTHROPIC` | claude-3-5-sonnet, claude-3-opus, etc. |
| Google | `ProviderType.GEMINI_NATIVE` | gemini-2.0-flash, gemini-1.5-pro, etc. |

## With Tools

```python
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"Weather in {city}: Sunny, 22°C"


agent = Agent(
    provider=provider,
    session_manager=SessionManager(Path("sessions.db")),
    tools=[get_weather],
)

async for event in agent.run("What's the weather in Paris?"):
    ...
```

## With Session Persistence

```python
from pathlib import Path
from nagents import SessionManager

session_manager = SessionManager(Path("sessions.db"))

agent = Agent(
    provider=provider,
    session_manager=session_manager,
)

# Use a specific session ID for conversation continuity
async for event in agent.run("Remember my name is Alice", session_id="user-123"):
    ...
```

## Documentation

- [ngn Installation](docs/guide/ngn-installation.md)
- [ngn Usage Guide](docs/guide/ngn.md)
- [ngn Configuration Reference](docs/guide/ngn-configuration.md)
- [ngn Local Web Client](docs/guide/ngn-web.md)
- [Legacy API Server](docs/guide/server.md)
- [Installation](https://abi-jey.github.io/nagents/getting-started/installation/)
- [Quick Start](https://abi-jey.github.io/nagents/getting-started/quickstart/)
- [Providers Guide](https://abi-jey.github.io/nagents/guide/providers/)
- [Tools Guide](https://abi-jey.github.io/nagents/guide/tools/)
- [API Reference](https://abi-jey.github.io/nagents/api/agent/)

## License

MIT
