# Cogents
[](https://github.com/caesar0301/cogents/actions/workflows/ci.yml)
[](https://pypi.org/project/cogents/)
[](https://deepwiki.com/caesar0301/cogents)
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
### Extensible Resources & Capabilities
- **Web search**: Tavily and Google AI Search integration
- **Vector stores**: Weaviate and PostgreSQL with pgvector support
- **Semantic search**: Integrated semantic web search with document processing
- **Voice processing**: Smart voice transcription and processing features
### 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
### Agent Gallery
- **Askura Agent**: Advanced conversation and memory management agent
- **Seekra Agent**: Research-focused agent with web search capabilities
- **Mem Agent**: Memory-focused agent (coming soon)
- **Cogito Agent**: Cognitive reasoning agent (coming soon)
## Project Structure
```
cogents/
├── agents/ # Agent implementations
├── base/ # Base classes and models
├── common/ # Shared utilities and LLM integrations
├── goalith/ # Goal management and planning
├── memory/ # Memory management (on plan)
├── orchestrix/ # Global orchestration (on plan)
├── resources/ # External service integrations
└── toolify/ # Tool management and execution
```
## Creating a New Agent
### From Base Classes
Start with the base agent classes in `cogents.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.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
```
## Documentation
For detailed documentation, visit: https://cogents.readthedocs.io/ (under construction)
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Acknowledgment
- Tencent [Youtu-agent](https://github.com/Tencent/Youtu-agent) toolkits integration.
Raw data
{
"_id": null,
"home_page": null,
"name": "cogents",
"maintainer": "xming",
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": "chenxm35@gmail.com",
"keywords": "agentic, multi-agent, framework, cognition, artificial intelligence",
"author": "xming",
"author_email": "chenxm35@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b9/ab/4c46a3ee31f3423ef99ae9c4ea40610c3a109371170f56ccb68be3934a6c/cogents-0.0.16.tar.gz",
"platform": null,
"description": "# Cogents\n\n[](https://github.com/caesar0301/cogents/actions/workflows/ci.yml)\n[](https://pypi.org/project/cogents/)\n[](https://deepwiki.com/caesar0301/cogents)\n\nA 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)).\n\n## Core Modules\n\nCogents offers a comprehensive set of modules for creating intelligent agent-based applications:\n\n### LLM Integration & Management\n- **Multi-model support**: OpenAI, Google GenAI (via OpenRouter), Ollama, and LlamaCPP\n- **Advanced routing**: Dynamic complexity-based and self-assessment routing strategies\n- **Tracing & monitoring**: Built-in token tracking and Opik tracing integration\n- **Extensible architecture**: Easy to add new LLM providers\n\n### Extensible Resources & Capabilities\n- **Web search**: Tavily and Google AI Search integration\n- **Vector stores**: Weaviate and PostgreSQL with pgvector support\n- **Semantic search**: Integrated semantic web search with document processing\n- **Voice processing**: Smart voice transcription and processing features\n\n### Goal Management & Planning\n- **Goal decomposition**: LLM-based and callable goal decomposition strategies\n- **Conflict detection**: Automated goal conflict identification and resolution\n- **Replanning**: Dynamic goal replanning capabilities\n\n### Tool Management\n- **Tool registry**: Centralized tool registration and management\n- **Execution engine**: Robust tool execution with error handling\n- **Repository system**: Organized tool storage and retrieval\n\n### Agent Gallery\n- **Askura Agent**: Advanced conversation and memory management agent\n- **Seekra Agent**: Research-focused agent with web search capabilities\n- **Mem Agent**: Memory-focused agent (coming soon)\n- **Cogito Agent**: Cognitive reasoning agent (coming soon)\n\n## Project Structure\n\n```\ncogents/\n\u251c\u2500\u2500 agents/ # Agent implementations\n\u251c\u2500\u2500 base/ # Base classes and models\n\u251c\u2500\u2500 common/ # Shared utilities and LLM integrations\n\u251c\u2500\u2500 goalith/ # Goal management and planning\n\u251c\u2500\u2500 memory/ # Memory management (on plan)\n\u251c\u2500\u2500 orchestrix/ # Global orchestration (on plan)\n\u251c\u2500\u2500 resources/ # External service integrations\n\u2514\u2500\u2500 toolify/ # Tool management and execution\n```\n\n## Creating a New Agent\n\n### From Base Classes\nStart with the base agent classes in `cogents.base` to create custom agents with full control over behavior and capabilities.\n\n#### Base Agent Class Hierarchy\n\n```\nBaseAgent (abstract)\n\u251c\u2500\u2500 Core functionality\n\u2502 \u251c\u2500\u2500 LLM client management\n\u2502 \u251c\u2500\u2500 Token usage tracking\n\u2502 \u251c\u2500\u2500 Logging capabilities\n\u2502 \u2514\u2500\u2500 Configuration management\n\u2502\n\u251c\u2500\u2500 BaseGraphicAgent (abstract)\n\u2502 \u251c\u2500\u2500 LangGraph integration\n\u2502 \u251c\u2500\u2500 State management\n\u2502 \u251c\u2500\u2500 Graph visualization\n\u2502 \u2514\u2500\u2500 Error handling patterns\n\u2502 \u2502\n\u2502 \u251c\u2500\u2500 BaseConversationAgent (abstract)\n\u2502 \u2502 \u251c\u2500\u2500 Session management\n\u2502 \u2502 \u251c\u2500\u2500 Message handling\n\u2502 \u2502 \u251c\u2500\u2500 Conversation state\n\u2502 \u2502 \u2514\u2500\u2500 Response generation\n\u2502 \u2502\n\u2502 \u2514\u2500\u2500 BaseResearcher (abstract)\n\u2502 \u251c\u2500\u2500 Research workflow\n\u2502 \u251c\u2500\u2500 Source management\n\u2502 \u251c\u2500\u2500 Query generation\n\u2502 \u2514\u2500\u2500 Result compilation\n\u2502 \u2514\u2500\u2500 Uses ResearchOutput model\n\u2502 \u251c\u2500\u2500 content: str\n\u2502 \u251c\u2500\u2500 sources: List[Dict]\n\u2502 \u251c\u2500\u2500 summary: str\n\u2502 \u2514\u2500\u2500 timestamp: datetime\n```\n\n**Key Inheritance Paths:**\n- **BaseAgent**: Core functionality (LLM client, token tracking, logging)\n- **BaseGraphicAgent**: LangGraph integration and visualization\n- **BaseConversationAgent**: Session management and conversation patterns\n- **BaseResearcher**: Research workflow and structured output patterns\n\n### From Existing Agents\nUse well-constructed agents like Seekra Agent as templates:\n\n```python\nfrom cogents.agents.seekra_agent import SeekraAgent\n\n# Extend Seekra Agent for custom research tasks\nclass CustomResearchAgent(SeekraAgent):\n def __init__(self, *args, **kwargs):\n super().__init__(*args, **kwargs)\n # Add custom functionality\n \n def custom_research_method(self):\n # Implement custom research logic\n pass\n```\n\n## Install\n\n```\npip install -U cogents\n```\n\n## Documentation\n\nFor detailed documentation, visit: https://cogents.readthedocs.io/ (under construction)\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Acknowledgment\n\n- Tencent [Youtu-agent](https://github.com/Tencent/Youtu-agent) toolkits integration.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Towards a cognitive agentic framework",
"version": "0.0.16",
"project_urls": {
"Documentation": "https://cogents.readthedocs.io/",
"Homepage": "https://github.com/caesar0301/cogents",
"Repository": "https://github.com/caesar0301/cogents"
},
"split_keywords": [
"agentic",
" multi-agent",
" framework",
" cognition",
" artificial intelligence"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9ef3258e6a6dcf256e7a37bc43ff39062bea88b9bb611d7c83437ef4da3124d7",
"md5": "d35ffc268df1470bddae10c5dff91205",
"sha256": "bc73a65c9b5994a1174c55113f5f99e6f243490cb291b19ae3e99e910cf3db3f"
},
"downloads": -1,
"filename": "cogents-0.0.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d35ffc268df1470bddae10c5dff91205",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 351350,
"upload_time": "2025-08-31T04:09:06",
"upload_time_iso_8601": "2025-08-31T04:09:06.519045Z",
"url": "https://files.pythonhosted.org/packages/9e/f3/258e6a6dcf256e7a37bc43ff39062bea88b9bb611d7c83437ef4da3124d7/cogents-0.0.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b9ab4c46a3ee31f3423ef99ae9c4ea40610c3a109371170f56ccb68be3934a6c",
"md5": "80b66e564ff9cabf850eb836ad29123f",
"sha256": "a6b67d3336e3035a04a3feb95701fa537758dd370311ddaba78c6f4ee95914c3"
},
"downloads": -1,
"filename": "cogents-0.0.16.tar.gz",
"has_sig": false,
"md5_digest": "80b66e564ff9cabf850eb836ad29123f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 292482,
"upload_time": "2025-08-31T04:09:08",
"upload_time_iso_8601": "2025-08-31T04:09:08.531574Z",
"url": "https://files.pythonhosted.org/packages/b9/ab/4c46a3ee31f3423ef99ae9c4ea40610c3a109371170f56ccb68be3934a6c/cogents-0.0.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 04:09:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "caesar0301",
"github_project": "cogents",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cogents"
}
JSON
