# Proto - ClickHouse AI Agent
> Natural language interface for ClickHouse databases
Proto is an intelligent CLI agent that allows you to interact with ClickHouse databases using natural language. Ask questions about your data, generate SQL queries, and get insights without writing complex SQL.
## Features
- 🤖 **AI-Powered**: Natural language interface powered by local or cloud AI models
- 📊 **Smart Analysis**: Automatic table analysis and data insights
- 🔍 **Query Generation**: Convert questions to optimized SQL queries
- 📈 **Data Visualization**: Generate charts and visualizations from your data
- ⚡ **Fast Setup**: One-command installation, no Python knowledge required
- 🔒 **Privacy-First**: Option to run completely locally with local AI models
- 🚀 **Cross-Platform**: Works on macOS (Intel/Apple Silicon), Linux, and Windows
- 📦 **Easy Installation**: Install via pipx, pip, or one-liner script
## Quick Start
### Install Proto
```bash
curl -fsSL https://proto.dev/install.sh | sh
```
### Start Using Proto
```bash
proto
```
Follow the interactive onboarding to configure your ClickHouse connection and AI provider.
## Installation Options
### Using pipx (Recommended)
```bash
pipx install proto-clickhouse-agent
```
### Using pip
```bash
pip install proto-clickhouse-agent
```
### One-liner (Legacy)
```bash
curl -fsSL https://proto.dev/install.sh | sh
```
## Usage Examples
```bash
# Start interactive chat
proto
# Execute a single query
proto query "Show me the top 10 users by activity"
# Analyze a specific table
proto analyze users
# Load data from a file
proto load-data users.csv users
```
## Configuration
Proto supports multiple AI providers:
- **Local LLM**: Run completely offline with local models
- **Local LLM**: Built-in ClickHouse AI model (no API keys needed)
- **OpenAI**: Direct OpenAI API integration
Configuration is stored in `~/.config/proto/proto-config.json`.
## System Requirements
- macOS 10.15+ or Linux
- ClickHouse database (local or cloud)
- AI provider (Local LLM built-in)
- ~3.5GB free space for AI model (first run)
## Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/yourusername/proto.git
cd proto
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Run Proto
python main.py
```
### Building Standalone Binaries
```bash
./build_installers.sh
```
This creates platform-specific binaries in the `builds/` directory.
## Architecture
```
proto/
├── agent/ # Core AI agent logic
├── config/ # Configuration management
├── providers/ # AI provider integrations
├── tools/ # Database and data tools
├── ui/ # User interface components
├── utils/ # Utility functions
└── main.py # Entry point
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- 📖 [Documentation](https://proto.dev)
- 🐛 [Report Issues](https://github.com/yourusername/proto/issues)
- 💬 [Discussions](https://github.com/yourusername/proto/discussions)
## Roadmap
- [ ] Web interface
- [ ] More AI providers
- [ ] Advanced data visualization
- [ ] Query optimization suggestions
- [ ] Multi-database support
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/proto",
"name": "proto-clickhouse-agent",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Proto Team <team@proto.dev>",
"keywords": "clickhouse, ai, agent, database, sql, nlp",
"author": "Proto Team",
"author_email": "Proto Team <team@proto.dev>",
"download_url": "https://files.pythonhosted.org/packages/89/e8/9f36179eb8a3b0eeded53e259639f3a960323c86ced86de329499fbd7c87/proto_clickhouse_agent-1.0.1.tar.gz",
"platform": null,
"description": "# Proto - ClickHouse AI Agent\n\n> Natural language interface for ClickHouse databases\n\nProto is an intelligent CLI agent that allows you to interact with ClickHouse databases using natural language. Ask questions about your data, generate SQL queries, and get insights without writing complex SQL.\n\n## Features\n\n- \ud83e\udd16 **AI-Powered**: Natural language interface powered by local or cloud AI models\n- \ud83d\udcca **Smart Analysis**: Automatic table analysis and data insights\n- \ud83d\udd0d **Query Generation**: Convert questions to optimized SQL queries\n- \ud83d\udcc8 **Data Visualization**: Generate charts and visualizations from your data\n- \u26a1 **Fast Setup**: One-command installation, no Python knowledge required\n- \ud83d\udd12 **Privacy-First**: Option to run completely locally with local AI models\n- \ud83d\ude80 **Cross-Platform**: Works on macOS (Intel/Apple Silicon), Linux, and Windows\n- \ud83d\udce6 **Easy Installation**: Install via pipx, pip, or one-liner script\n\n## Quick Start\n\n### Install Proto\n\n```bash\ncurl -fsSL https://proto.dev/install.sh | sh\n```\n\n### Start Using Proto\n\n```bash\nproto\n```\n\nFollow the interactive onboarding to configure your ClickHouse connection and AI provider.\n\n## Installation Options\n\n### Using pipx (Recommended)\n```bash\npipx install proto-clickhouse-agent\n```\n\n### Using pip\n```bash\npip install proto-clickhouse-agent\n```\n\n### One-liner (Legacy)\n```bash\ncurl -fsSL https://proto.dev/install.sh | sh\n```\n\n## Usage Examples\n\n```bash\n# Start interactive chat\nproto\n\n# Execute a single query\nproto query \"Show me the top 10 users by activity\"\n\n# Analyze a specific table\nproto analyze users\n\n# Load data from a file\nproto load-data users.csv users\n```\n\n## Configuration\n\nProto supports multiple AI providers:\n\n- **Local LLM**: Run completely offline with local models\n- **Local LLM**: Built-in ClickHouse AI model (no API keys needed)\n- **OpenAI**: Direct OpenAI API integration\n\nConfiguration is stored in `~/.config/proto/proto-config.json`.\n\n## System Requirements\n\n- macOS 10.15+ or Linux\n- ClickHouse database (local or cloud)\n- AI provider (Local LLM built-in)\n- ~3.5GB free space for AI model (first run)\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/proto.git\ncd proto\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run Proto\npython main.py\n```\n\n### Building Standalone Binaries\n\n```bash\n./build_installers.sh\n```\n\nThis creates platform-specific binaries in the `builds/` directory.\n\n## Architecture\n\n```\nproto/\n\u251c\u2500\u2500 agent/ # Core AI agent logic\n\u251c\u2500\u2500 config/ # Configuration management\n\u251c\u2500\u2500 providers/ # AI provider integrations\n\u251c\u2500\u2500 tools/ # Database and data tools\n\u251c\u2500\u2500 ui/ # User interface components\n\u251c\u2500\u2500 utils/ # Utility functions\n\u2514\u2500\u2500 main.py # Entry point\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- \ud83d\udcd6 [Documentation](https://proto.dev)\n- \ud83d\udc1b [Report Issues](https://github.com/yourusername/proto/issues)\n- \ud83d\udcac [Discussions](https://github.com/yourusername/proto/discussions)\n\n## Roadmap\n\n- [ ] Web interface\n- [ ] More AI providers\n- [ ] Advanced data visualization\n- [ ] Query optimization suggestions\n- [ ] Multi-database support\n",
"bugtrack_url": null,
"license": null,
"summary": "ClickHouse AI Agent - Natural language interface for ClickHouse databases",
"version": "1.0.1",
"project_urls": {
"Changelog": "https://github.com/vishprometa/proto/releases",
"Documentation": "https://proto.dev",
"Homepage": "https://github.com/vishprometa/proto",
"Issues": "https://github.com/vishprometa/proto/issues",
"Repository": "https://github.com/vishprometa/proto"
},
"split_keywords": [
"clickhouse",
" ai",
" agent",
" database",
" sql",
" nlp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5275e0ac96293ceed966dacb2547eed7876ee4d9eeadc74ebf069c1f32cae5e2",
"md5": "10507f55bdd28929624b1e90c4c64059",
"sha256": "42e2ec64cb26ecfcb310ad0240f707f7b5db8d03e00e2bb34d07ab85cbd6e3b2"
},
"downloads": -1,
"filename": "proto_clickhouse_agent-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "10507f55bdd28929624b1e90c4c64059",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 41303,
"upload_time": "2025-08-28T17:45:30",
"upload_time_iso_8601": "2025-08-28T17:45:30.792359Z",
"url": "https://files.pythonhosted.org/packages/52/75/e0ac96293ceed966dacb2547eed7876ee4d9eeadc74ebf069c1f32cae5e2/proto_clickhouse_agent-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "89e89f36179eb8a3b0eeded53e259639f3a960323c86ced86de329499fbd7c87",
"md5": "3ccd61c383ce9056fda435abad6c7670",
"sha256": "eba92c54a7efe91d4a85a3b706d16b9dc42a8242e919e08e10ddd405dfd3ab89"
},
"downloads": -1,
"filename": "proto_clickhouse_agent-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "3ccd61c383ce9056fda435abad6c7670",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 38409,
"upload_time": "2025-08-28T17:45:32",
"upload_time_iso_8601": "2025-08-28T17:45:32.742285Z",
"url": "https://files.pythonhosted.org/packages/89/e8/9f36179eb8a3b0eeded53e259639f3a960323c86ced86de329499fbd7c87/proto_clickhouse_agent-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 17:45:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "proto",
"github_not_found": true,
"lcname": "proto-clickhouse-agent"
}
JSON
