{"id":37065001,"url":"https://github.com/caesar0301/cogents-core","last_synced_at":"2026-01-14T07:36:16.786Z","repository":{"id":313185076,"uuid":"1050334904","full_name":"caesar0301/cogents-core","owner":"caesar0301","description":"Core and base module towards a cognitive agentic framework (core and base)","archived":false,"fork":false,"pushed_at":"2025-12-26T12:20:17.000Z","size":558,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-05T22:54:31.042Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caesar0301.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-04T09:33:48.000Z","updated_at":"2025-12-26T12:20:15.000Z","dependencies_parsed_at":"2025-09-24T06:17:18.541Z","dependency_job_id":"c19e6dd5-ceb2-4230-beca-4bc1c42f2101","html_url":"https://github.com/caesar0301/cogents-core","commit_stats":null,"previous_names":["mirasurf/cogents-core","caesar0301/cogents-core"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/caesar0301/cogents-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caesar0301%2Fcogents-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caesar0301%2Fcogents-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caesar0301%2Fcogents-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caesar0301%2Fcogents-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caesar0301","download_url":"https://codeload.github.com/caesar0301/cogents-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caesar0301%2Fcogents-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28413435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T07:36:16.148Z","updated_at":"2026-01-14T07:36:16.770Z","avatar_url":"https://github.com/caesar0301.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cogents-core\n\n[![CI](https://github.com/caesar0301/cogents-core/actions/workflows/ci.yml/badge.svg)](https://github.com/caesar0301/cogents-core/actions/workflows/ci.yml)\n[![PyPI version](https://img.shields.io/pypi/v/cogents-core.svg)](https://pypi.org/project/cogents-core/)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/caesar0301/cogents-core)\n\nThis is part of [Project Cogents](https://www.xiaming.site/2025/08/30/project-cogents/), 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)).\n\n## Installation\n\n```bash\npip install -U cogents-core\n```\n\n## Core Modules\n\nCogents offers a comprehensive set of modules for creating intelligent agent-based applications:\n\n### LLM Integration \u0026 Management (`cogents_core.llm`)\n- **Multi-model support**: OpenAI, OpenRouter, Ollama, LlamaCPP, and LiteLLM\n- **Advanced routing**: Dynamic complexity-based and self-assessment routing strategies\n- **Tracing \u0026 monitoring**: Built-in token tracking and Opik tracing integration\n- **Extensible architecture**: Easy to add new LLM providers\n\n### Goal Management \u0026 Planning (`cogents_core.goalith`) - *In Development*\n- **Goal decomposition**: LLM-based, callable, and simple goal decomposition strategies\n- **Graph-based structure**: DAG-based goal management with dependencies\n- **Node management**: Goal, subgoal, and task node creation and tracking\n- **Conflict detection**: Framework for automated goal conflict identification (planned)\n- **Replanning**: Dynamic goal replanning capabilities (planned)\n\n### Tool Management (`cogents_core.toolify`)\n- **Tool registry**: Centralized tool registration and management\n- **MCP integration**: Model Context Protocol support for tool discovery\n- **Execution engine**: Robust tool execution with error handling\n- **Toolkit system**: Organized tool collections and configurations\n\n### Memory Management (`cogents_core.memory`)\n- **MemU integration**: Advanced memory agent with categorization\n- **Embedding support**: Vector-based memory retrieval and linking\n- **Multi-category storage**: Activity, event, and profile memory types\n- **Memory linking**: Automatic relationship discovery between memories\n\n### Vector Storage (`cogents_core.vector_store`)\n- **PGVector support**: PostgreSQL with pgvector extension\n- **Weaviate integration**: Cloud-native vector database\n- **Semantic search**: Embedding-based document retrieval\n- **Flexible indexing**: HNSW and DiskANN indexing strategies\n\n### Message Bus (`cogents_core.msgbus`)\n- **Event-driven architecture**: Inter-component communication\n- **Watchdog patterns**: Monitoring and reactive behaviors\n- **Flexible routing**: Message filtering and delivery\n\n### Routing \u0026 Tracing (`cogents_core.routing`, `cogents_core.tracing`)\n- **Smart routing**: Dynamic model selection based on complexity\n- **Token tracking**: Comprehensive usage monitoring\n- **Opik integration**: Production-ready observability\n- **LangGraph hooks**: Workflow tracing and debugging\n\n## Project Structure\n\n```\ncogents_core/\n├── agent/           # Base agent classes and models\n├── goalith/         # Goal management and planning system\n│   ├── decomposer/  # Goal decomposition strategies\n│   ├── goalgraph/   # Graph data structures\n│   ├── conflict/    # Conflict detection\n│   └── replanner/   # Dynamic replanning\n├── llm/             # LLM provider implementations\n├── memory/          # Memory management system\n│   └── memu/        # MemU memory agent integration\n├── toolify/         # Tool management and execution\n├── vector_store/    # Vector database integrations\n├── msgbus/          # Message bus system\n├── routing/         # LLM routing strategies\n├── tracing/         # Token tracking and observability\n└── utils/           # Utilities and logging\n```\n\n## Quick Start\n\n### 1. LLM Client Usage\n\n```python\nfrom cogents_core.llm import get_llm_client\n\n# OpenAI/OpenRouter providers\nclient = get_llm_client(provider=\"openai\", api_key=\"sk-...\")\nclient = get_llm_client(provider=\"openrouter\", api_key=\"sk-...\")\n\n# Local providers\nclient = get_llm_client(provider=\"ollama\", base_url=\"http://localhost:11434\")\nclient = get_llm_client(provider=\"llamacpp\", model_path=\"/path/to/model.gguf\")\n\n# Basic chat completion\nresponse = client.completion([\n    {\"role\": \"user\", \"content\": \"Hello!\"}\n])\n\n# Structured output (requires structured_output=True)\nfrom pydantic import BaseModel\n\nclass Response(BaseModel):\n    answer: str\n    confidence: float\n\nclient = get_llm_client(provider=\"openai\", structured_output=True)\nresult = client.structured_completion(messages, Response)\n```\n\n### 2. Goal Management with Goalith\n\n**Note**: The Goalith goal management system is currently under development. The core components are available but the full service integration is not yet complete.\n\n```python\n# Basic goal node creation and management\nfrom cogents_core.goalith.goalgraph.node import GoalNode, NodeStatus\nfrom cogents_core.goalith.goalgraph.graph import GoalGraph\nfrom cogents_core.goalith.decomposer import LLMDecomposer\n\n# Create a goal node\ngoal_node = GoalNode(\n    description=\"Plan and execute a product launch\",\n    priority=8.0,\n    context={\n        \"budget\": \"$50,000\",\n        \"timeline\": \"3 months\",\n        \"target_audience\": \"young professionals\"\n    },\n    tags=[\"product\", \"launch\", \"marketing\"]\n)\n\n# Create goal graph for management\ngraph = GoalGraph()\ngraph.add_node(goal_node)\n\n# Use LLM decomposer directly\ndecomposer = LLMDecomposer()\nsubgoals = decomposer.decompose(goal_node, context={\n    \"team_size\": \"5 people\",\n    \"experience_level\": \"intermediate\"\n})\n\nprint(f\"Goal: {goal_node.description}\")\nprint(f\"Status: {goal_node.status}\")\nprint(f\"Generated {len(subgoals)} subgoals\")\n```\n\n### 3. Memory Management\n\n```python\nfrom cogents_core.memory.memu import MemoryAgent\n\n# Initialize memory agent\nmemory_agent = MemoryAgent(\n    agent_id=\"my_agent\",\n    user_id=\"user123\",\n    memory_dir=\"/tmp/memory_storage\",\n    enable_embeddings=True\n)\n\n# Add activity memory\nactivity_content = \"\"\"\nUSER: Hi, I'm Sarah and I work as a software engineer.\nASSISTANT: Nice to meet you Sarah! What kind of projects do you work on?\nUSER: I mainly work on web applications using Python and React.\n\"\"\"\n\nresult = memory_agent.call_function(\n    \"add_activity_memory\",\n    {\n        \"character_name\": \"Sarah\",\n        \"content\": activity_content\n    }\n)\n\n# Generate memory suggestions\nif result.get(\"success\"):\n    memory_items = result.get(\"memory_items\", [])\n    suggestions = memory_agent.call_function(\n        \"generate_memory_suggestions\",\n        {\n            \"character_name\": \"Sarah\",\n            \"new_memory_items\": memory_items\n        }\n    )\n```\n\n### 4. Vector Store Operations\n\n```python\nfrom cogents_core.vector_store import PGVectorStore\nfrom cogents_core.llm import get_llm_client\n\n# Initialize vector store\nvector_store = PGVectorStore(\n    collection_name=\"my_documents\",\n    embedding_model_dims=768,\n    dbname=\"vectordb\",\n    user=\"postgres\",\n    password=\"postgres\",\n    host=\"localhost\",\n    port=5432\n)\n\n# Initialize embedding client\nembed_client = get_llm_client(provider=\"ollama\", embed_model=\"nomic-embed-text\")\n\n# Prepare documents\ndocuments = [\n    {\n        \"id\": \"doc1\",\n        \"content\": \"Machine learning is a subset of AI...\",\n        \"metadata\": {\"category\": \"AI\", \"type\": \"definition\"}\n    }\n]\n\n# Generate embeddings and store\nvectors = []\npayloads = []\nids = []\n\nfor doc in documents:\n    embedding = embed_client.embed(doc[\"content\"])\n    vectors.append(embedding)\n    payloads.append(doc[\"metadata\"])\n    ids.append(doc[\"id\"])\n\n# Insert into vector store\nvector_store.insert(vectors=vectors, payloads=payloads, ids=ids)\n\n# Search\nquery = \"What is artificial intelligence?\"\nquery_embedding = embed_client.embed(query)\nresults = vector_store.search(query=query, vectors=query_embedding, limit=5)\n```\n\n### 5. Tool Management\n\n```python\nfrom cogents_core.toolify import BaseToolkit, ToolkitConfig, ToolkitRegistry, register_toolkit\nfrom typing import Dict, Callable\n\n# Create a custom toolkit using decorator\n@register_toolkit(\"calculator\")\nclass CalculatorToolkit(BaseToolkit):\n    def get_tools_map(self) -\u003e Dict[str, Callable]:\n        return {\n            \"add\": self.add,\n            \"multiply\": self.multiply\n        }\n\n    def add(self, a: float, b: float) -\u003e float:\n        \"\"\"Add two numbers.\"\"\"\n        return a + b\n\n    def multiply(self, a: float, b: float) -\u003e float:\n        \"\"\"Multiply two numbers.\"\"\"\n        return a * b\n\n# Alternative: Manual registration\nconfig = ToolkitConfig(name=\"calculator\", description=\"Basic math operations\")\nToolkitRegistry.register(\"calculator\", CalculatorToolkit)\n\n# Create and use toolkit\ncalculator = ToolkitRegistry.create_toolkit(\"calculator\", config)\nresult = calculator.call_tool(\"add\", a=5, b=3)\nprint(f\"5 + 3 = {result}\")\n```\n\n### 6. Message Bus and Events\n\n```python\nfrom cogents_core.msgbus import EventBus, BaseEvent, BaseWatchdog\n\n# Define custom event\nclass TaskCompleted(BaseEvent):\n    def __init__(self, task_id: str, result: str):\n        super().__init__()\n        self.task_id = task_id\n        self.result = result\n\n# Create event bus\nbus = EventBus()\n\n# Define watchdog\nclass TaskWatchdog(BaseWatchdog):\n    def handle_event(self, event: BaseEvent):\n        if isinstance(event, TaskCompleted):\n            print(f\"Task {event.task_id} completed with result: {event.result}\")\n\n# Register watchdog and publish event\nwatchdog = TaskWatchdog()\nbus.register_watchdog(watchdog)\nbus.publish(TaskCompleted(\"task_1\", \"success\"))\n```\n\n### 7. Token Tracking and Tracing\n\n```python\nfrom cogents_core.tracing import get_token_tracker\nfrom cogents_core.llm import get_llm_client\n\n# Initialize client and tracker\nclient = get_llm_client(provider=\"openai\")\ntracker = get_token_tracker()\n\n# Reset tracker\ntracker.reset()\n\n# Make LLM calls (automatically tracked)\nresponse1 = client.completion([{\"role\": \"user\", \"content\": \"Hello\"}])\nresponse2 = client.completion([{\"role\": \"user\", \"content\": \"How are you?\"}])\n\n# Get usage statistics\nstats = tracker.get_stats()\nprint(f\"Total tokens: {stats['total_tokens']}\")\nprint(f\"Total calls: {stats['total_calls']}\")\nprint(f\"Average tokens per call: {stats.get('avg_tokens_per_call', 0)}\")\n```\n\n## Environment Variables\n\nSet these environment variables for different providers:\n\n```bash\n# Default LLM provider\nexport COGENTS_LLM_PROVIDER=\"openai\"\n\n# OpenAI\nexport OPENAI_API_KEY=\"sk-...\"\n\n# OpenRouter\nexport OPENROUTER_API_KEY=\"sk-...\"\n\n# LlamaCPP\nexport LLAMACPP_MODEL_PATH=\"/path/to/model.gguf\"\n\n# Ollama\nexport OLLAMA_BASE_URL=\"http://localhost:11434\"\n\n# PostgreSQL (for vector store)\nexport POSTGRES_HOST=\"localhost\"\nexport POSTGRES_PORT=\"5432\"\nexport POSTGRES_DB=\"vectordb\"\nexport POSTGRES_USER=\"postgres\"\nexport POSTGRES_PASSWORD=\"postgres\"\n```\n\n## Advanced Usage\n\n### Custom Goal Decomposer\n\n```python\nfrom cogents_core.goalith.decomposer.base import GoalDecomposer\nfrom cogents_core.goalith.goalgraph.node import GoalNode\nfrom typing import List, Dict, Any, Optional\nimport copy\n\nclass CustomDecomposer(GoalDecomposer):\n    @property\n    def name(self) -\u003e str:\n        return \"custom_decomposer\"\n\n    def decompose(self, goal_node: GoalNode, context: Optional[Dict[str, Any]] = None) -\u003e List[GoalNode]:\n        # Custom decomposition logic\n        subtasks = [\n            \"Research requirements\",\n            \"Design solution\",\n            \"Implement features\",\n            \"Test and deploy\"\n        ]\n\n        nodes = []\n        for i, subtask in enumerate(subtasks):\n            # Deep copy context to avoid shared references\n            context_copy = copy.deepcopy(goal_node.context) if goal_node.context else {}\n\n            node = GoalNode(\n                description=subtask,\n                parent=goal_node.id,\n                priority=goal_node.priority - i * 0.1,\n                context=context_copy,\n                tags=goal_node.tags.copy() if goal_node.tags else [],\n                decomposer_name=self.name\n            )\n            nodes.append(node)\n\n        return nodes\n\n# Use the decomposer directly\ncustom_decomposer = CustomDecomposer()\ngoal_node = GoalNode(description=\"Build a web application\")\nsubgoals = custom_decomposer.decompose(goal_node)\n```\n\n### LLM Routing Strategies\n\n```python\nfrom cogents_core.routing import ModelRouter, DynamicComplexityStrategy\nfrom cogents_core.llm import get_llm_client\n\n# Create a lite client for complexity assessment\nlite_client = get_llm_client(provider=\"ollama\", chat_model=\"llama3.2:1b\")\n\n# Create router with dynamic complexity strategy\nrouter = ModelRouter(\n    strategy=\"dynamic_complexity\",\n    lite_client=lite_client,\n    strategy_config={\n        \"complexity_threshold_low\": 0.3,\n        \"complexity_threshold_high\": 0.7\n    }\n)\n\n# Route queries to get tier recommendations\nsimple_query = \"What is 2+2?\"\nresult = router.route(simple_query)\nprint(f\"Query: {simple_query}\")\nprint(f\"Recommended tier: {result.tier}\")  # Likely ModelTier.LITE\nprint(f\"Confidence: {result.confidence}\")\n\ncomplex_query = \"Explain quantum computing and its applications\"\nresult = router.route(complex_query)\nprint(f\"Query: {complex_query}\")\nprint(f\"Recommended tier: {result.tier}\")  # Likely ModelTier.POWER\nprint(f\"Confidence: {result.confidence}\")\n\n# Get recommended model configuration\nrouting_result, model_config = router.route_and_configure(complex_query)\nprint(f\"Recommended config: {model_config}\")\n```\n\n## Examples\n\nCheck the `examples/` directory for comprehensive usage examples:\n\n- **LLM Examples**: `examples/llm/` - OpenAI, Ollama, LlamaCPP, token tracking\n- **Goal Management**: `examples/goals/` - Goal decomposition and planning\n- **Memory Examples**: `examples/memory/` - Memory agent operations\n- **Vector Store**: `examples/vector_store/` - PGVector and Weaviate usage\n- **Message Bus**: `examples/msgbus/` - Event-driven patterns\n- **Tools**: Various toolkit implementations\n\n## Development\n\n```bash\n# Install development dependencies\nmake install\n\n# Run tests\nmake test\n\n# Run specific test categories\nmake test-unit          # Unit tests only\nmake test-integration   # Integration tests only\n\n# Format code\nmake format\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaesar0301%2Fcogents-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaesar0301%2Fcogents-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaesar0301%2Fcogents-core/lists"}