# Cogency
[](https://badge.fury.io/py/cogency)
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.python.org/downloads/)
**Smart AI agents that think as hard as they need to.**
> 🚧 **Production Beta (v0.9.1)** - Architecturally complete, actively gathering feedback from early adopters. Ready for serious evaluation and beta deployments.
```python
from cogency import Agent
agent = Agent("assistant")
# Simple task → thinks fast
await agent.run("What's 2+2?")
# Complex task → thinks deep
await agent.run("Analyze this codebase and suggest architectural improvements")
# Automatically escalates reasoning, uses relevant tools, streams thinking
```
## 🧠 Adaptive Reasoning
**Thinks fast or deep as needed** - agents discover task complexity during execution and adapt their cognitive approach automatically.
- **Fast React**: Direct execution for simple queries
- **Deep React**: Reflection + planning for complex analysis
- **Zero-cost switching**: Seamless transitions preserve full context
- **Runtime discovery**: No upfront classification - intelligence governs intelligence
## 🚀 Key Features
- **🤖 Agents in 3 lines** - Fully functional, tool-using agents from a single import
- **🔥 Adaptive reasoning** - Thinks fast or deep as needed, switches seamlessly during execution
- **🌊 Streaming first** - Watch agents think in real-time with full transparency
- **🛠️ Automatic tool discovery** - Drop tools in, they auto-register and route intelligently
- **⚡️ Zero configuration** - Auto-detects LLMs, tools, memory from environment
- **🧠 Built-in memory** - Persistent memory with extensible backends (Pinecone, ChromaDB, PGVector)
- **✨ Clean tracing** - Every reasoning step traced and streamed with clear phase indicators
- **🌍 Universal LLM support** - OpenAI, Anthropic, Gemini, Grok, Mistral out of the box
- **🧩 Extensible design** - Add tools, memory backends, embedders with zero friction
- **👥 Multi-tenancy** - Built-in user contexts and conversation isolation
- **🏗️ Production hardened** - Resilience, rate limiting, metrics, tracing included
## How It Works
**Preprocess → Reason → Act → Respond**
```
👤 Plan a Tokyo trip with $2000 budget
🔧 Tools: weather, calculator, search
🧠 Task complexity → escalating to Deep React
🌤️ weather(Tokyo) → 25°C sunny, rain Thu-Fri
🧮 calculator($2000 ÷ 5 days) → $400/day
🔍 search(Tokyo indoor activities) → Museums, temples
💭 Reflection: Need indoor backup plans for rainy days
📋 Planning: 5-day itinerary with weather contingencies
🤖 Here's your optimized Tokyo itinerary...
```
The preprocessing phase handles tool selection, memory operations, and intelligent routing between reasoning modes.
## Quick Examples
**Custom Tools**
```python
from cogency.tools import Tool, tool
@tool
class MyTool(Tool):
def __init__(self):
super().__init__("my_tool", "Does something useful")
async def run(self, param: str):
return {"result": f"Processed: {param}"}
# Tool auto-registers - just create agent
agent = Agent("assistant")
await agent.run("Use my_tool with hello")
```
**Real-World Applications**
```python
# Research Agent
agent = Agent("researcher")
await agent.run("Latest quantum computing developments?")
# Coding Assistant
agent = Agent("coder")
await agent.run("Fix the auth bug in this Flask app")
# Data Analyst
agent = Agent("analyst")
await agent.run("Analyze sales trends in quarterly_data.csv")
```
## Built-in Tools
Agents automatically discover and use relevant tools:
🧮 **Calculator** - Mathematical expressions and calculations
🔍 **Search** - Web search for current information
🌤️ **Weather** - Current conditions and forecasts
📁 **Files** - Create, read, edit, list, delete files
💻 **Shell** - Execute system commands safely
🐍 **Code** - Python code execution in sandboxed environment
📊 **CSV** - Data processing and analysis
🗄️ **SQL** - Database querying and management
🌐 **HTTP** - Make HTTP requests with JSON parsing
🕒 **Time** - Date/time operations and timezone conversions
🔗 **Scrape** - Web scraping with content extraction
🧠 **Recall** - Memory search and retrieval
## Installation
```bash
pip install cogency
```
**Beta Note**: Cross-provider testing is ongoing. OpenAI and Anthropic are well-tested; other providers may have edge cases.
Set any LLM API key:
```bash
export OPENAI_API_KEY=... # or
export ANTHROPIC_API_KEY=... # or
export GEMINI_API_KEY=... # etc
```
## Documentation
- **[Quick Start](docs/quickstart.md)** - Get running in 5 minutes
- **[API Reference](docs/api.md)** - Complete Agent class documentation
- **[Tools](docs/tools.md)** - Built-in tools and custom tool creation
- **[Examples](docs/examples.md)** - Detailed code examples and walkthroughs
- **[Memory](docs/memory.md)** - Memory backends and configuration
- **[Reasoning](docs/reasoning.md)** - Adaptive reasoning modes
- **[Configuration](docs/configuration.md)** - Advanced configuration options
- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
## 📄 License
Apache 2.0 - Build whatever you want.
## Beta Feedback
We're actively gathering feedback from early adopters:
- **Issues**: [GitHub Issues](https://github.com/iteebz/cogency/issues)
- **Discussions**: [GitHub Discussions](https://github.com/iteebz/cogency/discussions)
- **Known limitations**: Cross-provider behavior, memory backend edge cases
---
_Built for developers who want agents that just work, not frameworks that require PhD-level configuration._
Raw data
{
"_id": null,
"home_page": "https://github.com/iteebz/cogency",
"name": "cogency",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "ai, agents, reasoning, react, memory, tools, tracing, cognition, streaming",
"author": "Tyson Chan",
"author_email": "tyson.chan@proton.me",
"download_url": "https://files.pythonhosted.org/packages/30/29/b4f851caab1698e8776c3a162d37eb5242c100e2ce03f6f996180a1674df/cogency-0.9.1.tar.gz",
"platform": null,
"description": "# Cogency\n\n[](https://badge.fury.io/py/cogency)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://www.python.org/downloads/)\n\n**Smart AI agents that think as hard as they need to.**\n\n> \ud83d\udea7 **Production Beta (v0.9.1)** - Architecturally complete, actively gathering feedback from early adopters. Ready for serious evaluation and beta deployments.\n\n```python\nfrom cogency import Agent\nagent = Agent(\"assistant\")\n\n# Simple task \u2192 thinks fast\nawait agent.run(\"What's 2+2?\")\n\n# Complex task \u2192 thinks deep\nawait agent.run(\"Analyze this codebase and suggest architectural improvements\")\n# Automatically escalates reasoning, uses relevant tools, streams thinking\n```\n\n## \ud83e\udde0 Adaptive Reasoning\n\n**Thinks fast or deep as needed** - agents discover task complexity during execution and adapt their cognitive approach automatically.\n\n- **Fast React**: Direct execution for simple queries\n- **Deep React**: Reflection + planning for complex analysis\n- **Zero-cost switching**: Seamless transitions preserve full context\n- **Runtime discovery**: No upfront classification - intelligence governs intelligence\n\n## \ud83d\ude80 Key Features\n\n- **\ud83e\udd16 Agents in 3 lines** - Fully functional, tool-using agents from a single import\n- **\ud83d\udd25 Adaptive reasoning** - Thinks fast or deep as needed, switches seamlessly during execution\n- **\ud83c\udf0a Streaming first** - Watch agents think in real-time with full transparency\n- **\ud83d\udee0\ufe0f Automatic tool discovery** - Drop tools in, they auto-register and route intelligently\n- **\u26a1\ufe0f Zero configuration** - Auto-detects LLMs, tools, memory from environment\n- **\ud83e\udde0 Built-in memory** - Persistent memory with extensible backends (Pinecone, ChromaDB, PGVector)\n- **\u2728 Clean tracing** - Every reasoning step traced and streamed with clear phase indicators\n- **\ud83c\udf0d Universal LLM support** - OpenAI, Anthropic, Gemini, Grok, Mistral out of the box\n- **\ud83e\udde9 Extensible design** - Add tools, memory backends, embedders with zero friction\n- **\ud83d\udc65 Multi-tenancy** - Built-in user contexts and conversation isolation\n- **\ud83c\udfd7\ufe0f Production hardened** - Resilience, rate limiting, metrics, tracing included\n\n## How It Works\n\n**Preprocess \u2192 Reason \u2192 Act \u2192 Respond**\n\n```\n\ud83d\udc64 Plan a Tokyo trip with $2000 budget\n\n\ud83d\udd27 Tools: weather, calculator, search\n\ud83e\udde0 Task complexity \u2192 escalating to Deep React\n\ud83c\udf24\ufe0f weather(Tokyo) \u2192 25\u00b0C sunny, rain Thu-Fri\n\ud83e\uddee calculator($2000 \u00f7 5 days) \u2192 $400/day\n\ud83d\udd0d search(Tokyo indoor activities) \u2192 Museums, temples\n\ud83d\udcad Reflection: Need indoor backup plans for rainy days\n\ud83d\udccb Planning: 5-day itinerary with weather contingencies\n\ud83e\udd16 Here's your optimized Tokyo itinerary...\n```\n\nThe preprocessing phase handles tool selection, memory operations, and intelligent routing between reasoning modes.\n\n## Quick Examples\n\n**Custom Tools**\n\n```python\nfrom cogency.tools import Tool, tool\n\n@tool\nclass MyTool(Tool):\n def __init__(self):\n super().__init__(\"my_tool\", \"Does something useful\")\n\n async def run(self, param: str):\n return {\"result\": f\"Processed: {param}\"}\n\n# Tool auto-registers - just create agent\nagent = Agent(\"assistant\")\nawait agent.run(\"Use my_tool with hello\")\n```\n\n**Real-World Applications**\n\n```python\n# Research Agent\nagent = Agent(\"researcher\")\nawait agent.run(\"Latest quantum computing developments?\")\n\n# Coding Assistant\nagent = Agent(\"coder\")\nawait agent.run(\"Fix the auth bug in this Flask app\")\n\n# Data Analyst\nagent = Agent(\"analyst\")\nawait agent.run(\"Analyze sales trends in quarterly_data.csv\")\n```\n\n## Built-in Tools\n\nAgents automatically discover and use relevant tools:\n\n\ud83e\uddee **Calculator** - Mathematical expressions and calculations \n\ud83d\udd0d **Search** - Web search for current information \n\ud83c\udf24\ufe0f **Weather** - Current conditions and forecasts \n\ud83d\udcc1 **Files** - Create, read, edit, list, delete files \n\ud83d\udcbb **Shell** - Execute system commands safely \n\ud83d\udc0d **Code** - Python code execution in sandboxed environment \n\ud83d\udcca **CSV** - Data processing and analysis \n\ud83d\uddc4\ufe0f **SQL** - Database querying and management \n\ud83c\udf10 **HTTP** - Make HTTP requests with JSON parsing \n\ud83d\udd52 **Time** - Date/time operations and timezone conversions \n\ud83d\udd17 **Scrape** - Web scraping with content extraction \n\ud83e\udde0 **Recall** - Memory search and retrieval\n\n## Installation\n\n```bash\npip install cogency\n```\n\n**Beta Note**: Cross-provider testing is ongoing. OpenAI and Anthropic are well-tested; other providers may have edge cases.\n\nSet any LLM API key:\n\n```bash\nexport OPENAI_API_KEY=... # or\nexport ANTHROPIC_API_KEY=... # or\nexport GEMINI_API_KEY=... # etc\n```\n\n## Documentation\n\n- **[Quick Start](docs/quickstart.md)** - Get running in 5 minutes\n- **[API Reference](docs/api.md)** - Complete Agent class documentation\n- **[Tools](docs/tools.md)** - Built-in tools and custom tool creation\n- **[Examples](docs/examples.md)** - Detailed code examples and walkthroughs\n- **[Memory](docs/memory.md)** - Memory backends and configuration\n- **[Reasoning](docs/reasoning.md)** - Adaptive reasoning modes\n- **[Configuration](docs/configuration.md)** - Advanced configuration options\n- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions\n\n## \ud83d\udcc4 License\n\nApache 2.0 - Build whatever you want.\n\n## Beta Feedback\n\nWe're actively gathering feedback from early adopters:\n\n- **Issues**: [GitHub Issues](https://github.com/iteebz/cogency/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/iteebz/cogency/discussions)\n- **Known limitations**: Cross-provider behavior, memory backend edge cases\n\n---\n\n_Built for developers who want agents that just work, not frameworks that require PhD-level configuration._\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Smart AI agents that think as hard as they need to.",
"version": "0.9.1",
"project_urls": {
"Homepage": "https://github.com/iteebz/cogency",
"Repository": "https://github.com/iteebz/cogency"
},
"split_keywords": [
"ai",
" agents",
" reasoning",
" react",
" memory",
" tools",
" tracing",
" cognition",
" streaming"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4e65ceefd79ffe6d656bff980bc6c163207b7706ddbc5d10518580201b6f9972",
"md5": "15e03bfd5f4831c3a3c974068cb527fa",
"sha256": "dd3b69b6d562c818997692a9ec5c53d31b0426947a274c3b0a5201458eac8b96"
},
"downloads": -1,
"filename": "cogency-0.9.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "15e03bfd5f4831c3a3c974068cb527fa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 120625,
"upload_time": "2025-07-31T06:08:31",
"upload_time_iso_8601": "2025-07-31T06:08:31.109453Z",
"url": "https://files.pythonhosted.org/packages/4e/65/ceefd79ffe6d656bff980bc6c163207b7706ddbc5d10518580201b6f9972/cogency-0.9.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3029b4f851caab1698e8776c3a162d37eb5242c100e2ce03f6f996180a1674df",
"md5": "e44551aecc4d48509de0f99c741f1231",
"sha256": "ae6e06415d74ef24dceb94d4afe38a3ebbbc6c00b41358fb335e3a02bc3a29c4"
},
"downloads": -1,
"filename": "cogency-0.9.1.tar.gz",
"has_sig": false,
"md5_digest": "e44551aecc4d48509de0f99c741f1231",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 87164,
"upload_time": "2025-07-31T06:08:32",
"upload_time_iso_8601": "2025-07-31T06:08:32.764871Z",
"url": "https://files.pythonhosted.org/packages/30/29/b4f851caab1698e8776c3a162d37eb5242c100e2ce03f6f996180a1674df/cogency-0.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 06:08:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "iteebz",
"github_project": "cogency",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cogency"
}
JSON
