Metadata-Version: 2.4
Name: noesium
Version: 0.3.4
Summary: Towards a cognitive agentic framework
Author-email: Xiaming Chen <chenxm35@gmail.com>
Maintainer-email: Xiaming Chen <chenxm35@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mirasoth/noesium
Project-URL: Repository, https://github.com/mirasoth/noesium
Keywords: agents,multi-agent system,cognition,artificial intelligence
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: aiohttp>=3.12.15
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: colorlog>=6.8.0
Requires-Dist: typing-extensions>=4.8.0
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: uuid7>=0.1.0
Requires-Dist: langchain-core>=1.2.16
Requires-Dist: langgraph>=1.0.10
Requires-Dist: bubus>=1.5.6
Requires-Dist: pytest>=8.4.2
Requires-Dist: pytest-asyncio>=1.3.0
Provides-Extra: google
Requires-Dist: google-genai>=1.5.0; extra == "google"
Requires-Dist: google-api-python-client>=2.174.0; extra == "google"
Requires-Dist: google-auth-oauthlib>=1.2.2; extra == "google"
Requires-Dist: google-auth>=2.40.3; extra == "google"
Provides-Extra: aliyun
Requires-Dist: aliyun-python-sdk-core<3.0.0,>=2.13.1; extra == "aliyun"
Provides-Extra: llm
Requires-Dist: litellm>=1.0.0; extra == "llm"
Requires-Dist: openai>=1.0.0; extra == "llm"
Requires-Dist: instructor>=1.10.0; extra == "llm"
Provides-Extra: local-llm
Requires-Dist: ollama>=0.5.3; extra == "local-llm"
Requires-Dist: llama-cpp-python>=0.3.16; extra == "local-llm"
Requires-Dist: huggingface-hub>=0.34.4; extra == "local-llm"
Provides-Extra: all-llm
Requires-Dist: noesium[aliyun,google,llm,local-llm]; extra == "all-llm"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3.72; extra == "langchain"
Requires-Dist: langchain-text-splitters>=0.3.0; extra == "langchain"
Requires-Dist: langchain-ollama>=0.2.0; extra == "langchain"
Requires-Dist: langgraph>=0.5.4; extra == "langchain"
Provides-Extra: agents
Requires-Dist: noesium[langchain]; extra == "agents"
Requires-Dist: bubus>=1.5.6; extra == "agents"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
Requires-Dist: psycopg2>=2.9.10; extra == "postgres"
Provides-Extra: weaviate
Requires-Dist: weaviate-client<5,>=4; extra == "weaviate"
Requires-Dist: protobuf<6,>=5; extra == "weaviate"
Provides-Extra: datascience
Requires-Dist: networkx>=3.5; extra == "datascience"
Requires-Dist: matplotlib>=3.8.0; extra == "datascience"
Requires-Dist: pexpect>=4.9.0; extra == "datascience"
Requires-Dist: ipython>=8.18.0; extra == "datascience"
Requires-Dist: pandas>=2.0.0; extra == "datascience"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: tools
Requires-Dist: noesium[aliyun,datascience,google,mcp]; extra == "tools"
Requires-Dist: wizsearch<2.0.0,>=1.1.2; extra == "tools"
Requires-Dist: arxiv>=2.2.0; extra == "tools"
Requires-Dist: pillow<12.0,>=10.1.0; extra == "tools"
Requires-Dist: pymupdf>=1.23.0; extra == "tools"
Requires-Dist: openpyxl>=3.1.5; extra == "tools"
Requires-Dist: wikipedia-api>=0.6.0; extra == "tools"
Requires-Dist: aiofiles>=24.1.0; extra == "tools"
Provides-Extra: browser-use
Requires-Dist: screeninfo>=0.8.1; extra == "browser-use"
Requires-Dist: uuid7>=0.1.0; extra == "browser-use"
Requires-Dist: authlib>=1.6.0; extra == "browser-use"
Requires-Dist: pypdf>=5.7.0; extra == "browser-use"
Requires-Dist: cdp-use>=1.4.4; extra == "browser-use"
Requires-Dist: html2text>=2025.4.15; extra == "browser-use"
Requires-Dist: psutil>=7.0.0; extra == "browser-use"
Requires-Dist: pillow>=11.3.0; extra == "browser-use"
Requires-Dist: anyio>=4.9.0; extra == "browser-use"
Requires-Dist: httpx>=0.28.1; extra == "browser-use"
Requires-Dist: cloudpickle>=3.1.1; extra == "browser-use"
Requires-Dist: markdown-pdf<2.0,>=1.0; extra == "browser-use"
Provides-Extra: all
Requires-Dist: noesium[agents,all-llm,browser-use,postgres,tools,weaviate]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.2; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: autoflake>=2.3.1; extra == "dev"
Requires-Dist: flake8>=7.3.0; extra == "dev"
Requires-Dist: networkx>=3.5; extra == "dev"
Requires-Dist: pandas>=2.0.0; extra == "dev"
Dynamic: license-file

<div align="center">
  <img src="docs/logos/noesium-logo-light.png" alt="Noesium Logo" width="350" />

  #

  [![Python](https://img.shields.io/pypi/pyversions/noesium)](https://pypi.org/project/noesium/)
  [![PyPI Version](https://img.shields.io/pypi/v/noesium)](https://pypi.org/project/noesium/)
  [![License](https://img.shields.io/github/license/mirasoth/noesium)](https://github.com/mirasoth/noesium/blob/main/LICENSE)
  [![GitHub Stars](https://img.shields.io/github/stars/mirasoth/noesium)](https://github.com/mirasoth/noesium)

</div>

**Noesium** is a computation-driven cognitive agentic framework. Use it as a **ready-to-run multi-agent system** (NoeAgent plus subagents) or as a **foundation** to build custom agents with core abstractions and 17+ toolkits.

## Design Philosophy

Noesium follows an **event-sourced multi-agent kernel architecture** for durability, replayability, and distributed coordination:

- **Single execution authority** — One Agent Kernel per agent; all reasoning, planning, tool use, and delegation happen inside it. No external layer mutates agent state.
- **Event-sourced state** — State is derived from an append-only event log. Enables replay, deterministic reconstruction, audit, and crash recovery.
- **Delegation via events** — Agents publish task events to capability topics; subscribers process them. Loose coupling, capability-based coordination.
- **Separation of concerns** — Cognition (Kernel), transport (Event Bus), persistence (Event Store), memory (Projection), routing (Topic subscriptions).

Goals: long-running autonomous agents, durable/resumable execution, multi-agent collaboration, horizontal scalability.

## Architecture

```mermaid
flowchart TB
  subgraph framework [Framework]
    core[core: agent base, llm, toolify, memory, event, vector_store]
    toolkits[toolkits: 17+ built-in]
  end
  subgraph builtin [Built-in multi-agent system]
    noeAgent[NoeAgent]
    subagents[BrowserUseAgent, TacitusAgent, AskuraAgent]
  end
  framework --> builtin
  framework -.-> yourAgents[Your custom agents]
```

- **Framework** — Core modules (`agent` base classes, `llm`, `toolify`, `memory`, `event`, `vector_store`) and 17+ toolkits provide the agentic building blocks.
- **Built-in multi-agent system** — NoeAgent (orchestrator) and subagents (BrowserUseAgent, TacitusAgent, AskuraAgent) are a reference implementation and directly usable. See [AGENTS.md](AGENTS.md) for details.

## Install

```bash
pip install -U noesium
```

Recommended for full features:

```bash
pip install noesium[all]
```

Optional extras:

```bash
pip install noesium[llm]             # OpenAI, LiteLLM, Instructor
pip install noesium[local-llm]       # Ollama, LlamaCPP
pip install noesium[agents]          # LangChain, LangGraph
pip install noesium[tools]           # 17+ toolkits
pip install noesium[browser-use]     # Browser automation
```

Use `uv run` for scripts when developing with the repo.

## Quick Start

### 1. Common user — NoeAgent

**Library:**

```python
import asyncio
from noesium import NoeAgent

async def main():
    agent = NoeAgent()
    result = await agent.arun("What are the latest developments in quantum computing?")
    print(result)

asyncio.run(main())
```

**TUI:**

```bash
python -m noesium.noeagent.tui
```

Full NoeAgent options, streaming, subagents, and config: [docs/noeagent_guide.md](docs/noeagent_guide.md).

### 2. Developer — Framework

Build a custom agent on the framework:

```python
from noesium.core.agent import BaseGraphicAgent
from noesium.core.llm import get_llm_client
from noesium.core.toolify import get_toolkit

class MyAgent(BaseGraphicAgent):
    def __init__(self, llm_client=None):
        super().__init__(llm_client or get_llm_client())

    def build_graph(self):
        # Define your LangGraph workflow
        pass

agent = MyAgent()
result = await agent.run("Your task")
```

For full framework usage, custom agents, and toolkits: **[docs/dev_guide.md](docs/dev_guide.md)**.

## Environment variables

```bash
export NOE_LLM_PROVIDER="openai"   # or openrouter, ollama, llamacpp
export OPENAI_API_KEY="sk-..."
export SERPER_API_KEY="..."        # for search toolkit
```

## License and support

- **License** — MIT.
- **Documentation** — [AGENTS.md](AGENTS.md), [docs/dev_guide.md](docs/dev_guide.md), [docs/specs/](docs/specs/), [examples/](examples/).
- **Issues and repo** — [GitHub](https://github.com/mirasoth/noesium).
