Metadata-Version: 2.4
Name: noesium
Version: 0.3.5
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
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
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"
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>=8.4.2; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.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: ruff>=0.8.0; extra == "dev"
Requires-Dist: networkx>=3.5; extra == "dev"
Requires-Dist: pandas>=2.0.0; extra == "dev"

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

  #

  [![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)

</div>

# Noesium Framework

**A computation-driven cognitive agentic framework** for building custom autonomous systems with event-sourced architecture, reusable subagents, and 17+ toolkits.

## Overview

Noesium provides the foundational layer for building AI agents with:

- **Event-Sourced Architecture**: Durable, replayable agent execution
- **Multi-Agent Kernel**: Single execution authority for all agent operations
- **Built-in Toolkits**: 17+ production-ready tools (bash, search, Python execution, etc.)
- **Flexible LLM Support**: OpenAI, Anthropic, Google, Ollama, and more
- **Subagent Coordination**: Delegate specialized tasks to subagents
- **Memory Management**: Ephemeral and persistent memory systems

## Installation

```bash
# Basic installation
pip install noesium

# Full installation with all features
pip install noesium[all]

# Specific feature sets
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
pip install noesium[postgres]        # PostgreSQL vector store
pip install noesium[weaviate]        # Weaviate vector store
```

## Quick Start

### 1. Configure Environment

```bash
export NOESIUM_LLM_PROVIDER="openai"  # Required
export OPENAI_API_KEY="sk-..."        # Required for OpenAI
```

### 2. Use the LLM Client

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

# Create client
client = get_llm_client()

# Basic completion
response = client.completion([
    {"role": "user", "content": "Hello, how are you?"}
])

# Structured output with Pydantic
from pydantic import BaseModel

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

result = client.structured_completion(
    [{"role": "user", "content": "What is 2+2?"}],
    response_model=Answer
)
```

### 3. Create a Custom Agent

```python
from noesium.core.agent import BaseGraphicAgent
from noesium.core.llm import get_llm_client
from langgraph.graph import StateGraph, END

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

    def build_graph(self):
        workflow = StateGraph(AgentState)
        workflow.add_node("think", self.think_node)
        workflow.add_node("act", self.act_node)
        workflow.set_entry_point("think")
        workflow.add_edge("think", "act")
        workflow.add_edge("act", END)
        return workflow.compile()

    async def think_node(self, state):
        # Your thinking logic
        return state

    async def act_node(self, state):
        # Your action logic
        return state

# Use the agent
agent = MyAgent()
result = await agent.run("Complete this task")
```

### 4. Use Toolkits

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

# Bash toolkit - file operations
bash = get_toolkit("bash")
files = await bash.list_directory(".")

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

# Python executor - code execution
python_exec = get_toolkit("python_executor")
result = await python_exec.execute_code("print('Hello, World!')")
```

## Architecture

### Event-Sourced Multi-Agent Kernel

```
┌──────────────────────────────────────────┐
│            Event Bus                     │
│      (Topic-based routing)               │
└────────────┬─────────────────────────────┘
             │
    ┌────────┴────────┐
    │                 │
┌───▼────┐       ┌───▼────┐
│ Agent  │       │ Agent  │
│ Kernel │       │ Kernel │
└───┬────┘       └───┬────┘
    │                 │
┌───▼────┐       ┌───▼────┐
│ Event  │       │ Event  │
│ Store  │       │ Store  │
└────────┘       └────────┘
```

**Key Principles:**

- **Single execution authority**: All reasoning happens inside the Agent Kernel
- **Event-sourced state**: State derived from append-only event log
- **Delegation via events**: Agents coordinate through event topics
- **Durability**: Crash recovery and replay capability

### Framework Layers

```
┌──────────────────────────────────────┐
│        Subagents Layer               │  Reusable agent implementations
│  (BrowserUseAgent, Tacitus, etc.)    │
├──────────────────────────────────────┤
│        Toolkits Layer                │  17+ built-in tools
│  (bash, search, python_executor...)  │
├──────────────────────────────────────┤
│          Core Layer                  │  Framework primitives
│  (agents, tools, events, memory,     │
│   LLM, config, kernel)               │
└──────────────────────────────────────┘
```

## Built-in Toolkits

| Toolkit | Name | Description | Key Features |
|---------|------|-------------|--------------|
| Bash | `bash` | File operations & shell | List, read, write, execute |
| Python Executor | `python_executor` | Execute Python code | Sandbox, timeout, output capture |
| Search | `search` | Web search | Google, Tavily, DuckDuckGo |
| ArXiv | `arxiv` | Academic papers | Search, download, parse |
| Memory | `memory` | Persistent memory | Read, write, list, delete |
| Document | `document` | Document processing | PDF, Word, Excel |
| Image | `image` | Image processing | Resize, convert, analyze |
| Audio | `audio` | Audio processing | Transcription, synthesis |
| Wikipedia | `wikipedia` | Wikipedia search | Search, retrieve articles |
| GitHub | `github` | GitHub operations | Repos, issues, PRs |

## Agent Types

| Type | Description | Use Case |
|------|-------------|----------|
| `BaseAgent` | Abstract base with LLM and token tracking | Foundation for all agents |
| `BaseGraphicAgent` | LangGraph-based with state management | Complex multi-step workflows |
| `AskuraAgent` | Conversation agent with sessions | Interactive chat applications |
| `TacitusAgent` | Research agent with source management | Information gathering & synthesis |
| `BaseSubagentRuntime` | Reusable subagent components | Modular capability providers |

## LLM Providers

Support for multiple LLM providers:

- **OpenAI**: GPT-4, GPT-3.5, GPT-4 Vision
- **Anthropic**: Claude 3.5 Sonnet, Claude 3 Opus
- **Google**: Gemini Pro, Gemini Pro Vision
- **OpenRouter**: Unified API for multiple providers
- **LiteLLM**: 100+ LLM APIs
- **Ollama**: Local models (Llama 3, Mistral, etc.)
- **LlamaCPP**: Local GGUF models

## Memory System

Multi-tier memory architecture:

- **Working Memory**: In-memory, session-based
- **Durable Memory**: Persistent, database-backed
- **Semantic Memory**: Vector embeddings for retrieval

```python
from noesium.core.memory import MemoryManager

# Create memory manager
memory = MemoryManager(config={"provider": "ephemeral"})

# Write memory
await memory.write_memory(
    slot="research_notes",
    content="Key findings...",
    metadata={"topic": "AI"}
)

# Read memory
content = await memory.read_memory("research_notes")
```

## Event System

Topic-based event coordination:

```python
from noesium.core.event import EventBus, Event

# Create event bus
bus = EventBus()

# Subscribe to events
async def handle_task(event: Event):
    print(f"Received: {event.data}")

bus.subscribe("analysis", handle_task)

# Publish events
event = Event(
    type="TaskRequested",
    topic="analysis",
    data={"task": "Analyze data"}
)
await bus.publish(event)
```

## Configuration

### Environment Variables

```bash
# LLM Configuration
export NOESIUM_LLM_PROVIDER="openai"
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Toolkit Configuration
export SERPER_API_KEY="..."      # Web search
export JINA_API_KEY="..."        # Search embeddings
```

### Configuration File

Create `noesium.toml`:

```toml
[llm]
provider = "openai"
model = "gpt-4o"
temperature = 0.7

[agent]
max_iterations = 25
max_tool_calls_per_step = 5

[tools]
enabled_toolkits = ["bash", "search", "python_executor"]

[memory]
provider = "ephemeral"

[tools.toolkit_configs.bash]
timeout = 600
shell = "/bin/zsh"
```

## Development

### Setup

```bash
# Clone the workspace
git clone https://github.com/mirasoth/noesium.git
cd noesium

# Install with dev dependencies
make setup
```

### Testing

```bash
# Run tests
make test-noesium

# Run with coverage
make test-coverage
```

### Code Quality

```bash
make quality    # Run all quality checks
make format     # Format code
make lint       # Run linters
```

## Documentation

- **[Quick Guide](../docs/user_guides/quick_guide_noesium.md)** - Get started quickly
- **[Developer Guide](../docs/user_guides/dev_guide.md)** - Framework development
- **[Specifications](../docs/specs/)** - Technical RFCs
- **[Examples](../examples/)** - Usage examples

## Requirements

- Python >= 3.11
- For specific features, see optional dependencies above

## Applications Built on Noesium

- **[NoeAgent](../noeagent/)** - Multi-agent system implementation
- **[Voyager](../voyager/)** - 24/7 digital companion

## License

MIT License - see [LICENSE](../LICENSE) for details.

## Contributing

See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.

## Support

- **Issues**: [GitHub Issues](https://github.com/mirasoth/noesium/issues)
- **PyPI**: [noesium](https://pypi.org/project/noesium/)
