| Name | chief-ai JSON |
| Version |
0.1.5
JSON |
| download |
| home_page | None |
| Summary | AI agent framework with Chief and Chen, a conversational AI psychologist with web search and multi-provider support in your terminal. |
| upload_time | 2025-09-09 05:16:02 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.13 |
| license | MIT |
| keywords |
agent
ai
anthropic
assistant
chat
openai
openrouter
psychologist
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Chief & Chen AI Agents
A sophisticated AI agent framework built with Pydantic AI, featuring two main applications: **Chief** and **Chen**. Both agents provide conversational AI interfaces with web search capabilities and configurable model providers.
**Chen** has been written as an AI psychologist with an extensive software engineering background. You can think of her like [Wendy Rhoades](https://www.charactour.com/hub/characters/view/Wendy-Rhoades.Billions) that is always on your side.
On the other hand, **Chief** is a barebone agent with a barebone system prompt. Chief provides an entry point if you want to write your own agents using the same patterns that Chen uses.
Fork the repository and customize **Chief** however you want!
## Features
- **Dual Agent System**: Chief and Chen applications with distinct personalities and capabilities
- **Multi-Provider Support**: Anthropic, OpenAI, and OpenRouter integration
- **Web Search Integration**: Powered by Tavily API for real-time information
- **Smart Configuration**: Interactive onboarding with JSON-based settings management
- **MongoDB Persistence**: ~~Async document storage with Beanie ODM~~ Not implemented yet
- **Rich CLI Interface**: Beautiful terminal UI with Typer and Rich
- **MCP Support**: Coming soon
## Quick Start
### Easy Installation (Recommended)
Install with a convenience script that creates convenient `chen` and `chief` commands:
```bash
curl -sSL https://raw.githubusercontent.com/tistaharahap/chief-ai/main/install.sh | bash
```
After installation, you can run:
```bash
chen --help # Chen AI psychologist
chief --help # Basic AI agent
chen # Start Chen (triggers onboarding on first run)
```
### Manual Installation
Alternatively, run directly with uvx:
```bash
# Run Chen directly
uvx --python 3.13 --from chief-ai chen --help
# Go straight to onboarding
uvx --python 3.13 --from chief-ai chen
```
### Installation (for development)
```bash
# Clone and setup
git clone git@github.com:tistaharahap/chief-ai.git
cd chief-ai
source .venv/bin/activate
# Install dependencies
rye sync
```
## LLM Providers & Models Priority
In [src/libagentic/providers.py](src/libagentic/providers.py), it is clear that the first choice is Anthropic's Claude 4 Sonnet.
If the `anthropic_api_key` in `~/.chen/settings.json` is set, Claude 4 Sonnet will be the first choice. When all providers are set, the fallback becomes:
1. `claude-sonnet-4-20250514` via Anthropic
2. `gpt-5` via OpenAI
3. `deepseek/deepseek-chat-v3.1:free` via OpenRouter
To use free models, simply set the OpenRouter API key and leave the others unset.
## Chen
Chen has its settings defined in `~/.chen/settings.json` that looks like this:
```json
{
"anthropic_api_key": "sk-ant-...",
"openai_api_key": "sk-...",
"openrouter_api_key": "sk-or-...",
"tavily_api_key": "tvly_...",
"context_window": 200000,
"language": "English"
}
```
### Settings Explained
Each of these settings items are going to be prompted during onboarding if not set. Here are some commands with regards to settings:
```bash
chen config # View all settings
chen config get anthropic_api_key # Get specific setting, follows the JSON keys
chen config set context_window 150000 # Set specific setting
```
### Sessions
You can also find your chat history in `~/.chen/sessions/` with each session as a subdirectory there. A typical session directory might look like this:
```bash
ls -la ~/.chen/sessions/
total 0
drwxr-xr-x@ 14 tista staff 448 Sep 7 23:07 .
drwxr-xr-x@ 5 tista staff 160 Sep 7 22:05 ..
drwxr-xr-x@ 4 tista staff 128 Sep 7 21:01 068bdba6-1b51-7fd5-8000-b37d1f0832ea
drwxr-xr-x@ 4 tista staff 128 Sep 7 21:02 068bdbab-2071-7c75-8000-2cb9c8158015
drwxr-xr-x@ 4 tista staff 128 Sep 7 21:04 068bdbb2-163e-7553-8000-e3ce5a060b30
drwxr-xr-x@ 4 tista staff 128 Sep 7 21:04 068bdbb3-bbca-76b9-8000-498755d91316
drwxr-xr-x@ 4 tista staff 128 Sep 7 21:05 068bdbb5-702c-7e57-8000-317c40048963
drwxr-xr-x@ 4 tista staff 128 Sep 7 21:09 068bdbc3-cff6-7ea4-8000-62576dfa2d1f
```
Session subdirectories are named with UUID v7 which are chronologically sorted. Within each session, you will find these files:
```bash
ls -la ~/.chen/sessions/068bdba6-1b51-7fd5-8000-b37d1f0832ea
total 160
drwxr-xr-x@ 4 tista staff 128 Sep 7 21:01 .
drwxr-xr-x@ 14 tista staff 448 Sep 7 23:07 ..
-rw-r--r--@ 1 tista staff 74545 Sep 7 21:01 history.jsonl
-rw-r--r--@ 1 tista staff 327 Sep 7 21:01 metadata.json
```
The `history.jsonl` file contains the full conversation history in JSON Lines format, while `metadata.json` holds session metadata.
### In-chat Commands
While in a chat session with Chen, you can use the following commands:
```
/quit # Exit the chat session
/exit # Exit the chat session
Ctrl+D # Exit the chat session
Ctrl+C # Exit the chat session supposedly but you have to press it twice, got some exception bubbling not right yet
/resume # Resume a previous session, you will be shown a list of sessions to choose from
```
## Development
### Chen Configuration System
Chen uses a sophisticated JSON-based configuration system with interactive onboarding:
```bash
# View current settings
rye run chen config
# Set individual values
rye run chen config set anthropic_api_key "sk-ant-..."
rye run chen config set context_window 150000
# Manual onboarding
rye run chen onboard
# Reset all settings
rye run chen reset
```
Settings are stored in `~/.chen/settings.json` with support for:
- Anthropic, OpenAI, OpenRouter, and Tavily API keys
- Configurable context window size
- Automatic validation and type conversion
### Environment Variables (Optional)
Environment variables serve as defaults during onboarding:
```bash
export ANTHROPIC_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"
export OPENROUTER_API_KEY="your-key-here"
export TAVILY_API_KEY="your-key-here"
```
## Architecture
### Core Structure
```
src/
├── appclis/ # CLI applications
│ ├── chen.py # Chen agent with config system
│ ├── chief.py # Chief agent
│ └── settings/ # Configuration management
├── libagentic/ # Core agent framework
│ ├── agents.py # Agent factory functions
│ ├── providers.py # Model provider configs
│ ├── prompts.py # System prompts
│ └── tools/ # Agent tools and capabilities
└── libshared/ # Shared utilities
└── mongo.py # MongoDB base classes
```
### Technology Stack
- **Pydantic AI**: Core agent framework with Logfire integration
- **Typer + Rich**: Beautiful CLI interfaces with command groups
- **Pydantic Settings**: Type-safe configuration management
- **Beanie**: Async MongoDB ODM for persistence
- **Tavily**: Web search API integration
- **OpenRouter**: Multi-provider LLM access
## Development
### Code Quality
```bash
# Lint and format
ruff check . --fix
ruff format .
# Type checking and final lint
ruff check .
```
### Testing
```bash
# Run tests (when implemented)
pytest
# With coverage
pytest --cov=src
```
## Model Providers
- **Default**: `deepseek/deepseek-chat-v3.1:free` via OpenRouter, `gpt-5` via OpenAI and `claude-sonnet-4-20250514` via Anthropic
- **Supported**: All Anthropic, OpenAI, and OpenRouter models
- **Configuration**: Interactive setup or individual config commands
- **Fallbacks**: Automatic provider selection based on availability
## License
[MIT License](LICENSE)
## Contributing
Contributions are welcome! Please open issues or pull requests for enhancements and bug fixes.
Raw data
{
"_id": null,
"home_page": null,
"name": "chief-ai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "agent, ai, anthropic, assistant, chat, openai, openrouter, psychologist",
"author": null,
"author_email": "Batista Harahap <batista@bango29.com>",
"download_url": "https://files.pythonhosted.org/packages/58/88/fac054bd523c1b293d273320228a63de7d3c4f900dbac985b7d7d0ff876b/chief_ai-0.1.5.tar.gz",
"platform": null,
"description": "# Chief & Chen AI Agents\n\nA sophisticated AI agent framework built with Pydantic AI, featuring two main applications: **Chief** and **Chen**. Both agents provide conversational AI interfaces with web search capabilities and configurable model providers.\n\n**Chen** has been written as an AI psychologist with an extensive software engineering background. You can think of her like [Wendy Rhoades](https://www.charactour.com/hub/characters/view/Wendy-Rhoades.Billions) that is always on your side.\n\nOn the other hand, **Chief** is a barebone agent with a barebone system prompt. Chief provides an entry point if you want to write your own agents using the same patterns that Chen uses.\n\nFork the repository and customize **Chief** however you want!\n\n## Features\n\n- **Dual Agent System**: Chief and Chen applications with distinct personalities and capabilities\n- **Multi-Provider Support**: Anthropic, OpenAI, and OpenRouter integration\n- **Web Search Integration**: Powered by Tavily API for real-time information\n- **Smart Configuration**: Interactive onboarding with JSON-based settings management\n- **MongoDB Persistence**: ~~Async document storage with Beanie ODM~~ Not implemented yet\n- **Rich CLI Interface**: Beautiful terminal UI with Typer and Rich\n- **MCP Support**: Coming soon\n\n## Quick Start\n\n### Easy Installation (Recommended)\n\nInstall with a convenience script that creates convenient `chen` and `chief` commands:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/tistaharahap/chief-ai/main/install.sh | bash\n```\n\nAfter installation, you can run:\n\n```bash\nchen --help # Chen AI psychologist\nchief --help # Basic AI agent\nchen # Start Chen (triggers onboarding on first run)\n```\n\n### Manual Installation\n\nAlternatively, run directly with uvx:\n\n```bash\n# Run Chen directly\nuvx --python 3.13 --from chief-ai chen --help\n\n# Go straight to onboarding\nuvx --python 3.13 --from chief-ai chen\n```\n\n### Installation (for development)\n\n```bash\n# Clone and setup\ngit clone git@github.com:tistaharahap/chief-ai.git\ncd chief-ai\nsource .venv/bin/activate\n\n# Install dependencies\nrye sync\n```\n\n## LLM Providers & Models Priority\n\nIn [src/libagentic/providers.py](src/libagentic/providers.py), it is clear that the first choice is Anthropic's Claude 4 Sonnet.\n\nIf the `anthropic_api_key` in `~/.chen/settings.json` is set, Claude 4 Sonnet will be the first choice. When all providers are set, the fallback becomes:\n\n1. `claude-sonnet-4-20250514` via Anthropic\n2. `gpt-5` via OpenAI\n3. `deepseek/deepseek-chat-v3.1:free` via OpenRouter\n\nTo use free models, simply set the OpenRouter API key and leave the others unset.\n\n## Chen\n\nChen has its settings defined in `~/.chen/settings.json` that looks like this:\n\n```json\n{\n \"anthropic_api_key\": \"sk-ant-...\",\n \"openai_api_key\": \"sk-...\",\n \"openrouter_api_key\": \"sk-or-...\",\n \"tavily_api_key\": \"tvly_...\",\n \"context_window\": 200000,\n \"language\": \"English\"\n}\n```\n\n### Settings Explained\n\nEach of these settings items are going to be prompted during onboarding if not set. Here are some commands with regards to settings:\n\n```bash\nchen config # View all settings\nchen config get anthropic_api_key # Get specific setting, follows the JSON keys\nchen config set context_window 150000 # Set specific setting\n```\n\n### Sessions\n\nYou can also find your chat history in `~/.chen/sessions/` with each session as a subdirectory there. A typical session directory might look like this:\n\n```bash\nls -la ~/.chen/sessions/\ntotal 0\ndrwxr-xr-x@ 14 tista staff 448 Sep 7 23:07 .\ndrwxr-xr-x@ 5 tista staff 160 Sep 7 22:05 ..\ndrwxr-xr-x@ 4 tista staff 128 Sep 7 21:01 068bdba6-1b51-7fd5-8000-b37d1f0832ea\ndrwxr-xr-x@ 4 tista staff 128 Sep 7 21:02 068bdbab-2071-7c75-8000-2cb9c8158015\ndrwxr-xr-x@ 4 tista staff 128 Sep 7 21:04 068bdbb2-163e-7553-8000-e3ce5a060b30\ndrwxr-xr-x@ 4 tista staff 128 Sep 7 21:04 068bdbb3-bbca-76b9-8000-498755d91316\ndrwxr-xr-x@ 4 tista staff 128 Sep 7 21:05 068bdbb5-702c-7e57-8000-317c40048963\ndrwxr-xr-x@ 4 tista staff 128 Sep 7 21:09 068bdbc3-cff6-7ea4-8000-62576dfa2d1f\n```\n\nSession subdirectories are named with UUID v7 which are chronologically sorted. Within each session, you will find these files:\n\n```bash\nls -la ~/.chen/sessions/068bdba6-1b51-7fd5-8000-b37d1f0832ea \ntotal 160\ndrwxr-xr-x@ 4 tista staff 128 Sep 7 21:01 .\ndrwxr-xr-x@ 14 tista staff 448 Sep 7 23:07 ..\n-rw-r--r--@ 1 tista staff 74545 Sep 7 21:01 history.jsonl\n-rw-r--r--@ 1 tista staff 327 Sep 7 21:01 metadata.json\n```\n\nThe `history.jsonl` file contains the full conversation history in JSON Lines format, while `metadata.json` holds session metadata.\n\n### In-chat Commands\n\nWhile in a chat session with Chen, you can use the following commands:\n\n```\n/quit # Exit the chat session\n/exit # Exit the chat session\nCtrl+D # Exit the chat session\nCtrl+C # Exit the chat session supposedly but you have to press it twice, got some exception bubbling not right yet\n/resume # Resume a previous session, you will be shown a list of sessions to choose from\n```\n\n## Development\n\n### Chen Configuration System\n\nChen uses a sophisticated JSON-based configuration system with interactive onboarding:\n\n```bash\n# View current settings\nrye run chen config\n\n# Set individual values\nrye run chen config set anthropic_api_key \"sk-ant-...\"\nrye run chen config set context_window 150000\n\n# Manual onboarding\nrye run chen onboard\n\n# Reset all settings\nrye run chen reset\n```\n\nSettings are stored in `~/.chen/settings.json` with support for:\n- Anthropic, OpenAI, OpenRouter, and Tavily API keys\n- Configurable context window size\n- Automatic validation and type conversion\n\n### Environment Variables (Optional)\n\nEnvironment variables serve as defaults during onboarding:\n\n```bash\nexport ANTHROPIC_API_KEY=\"your-key-here\"\nexport OPENAI_API_KEY=\"your-key-here\"\nexport OPENROUTER_API_KEY=\"your-key-here\"\nexport TAVILY_API_KEY=\"your-key-here\"\n```\n\n## Architecture\n\n### Core Structure\n\n```\nsrc/\n\u251c\u2500\u2500 appclis/ # CLI applications\n\u2502 \u251c\u2500\u2500 chen.py # Chen agent with config system\n\u2502 \u251c\u2500\u2500 chief.py # Chief agent\n\u2502 \u2514\u2500\u2500 settings/ # Configuration management\n\u251c\u2500\u2500 libagentic/ # Core agent framework\n\u2502 \u251c\u2500\u2500 agents.py # Agent factory functions\n\u2502 \u251c\u2500\u2500 providers.py # Model provider configs\n\u2502 \u251c\u2500\u2500 prompts.py # System prompts\n\u2502 \u2514\u2500\u2500 tools/ # Agent tools and capabilities\n\u2514\u2500\u2500 libshared/ # Shared utilities\n \u2514\u2500\u2500 mongo.py # MongoDB base classes\n```\n\n### Technology Stack\n\n- **Pydantic AI**: Core agent framework with Logfire integration\n- **Typer + Rich**: Beautiful CLI interfaces with command groups\n- **Pydantic Settings**: Type-safe configuration management\n- **Beanie**: Async MongoDB ODM for persistence\n- **Tavily**: Web search API integration\n- **OpenRouter**: Multi-provider LLM access\n\n## Development\n\n### Code Quality\n\n```bash\n# Lint and format\nruff check . --fix\nruff format .\n\n# Type checking and final lint\nruff check .\n```\n\n### Testing\n\n```bash\n# Run tests (when implemented)\npytest\n\n# With coverage\npytest --cov=src\n```\n\n## Model Providers\n\n- **Default**: `deepseek/deepseek-chat-v3.1:free` via OpenRouter, `gpt-5` via OpenAI and `claude-sonnet-4-20250514` via Anthropic\n- **Supported**: All Anthropic, OpenAI, and OpenRouter models\n- **Configuration**: Interactive setup or individual config commands\n- **Fallbacks**: Automatic provider selection based on availability\n\n## License\n\n[MIT License](LICENSE)\n\n## Contributing\n\nContributions are welcome! Please open issues or pull requests for enhancements and bug fixes.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI agent framework with Chief and Chen, a conversational AI psychologist with web search and multi-provider support in your terminal.",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/tistaharahap/chief-ai",
"Issues": "https://github.com/tistaharahap/chief-ai/issues",
"Repository": "https://github.com/tistaharahap/chief-ai"
},
"split_keywords": [
"agent",
" ai",
" anthropic",
" assistant",
" chat",
" openai",
" openrouter",
" psychologist"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a0218d50c6498882cbe0d4455ca66f53be14829306ebe28bb945b3e398ebee88",
"md5": "a1c61b34b594d64e151c690566b82825",
"sha256": "9da73b9a8d6ece5634e82244e0dfcf909e897baef90b53b79db4fda1c0e5402b"
},
"downloads": -1,
"filename": "chief_ai-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a1c61b34b594d64e151c690566b82825",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 42257,
"upload_time": "2025-09-09T05:16:00",
"upload_time_iso_8601": "2025-09-09T05:16:00.198966Z",
"url": "https://files.pythonhosted.org/packages/a0/21/8d50c6498882cbe0d4455ca66f53be14829306ebe28bb945b3e398ebee88/chief_ai-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5888fac054bd523c1b293d273320228a63de7d3c4f900dbac985b7d7d0ff876b",
"md5": "6dc312445ba2d2c5f7e6c2fccc4ab220",
"sha256": "f464b8e0290384db6346cdf3a1eded02083231cfb131b88920ec802cb408e3fc"
},
"downloads": -1,
"filename": "chief_ai-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "6dc312445ba2d2c5f7e6c2fccc4ab220",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 100807,
"upload_time": "2025-09-09T05:16:02",
"upload_time_iso_8601": "2025-09-09T05:16:02.142705Z",
"url": "https://files.pythonhosted.org/packages/58/88/fac054bd523c1b293d273320228a63de7d3c4f900dbac985b7d7d0ff876b/chief_ai-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-09 05:16:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tistaharahap",
"github_project": "chief-ai",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "chief-ai"
}
