Metadata-Version: 2.4
Name: noesium
Version: 0.3.1
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: ai-providers-all
Requires-Dist: noesium[aliyun,google,llm,local-llm]; extra == "ai-providers-all"
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.0.1; 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"
Provides-Extra: all
Requires-Dist: noesium[agents,ai-providers-all,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 providing foundational abstractions for building autonomous AI agents with planning, memory, tools, and orchestration capabilities.

## Design Philosophy

Noesium is built on an **Event-Sourced Multi-Agent Kernel Architecture** that prioritizes durability, replayability, and distributed coordination. The core principles include:

### Single Execution Authority
Each agent contains exactly one execution authority: the Agent Kernel. All reasoning, planning, branching, retries, tool invocation, and delegation logic occur inside this kernel. No external orchestration layer is permitted to mutate agent state.

### Event-Sourced State
State is not stored as mutable objects. Instead, every state transition emits an event, the event log is the source of truth, and current state is a projection derived from event history. This ensures replayability, deterministic reconstruction, auditable cognition, and crash recovery.

### Delegation via Events
Delegation is modeled as event emission, not direct invocation. An agent expresses intent by publishing a task event to a capability topic. Any agent subscribed to that topic may process the task, enforcing loose coupling and capability-based coordination.

### Separation of Concerns
- **Cognition** → Agent Kernel
- **Transport** → Event Bus
- **Persistence** → Event Store
- **Memory Projection** → Projection Layer
- **Capability Routing** → Topic Subscriptions

### Architectural Goals
The system supports long-running autonomous agents, infinite reasoning loops, durable/resumable execution, distributed multi-agent collaboration, deterministic replayability, horizontal scalability, and explicit separation of cognition, transport, and persistence.

## Installation

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

### Optional Dependencies

```bash
# Recommended: all features
pip install noesium[all]

# AI providers
pip install noesium[llm]             # OpenAI, LiteLLM, Instructor
pip install noesium[local-llm]       # Ollama, LlamaCPP
pip install noesium[ai-providers-all] # All AI providers

# Frameworks
pip install noesium[agents]          # LangChain + Bubus

# Tools & data
pip install noesium[tools]           # 17+ toolkits
pip install noesium[datascience]     # Pandas, NetworkX
pip install noesium[browser-use]     # Browser automation
```

## Quick Start

### LLM Client

```python
from noesium.core.llm import get_llm_client

# Create client (supports openai, openrouter, ollama, llamacpp)
client = get_llm_client(provider="openai", api_key="sk-...")

# Chat completion
response = client.completion([{"role": "user", "content": "Hello!"}])

# Structured output
from pydantic import BaseModel

class Answer(BaseModel):
    text: str
    confidence: float

client = get_llm_client(provider="openai", structured_output=True)
result = client.structured_completion(messages, Answer)
```

### Build an Agent

```python
from noesium.core.agent.base import BaseGraphicAgent
from noesium.core.llm import get_llm_client

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

    def build_graph(self):
        # Define your agent's workflow graph
        pass

agent = MyAgent()
result = await agent.run("What is the meaning of life?")
```

### Use Toolkits

```python
from noesium.core.toolify import get_toolkit, ToolkitConfig

# Search toolkit
search_config = ToolkitConfig(name="search", config={"SERPER_API_KEY": "..."})
search = get_toolkit("search", search_config)
results = await search.search_google_api("Python async programming")

# Bash toolkit
bash = get_toolkit("bash")
files = await bash.list_directory(".")
```

## Core Modules

| Module | Description |
|--------|-------------|
| **Agents** (`noesium.core.agent`) | BaseAgent, BaseGraphicAgent, BaseHitlAgent, BaseResearcher |
| **LLM** (`noesium.core.llm`) | Multi-provider support, structured output, token tracking |
| **Toolify** (`noesium.core.toolify`) | Unified tool system with 17+ built-in toolkits |
| **Memory** (`noesium.core.memory`) | Multi-tier memory with semantic search |
| **Event** (`noesium.core.event`) | Domain events, message bus, tracing |
| **Vector Store** (`noesium.core.vector_store`) | PGVector, Weaviate support |

## Built-in Agents

- **Noe** - Autonomous research assistant with planning, execution, reflection cycles
- **BrowserUseAgent** - Web automation with DOM interaction and code execution
- **TacitusAgent** - Advanced research agent with iterative query generation, web search, reflection, and answer synthesis

## Built-in Toolkits

Search, Bash, Memory, Python Executor, ArXiv, Audio, Document, File Edit, GitHub, Gmail, Image, Tabular Data, Video, Wikipedia, and more.

See [AGENTS.md](AGENTS.md) for detailed documentation.

## Environment Variables

```bash
# LLM Provider
export NOESIUM_LLM_PROVIDER="openai"
export OPENAI_API_KEY="sk-..."

# Search
export SERPER_API_KEY="..."
```

## Documentation

- **[AGENTS.md](AGENTS.md)** - Detailed agent and toolkit documentation
- **`specs/`** - Design specifications (RFCs)
- **`examples/`** - Usage examples

## License

MIT License
