noesium 0.1.0__tar.gz → 0.2.1__tar.gz

{noesium-0.1.0 → noesium-0.2.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Xiaming Chen
+Copyright (c) 2025, Mirasoth Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

noesium-0.2.1/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: noesium
+Version: 0.2.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: 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
+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: all
+Requires-Dist: noesium[agents,ai-providers-all,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"
+Dynamic: license-file
+
+# Noesium
+
+[![CI](https://github.com/mirasoth/noesium/actions/workflows/ci.yml/badge.svg)](https://github.com/mirasoth/noesium/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/noesium.svg)](https://pypi.org/project/noesium/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/mirasoth/noesium)
+
+Project Noesium is an initiative to develop a computation-driven, cognitive agentic system. This repo contains the foundational abstractions (Agent, Memory, Tool, Goal, Orchestration, and more) along with essential modules such as LLM clients, logging, message buses, model routing, and observability. For the underlying philosophy, refer to my talk on MAS ([link](https://github.com/caesar0301/mas-talk-2508/blob/master/mas-talk-xmingc.pdf)).
+
+## Installation
+
+```bash
+pip install -U noesium
+```
+
+## Core Modules
+
+| Module | Description |
+|--------|-------------|
+| **LLM Integration** (`noesium.core.llm`) | Multi-provider support (OpenAI, OpenRouter, Ollama, LlamaCPP, LiteLLM), dynamic routing, token tracking |
+| **Goal Management** (`noesium.core.goalith`) | LLM-based goal decomposition, DAG-based goal graph, dependency tracking |
+| **Tool Management** (`noesium.core.toolify`) | Tool registry, MCP integration, 17+ built-in toolkits |
+| **Memory** (`noesium.core.memory`) | MemU integration, embedding-based retrieval, multi-category storage |
+| **Vector Store** (`noesium.core.vector_store`) | PGVector and Weaviate support, semantic search |
+| **Message Bus** (`noesium.core.msgbus`) | Event-driven architecture, watchdog patterns |
+| **Routing** (`noesium.core.routing`) | Dynamic complexity-based model selection |
+| **Tracing** (`noesium.core.tracing`) | Token usage monitoring, Opik integration |
+
+## Built-in Agents
+
+- **AskuraAgent** - Conversational agent for collecting semi-structured information via human-in-the-loop workflows
+- **SearchAgent** - Web search with query polishing, multi-engine support, and optional content crawling
+- **DeepResearchAgent** - Iterative research with LLM-powered reflection and citation generation
+- **MemoryAgent** - Memory management with categorization, embedding search, and memory linking
+
+## 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)
+```
+
+### Tool Management
+
+```python
+from noesium.core.toolify import BaseToolkit, ToolkitConfig, ToolkitRegistry, register_toolkit
+
+@register_toolkit("calculator")
+class CalculatorToolkit(BaseToolkit):
+    def get_tools_map(self):
+        return {"add": self.add, "multiply": self.multiply}
+
+    def add(self, a: float, b: float) -> float:
+        return a + b
+
+    def multiply(self, a: float, b: float) -> float:
+        return a * b
+
+# Use toolkit
+config = ToolkitConfig(name="calculator")
+calc = ToolkitRegistry.create_toolkit("calculator", config)
+result = calc.call_tool("add", a=5, b=3)
+```
+
+### Goal Decomposition
+
+```python
+from noesium.core.goalith.goalgraph.node import GoalNode
+from noesium.core.goalith.goalgraph.graph import GoalGraph
+from noesium.core.goalith.decomposer import LLMDecomposer
+
+# Create and decompose a goal
+goal = GoalNode(description="Plan a product launch", priority=8.0)
+graph = GoalGraph()
+graph.add_node(goal)
+
+decomposer = LLMDecomposer()
+subgoals = decomposer.decompose(goal, context={"budget": "$50,000"})
+```
+
+### Search Agent
+
+```python
+from noesium.agents.search import SearchAgent, SearchConfig
+
+config = SearchConfig(
+    polish_query=True,
+    search_engines=["tavily"],
+    max_results_per_engine=5
+)
+agent = SearchAgent(config=config)
+results = await agent.search("latest developments in quantum computing")
+```
+
+### Deep Research Agent
+
+```python
+from noesium.agents.deep_research import DeepResearchAgent, DeepResearchConfig
+
+config = DeepResearchConfig(
+    number_of_initial_queries=3,
+    max_research_loops=3,
+    web_search_citation_enabled=True
+)
+agent = DeepResearchAgent(config=config)
+result = await agent.research("What are the implications of AI on healthcare?")
+```
+
+## Environment Variables
+
+```bash
+# LLM Providers
+export NOESIUM_LLM_PROVIDER="openai"
+export OPENAI_API_KEY="sk-..."
+export OPENROUTER_API_KEY="sk-..."
+export OLLAMA_BASE_URL="http://localhost:11434"
+export LLAMACPP_MODEL_PATH="/path/to/model.gguf"
+
+# Vector Store (PostgreSQL)
+export POSTGRES_HOST="localhost"
+export POSTGRES_PORT="5432"
+export POSTGRES_DB="vectordb"
+export POSTGRES_USER="postgres"
+export POSTGRES_PASSWORD="postgres"
+
+# Search Tools
+export SERPER_API_KEY="..."
+export JINA_API_KEY="..."
+```
+
+## Examples
+
+See the `examples/` directory for comprehensive usage examples:
+
+- `examples/agents/` - Agent demos (Askura, Search, DeepResearch)
+- `examples/llm/` - LLM provider examples and token tracking
+- `examples/goals/` - Goal decomposition patterns
+- `examples/memory/` - Memory agent operations
+- `examples/tools/` - Toolkit demonstrations
+- `examples/vector_store/` - PGVector and Weaviate usage
+
+## Documentation
+
+- **Design Specifications**: `specs/` directory contains RFCs for system architecture
+- **Agent Details**: See `AGENTS.md` for comprehensive agent and toolkit documentation
+- **Toolify System**: `noesium/core/toolify/README.md`
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

noesium-0.2.1/README.md

@@ -0,0 +1,166 @@
+# Noesium
+
+[![CI](https://github.com/mirasoth/noesium/actions/workflows/ci.yml/badge.svg)](https://github.com/mirasoth/noesium/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/noesium.svg)](https://pypi.org/project/noesium/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/mirasoth/noesium)
+
+Project Noesium is an initiative to develop a computation-driven, cognitive agentic system. This repo contains the foundational abstractions (Agent, Memory, Tool, Goal, Orchestration, and more) along with essential modules such as LLM clients, logging, message buses, model routing, and observability. For the underlying philosophy, refer to my talk on MAS ([link](https://github.com/caesar0301/mas-talk-2508/blob/master/mas-talk-xmingc.pdf)).
+
+## Installation
+
+```bash
+pip install -U noesium
+```
+
+## Core Modules
+
+| Module | Description |
+|--------|-------------|
+| **LLM Integration** (`noesium.core.llm`) | Multi-provider support (OpenAI, OpenRouter, Ollama, LlamaCPP, LiteLLM), dynamic routing, token tracking |
+| **Goal Management** (`noesium.core.goalith`) | LLM-based goal decomposition, DAG-based goal graph, dependency tracking |
+| **Tool Management** (`noesium.core.toolify`) | Tool registry, MCP integration, 17+ built-in toolkits |
+| **Memory** (`noesium.core.memory`) | MemU integration, embedding-based retrieval, multi-category storage |
+| **Vector Store** (`noesium.core.vector_store`) | PGVector and Weaviate support, semantic search |
+| **Message Bus** (`noesium.core.msgbus`) | Event-driven architecture, watchdog patterns |
+| **Routing** (`noesium.core.routing`) | Dynamic complexity-based model selection |
+| **Tracing** (`noesium.core.tracing`) | Token usage monitoring, Opik integration |
+
+## Built-in Agents
+
+- **AskuraAgent** - Conversational agent for collecting semi-structured information via human-in-the-loop workflows
+- **SearchAgent** - Web search with query polishing, multi-engine support, and optional content crawling
+- **DeepResearchAgent** - Iterative research with LLM-powered reflection and citation generation
+- **MemoryAgent** - Memory management with categorization, embedding search, and memory linking
+
+## 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)
+```
+
+### Tool Management
+
+```python
+from noesium.core.toolify import BaseToolkit, ToolkitConfig, ToolkitRegistry, register_toolkit
+
+@register_toolkit("calculator")
+class CalculatorToolkit(BaseToolkit):
+    def get_tools_map(self):
+        return {"add": self.add, "multiply": self.multiply}
+
+    def add(self, a: float, b: float) -> float:
+        return a + b
+
+    def multiply(self, a: float, b: float) -> float:
+        return a * b
+
+# Use toolkit
+config = ToolkitConfig(name="calculator")
+calc = ToolkitRegistry.create_toolkit("calculator", config)
+result = calc.call_tool("add", a=5, b=3)
+```
+
+### Goal Decomposition
+
+```python
+from noesium.core.goalith.goalgraph.node import GoalNode
+from noesium.core.goalith.goalgraph.graph import GoalGraph
+from noesium.core.goalith.decomposer import LLMDecomposer
+
+# Create and decompose a goal
+goal = GoalNode(description="Plan a product launch", priority=8.0)
+graph = GoalGraph()
+graph.add_node(goal)
+
+decomposer = LLMDecomposer()
+subgoals = decomposer.decompose(goal, context={"budget": "$50,000"})
+```
+
+### Search Agent
+
+```python
+from noesium.agents.search import SearchAgent, SearchConfig
+
+config = SearchConfig(
+    polish_query=True,
+    search_engines=["tavily"],
+    max_results_per_engine=5
+)
+agent = SearchAgent(config=config)
+results = await agent.search("latest developments in quantum computing")
+```
+
+### Deep Research Agent
+
+```python
+from noesium.agents.deep_research import DeepResearchAgent, DeepResearchConfig
+
+config = DeepResearchConfig(
+    number_of_initial_queries=3,
+    max_research_loops=3,
+    web_search_citation_enabled=True
+)
+agent = DeepResearchAgent(config=config)
+result = await agent.research("What are the implications of AI on healthcare?")
+```
+
+## Environment Variables
+
+```bash
+# LLM Providers
+export NOESIUM_LLM_PROVIDER="openai"
+export OPENAI_API_KEY="sk-..."
+export OPENROUTER_API_KEY="sk-..."
+export OLLAMA_BASE_URL="http://localhost:11434"
+export LLAMACPP_MODEL_PATH="/path/to/model.gguf"
+
+# Vector Store (PostgreSQL)
+export POSTGRES_HOST="localhost"
+export POSTGRES_PORT="5432"
+export POSTGRES_DB="vectordb"
+export POSTGRES_USER="postgres"
+export POSTGRES_PASSWORD="postgres"
+
+# Search Tools
+export SERPER_API_KEY="..."
+export JINA_API_KEY="..."
+```
+
+## Examples
+
+See the `examples/` directory for comprehensive usage examples:
+
+- `examples/agents/` - Agent demos (Askura, Search, DeepResearch)
+- `examples/llm/` - LLM provider examples and token tracking
+- `examples/goals/` - Goal decomposition patterns
+- `examples/memory/` - Memory agent operations
+- `examples/tools/` - Toolkit demonstrations
+- `examples/vector_store/` - PGVector and Weaviate usage
+
+## Documentation
+
+- **Design Specifications**: `specs/` directory contains RFCs for system architecture
+- **Agent Details**: See `AGENTS.md` for comprehensive agent and toolkit documentation
+- **Toolify System**: `noesium/core/toolify/README.md`
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

noesium-0.2.1/noesium/agents/askura_agent/__init__.py

@@ -0,0 +1,22 @@
+"""
+AskuraAgent - A general-purpose dynamic conversation agent.
+
+AskuraAgent provides a flexible, configurable framework for human-in-the-loop
+conversations that adapt to different user communication styles and dynamically
+collect required information through natural conversation flow.
+"""
+
+from .askura_agent import AskuraAgent
+from .conversation import ConversationManager
+from .extractor import InformationExtractor
+from .models import AskuraConfig, AskuraResponse, AskuraState, InformationSlot
+
+__all__ = [
+    "AskuraAgent",
+    "AskuraConfig",
+    "AskuraState",
+    "AskuraResponse",
+    "ConversationManager",
+    "InformationExtractor",
+    "InformationSlot",
+]