Metadata-Version: 2.3
Name: cogents-core
Version: 0.1.3
Summary: Towards a cognitive agentic framework
License: MIT
Keywords: agents,multi-agent system,cognition,artificial intelligence
Author: Xiaming Chen
Author-email: chenxm35@gmail.com
Maintainer: Xiaming Chen
Maintainer-email: chenxm35@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: bubus (>=1.5.6,<2.0.0)
Requires-Dist: colorlog (>=6.8.0,<7.0.0)
Requires-Dist: deprecated (>=1.2.18,<2.0.0)
Requires-Dist: google-genai (>=1.5.0,<2.0.0)
Requires-Dist: huggingface-hub (>=0.34.4,<0.35.0)
Requires-Dist: instructor (>=1.10.0,<2.0.0)
Requires-Dist: langchain-core (>=0.3.72,<0.4.0)
Requires-Dist: langchain-ollama (>=0.2.0,<0.3.0)
Requires-Dist: langchain-text-splitters (>=0.3.0,<0.4.0)
Requires-Dist: langgraph (>=0.5.4,<0.6.0)
Requires-Dist: litellm (>=1.0.0,<2.0.0)
Requires-Dist: llama-cpp-python (>=0.3.16,<0.4.0)
Requires-Dist: mcp (>=1.0.0,<2.0.0)
Requires-Dist: networkx (>=3.5,<4.0)
Requires-Dist: ollama (>=0.5.3,<0.6.0)
Requires-Dist: openai (>=1.0.0,<2.0.0)
Requires-Dist: pydantic (>=2.0.0,<3.0.0)
Requires-Dist: pygraphviz (>=1.14,<2.0)
Requires-Dist: python-dotenv (>=1.1.1,<2.0.0)
Requires-Dist: requests (>=2.31.0,<3.0.0)
Requires-Dist: typing-extensions (>=4.8.0,<5.0.0)
Project-URL: Documentation, https://cogents-core.readthedocs.io/
Project-URL: Homepage, https://github.com/mirasurf/cogents-core
Project-URL: Repository, https://github.com/mirasurf/cogents-core
Description-Content-Type: text/markdown

# Cogents-core

[![CI](https://github.com/mirasurf/cogents-core/actions/workflows/ci.yml/badge.svg)](https://github.com/mirasurf/cogents-core/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/cogents-core.svg)](https://pypi.org/project/cogents-core/)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/mirasurf/cogents-core)

A comprehensive collection of essential building blocks for constructing cognitive multi-agent systems (MAS). Rather than building a full agent framework, Cogents provides a lightweight repository of key components designed to bridge the final mile in MAS development. Our philosophy focuses on modular, composable components that can be easily integrated into existing systems or used to build new ones from the ground up. For the underlying philosophy, refer to my talk on MAS ([link](https://github.com/caesar0301/mas-talk-2508/blob/master/mas-talk-xmingc.pdf)).

## Core Modules

Cogents offers a comprehensive set of modules for creating intelligent agent-based applications:

### LLM Integration & Management
- **Multi-model support**: OpenAI, Google GenAI (via OpenRouter), Ollama, and LlamaCPP
- **Advanced routing**: Dynamic complexity-based and self-assessment routing strategies
- **Tracing & monitoring**: Built-in token tracking and Opik tracing integration
- **Extensible architecture**: Easy to add new LLM providers

### Goal Management & Planning
- **Goal decomposition**: LLM-based and callable goal decomposition strategies
- **Conflict detection**: Automated goal conflict identification and resolution
- **Replanning**: Dynamic goal replanning capabilities

### Tool Management
- **Tool registry**: Centralized tool registration and management
- **Execution engine**: Robust tool execution with error handling
- **Repository system**: Organized tool storage and retrieval

### Memory Management
- Under development

### Orchestration
- Under development


## Project Structure

```
cogents/core
├── base/            # Base classes and models
├── goalith/         # Goal management and planning
├── memory/          # Memory management (on plan)
├── orchestrix/      # Global orchestration (on plan)
└── toolify/         # Tool management and execution
```

## Creating a New Agent

### From Base Classes
Start with the base agent classes in `cogents_core.base` to create custom agents with full control over behavior and capabilities.

#### Base Agent Class Hierarchy

```
BaseAgent (abstract)
├── Core functionality
│   ├── LLM client management
│   ├── Token usage tracking
│   ├── Logging capabilities
│   └── Configuration management
│
├── BaseGraphicAgent (abstract)
│   ├── LangGraph integration
│   ├── State management
│   ├── Graph visualization
│   └── Error handling patterns
│   │
│   ├── BaseConversationAgent (abstract)
│   │   ├── Session management
│   │   ├── Message handling
│   │   ├── Conversation state
│   │   └── Response generation
│   │
│   └── BaseResearcher (abstract)
│       ├── Research workflow
│       ├── Source management
│       ├── Query generation
│       └── Result compilation
│           └── Uses ResearchOutput model
│               ├── content: str
│               ├── sources: List[Dict]
│               ├── summary: str
│               └── timestamp: datetime
```

**Key Inheritance Paths:**
- **BaseAgent**: Core functionality (LLM client, token tracking, logging)
- **BaseGraphicAgent**: LangGraph integration and visualization
- **BaseConversationAgent**: Session management and conversation patterns
- **BaseResearcher**: Research workflow and structured output patterns

### From Existing Agents
Use well-constructed agents like Seekra Agent as templates:

```python
from cogents_core.agents.seekra_agent import SeekraAgent

# Extend Seekra Agent for custom research tasks
class CustomResearchAgent(SeekraAgent):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # Add custom functionality
        
    def custom_research_method(self):
        # Implement custom research logic
        pass
```

## Install

```
pip install -U cogents-core
```

## License

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

