Metadata-Version: 2.4
Name: novaagents
Version: 0.8.0
Summary: NovaAgents: a production-oriented agent harness derived from Deep Agents, with managed sessions, Nova context, skills, and long-term memory.
License-Expression: MIT
Project-URL: Upstream, https://github.com/langchain-ai/deepagents
Keywords: agents,ai,llm,langgraph,langchain,novaagents,deep-agents,sub-agents,agentic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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
Requires-Python: <4.0,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain<2.0.0,>=1.4.9
Requires-Dist: langchain-core<2.0.0,>=1.7.6
Requires-Dist: langchain-anthropic<2.0.0,>=1.7.10
Requires-Dist: langchain-google-genai<5.0.0,>=4.4.3
Requires-Dist: langsmith>=0.14.17
Requires-Dist: packaging>=23.2
Requires-Dist: wcmatch>=11.0
Provides-Extra: aws
Requires-Dist: langchain-aws<2.0.0,>=1.9.2; extra == "aws"
Provides-Extra: video
Requires-Dist: av>=18.0.0; extra == "video"
Requires-Dist: pillow>=12.3.0; extra == "video"
Dynamic: license-file

# NovaAgents

NovaAgents (`novaagents`) is a production-oriented agent harness for building stateful AI agents with managed sessions, context management, skills, subagents, and long-term memory.

> **Provenance:** NovaAgents is derived from [Deep Agents](https://github.com/langchain-ai/deepagents) (LangChain). It keeps compatibility where practical, but it is an independent package with Nova-specific APIs and behavior.

## Installation

Install from PyPI (recommended, once published):

```bash
pip install novaagents
# or
uv add novaagents
```

For local development, run from the repository root:

```bash
uv sync --all-groups
```

Optional extras:

```bash
pip install "novaagents[aws]"    # AWS Bedrock support
pip install "novaagents[video]"  # video/media helpers (av, pillow)
```

## Quickstart

Use `create_nova_agent` for the Nova graph. `create_deep_agent` is a separate compatibility factory with the inherited behavior.

```python
from novaagents import create_nova_agent
from langchain.chat_models import init_chat_model

model = init_chat_model("anthropic:claude-sonnet-4-6")

agent = create_nova_agent(
    model=model,
    system_prompt="You are a concise, reliable assistant.",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Summarize this repository."}]}
)
print(result["messages"][-1].content)
```

## Managed Sessions (Nova-specific)

`NovaSession` supervises local background tasks and serializes parent invocations. Pass it a compiled Nova graph:

```python
import asyncio
from novaagents import NovaSession

async def main():
    # Use the agent constructed in the quickstart above.
    async with NovaSession(agent, thread_id="demo-001") as session:
        result = await session.ainvoke({
            "messages": [{"role": "user", "content": "List files in / and summarize the project."}],
        })
        print(result["messages"][-1].content)
        await session.wait_until_idle()

asyncio.run(main())
```

See [MANAGED_SESSIONS.md](MANAGED_SESSIONS.md) for lifecycle, resume, and background-task behavior.
Persistence across restarts requires a persistent checkpointer and the appropriate backend. Local background workers live only for the current process.

## Nova Features

NovaAgents includes capabilities layered on the Deep Agents foundation:

- **`create_nova_agent`**: Nova graph assembly with Nova middleware defaults.
- **`NovaSession`**: local background task supervision and serialized conversation execution.
- **Context & managed skills middleware**: Nova-specific context loading/handling and skill behavior (see `novaagents.middleware`).
- **Subagents / delegation**: task decomposition via LangGraph subagent patterns.
- **Filesystem & stateful workflows**: tool-driven file operations and checkpointed agent state.
- **Long-term memory patterns**: memory-backed workflows depending on configured backend/tools.

Compatibility APIs from the upstream lineage may still exist; prefer Nova APIs for new integrations and verify behavior against this repository's tests/docs.

## Development

```bash
# install dev/test deps (example)
uv sync --group test

# lint / type / test (requires deps)
make lint
make type
make test
```

See [DEVELOPMENT.md](DEVELOPMENT.md) for development and [PUBLISHING.md](PUBLISHING.md) for PyPI releases.

## Security & Threat Model

See [THREAT_MODEL.md](THREAT_MODEL.md). NovaAgents inherits the general agent/tool risk profile of Deep Agents-derived systems: treat tool outputs, files, web content, and model outputs as untrusted inputs to policy decisions; enforce least privilege and human approval for sensitive actions.

## Changelog & License

- [CHANGELOG.md](CHANGELOG.md)
- [LICENSE](LICENSE) (MIT)

## Upstream Attribution

NovaAgents is derived from the Deep Agents project by LangChain:
- Upstream source: https://github.com/langchain-ai/deepagents
- Upstream docs: https://docs.langchain.com/oss/python/deepagents/overview

## Security

NovaAgents follows a "trust the LLM, enforce at the tool boundary" model: the agent can do anything its tools allow. Enforce boundaries via sandboxing, least-privilege tools, and human approval for sensitive actions (see [THREAT_MODEL.md](THREAT_MODEL.md)). Upstream Deep Agents security guidance: [Deep Agents security policy](https://github.com/langchain-ai/deepagents?tab=security-ov-file).

## Contributing

Contributions are welcome (features, fixes, docs, tests). Before opening changes, run available checks and record blocked validation honestly. If your work touches upstream-derived behavior, keep Nova-specific intent and compatibility clear; upstream project context: [Deep Agents](https://github.com/langchain-ai/deepagents).
