Metadata-Version: 2.4
Name: zeocloud
Version: 0.1.4
Summary: Ask your codebase anything — locally, privately, powerfully
Author-email: Manish Sharma <mdashsharma95@gmail.com>
License: MIT License
        
        Copyright (c) 2024 Manish Sharma
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/manishdashsharma/Zeocloud
Project-URL: Repository, https://github.com/manishdashsharma/Zeocloud
Project-URL: Issues, https://github.com/manishdashsharma/Zeocloud/issues
Keywords: ai,cli,rag,codebase,ollama,local-ai,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: qdrant-client>=1.9.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pathspec>=0.12.1
Requires-Dist: pydantic>=2.7.0
Requires-Dist: tiktoken>=0.7.0
Dynamic: license-file

<div align="center">

<pre>
███████╗███████╗ ██████╗  ██████╗██╗      ██████╗ ██╗   ██╗██████╗
╚══███╔╝██╔════╝██╔═══██╗██╔════╝██║     ██╔═══██╗██║   ██║██╔══██╗
  ███╔╝ █████╗  ██║   ██║██║     ██║     ██║   ██║██║   ██║██║  ██║
 ███╔╝  ██╔══╝  ██║   ██║██║     ██║     ██║   ██║██║   ██║██║  ██║
███████╗███████╗╚██████╔╝╚██████╗███████╗╚██████╔╝╚██████╔╝██████╔╝
╚══════╝╚══════╝ ╚═════╝  ╚═════╝╚══════╝ ╚═════╝  ╚═════╝ ╚═════╝
</pre>

**Ask your codebase anything — locally, privately, powerfully.**

[![Version](https://img.shields.io/badge/version-v0.1.4-orange.svg)](https://github.com/manishdashsharma/Zeocloud)
[![PyPI](https://img.shields.io/pypi/v/zeocloud.svg)](https://pypi.org/project/zeocloud/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://python.org)
[![uv](https://img.shields.io/badge/managed%20by-uv-purple.svg)](https://github.com/astral-sh/uv)
[![Ollama](https://img.shields.io/badge/powered%20by-Ollama-black.svg)](https://ollama.com)
[![Qdrant](https://img.shields.io/badge/vector%20db-Qdrant-red.svg)](https://qdrant.tech)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

</div>

---

## What is Zeocloud?

Zeocloud is an open-source CLI tool that lets you have natural conversations with any codebase — in **English or Hindi** — without sending a single byte to the cloud.

It indexes your code locally, stores vectors in a local Qdrant database, and uses Ollama to run language models on your own hardware. No API keys. No subscriptions. No privacy concerns.

```bash
$ zeocloud

 ⚡ buddy is listening

  1.  Ask a question about your code
  2.  Index a new project

  You → buddy: auth middleware kahan hai aur kaise kaam karta hai?

  🤖 buddy:

  The auth middleware lives in `src/middleware/auth.js` (lines 12–48).
  It validates JWT tokens using the `jsonwebtoken` library...
```

---

## Features

- **100% local** — Ollama + Qdrant, zero cloud calls
- **Smart hardware detection** — suggests the right model for your machine (RAM, GPU, Apple Silicon)
- **Bilingual** — ask questions in English or Hindi, get answers in the same language
- **Conversation memory** — follow-up questions use previous context
- **Any language** — Python, JS, TS, Go, Rust, Java, C++, and 40+ more
- **Gitignore-aware** — skips `node_modules`, build artifacts, binary files
- **Safety guardrails** — blocks indexing of system directories, warns about `.env` files
- **Session logs** — every conversation is saved to `~/.zeocloud/sessions/`
- **Beautiful CLI** — Rich-powered colorful terminal with progress bars, spinners, tables
- **`zeocloud status`** — health check for all services at a glance

---

## Requirements

| Tool | Version | Purpose |
|------|---------|---------|
| [Python](https://python.org) | 3.11+ | Runtime |
| [Ollama](https://ollama.com/download) | latest | Local LLM |
| [Docker](https://www.docker.com/get-started) | latest | Vector database |

---

## Quick Start

**Option 1 — PyPI (recommended):**

```bash
pipx install zeocloud
# or
uv tool install zeocloud
```

**Option 2 — Clone:**

```bash
git clone https://github.com/manishdashsharma/Zeocloud.git
cd Zeocloud
bash scripts/install.sh
```

Then run setup:

```bash
zeocloud install
```

After setup, just run:

```bash
zeocloud
```

Name your agent, point it at a project, and start asking questions.

---

## Usage

### `zeocloud install`

Interactive setup wizard that:
1. Detects your CPU, RAM, and GPU
2. Recommends the best local model for your hardware
3. Pulls the model via Ollama (downloads once, stored locally)
4. Starts Qdrant vector database in Docker
5. Runs health checks on all services

```
$ zeocloud install

  System Detection
  ┌──────────────┬──────────────────────────────────┐
  │ Property     │ Value                            │
  ├──────────────┼──────────────────────────────────┤
  │ OS           │ Darwin                           │
  │ CPU          │ Apple M3 Pro                     │
  │ CPU Cores    │ 11                               │
  │ RAM          │ 18.0 GB                          │
  │ Chip         │ Apple Silicon (unified memory)   │
  └──────────────┴──────────────────────────────────┘

  Recommended: llama3.1:8b  ★★★★☆ Great
```

### `zeocloud`

```
$ zeocloud

  ╔═══════════════════════════════════════╗
  ║           Z E O C L O U D            ║
  ║    Ask your codebase anything         ║
  ╚═══════════════════════════════════════╝

  ── Name Your Agent ──────────────────────

  Give your AI assistant a name — something that feels right to you.
  Examples: buddy, sage, aria, max, nova, cody, orion

  Agent name [buddy]: aria

  ✓  aria is your Zeocloud agent. Let's go!

  ⚡  aria is listening

  1.  Ask a question about your code
  2.  Index a new project
  3.  View indexed projects
  4.  Remove a project
  5.  Exit

  Choice [1]:
```

On **first run**, you name your AI agent — call it anything you like. That name is saved and used in every session going forward. Then the interactive menu appears:

- **Ask a question** — select a project and ask anything in English or Hindi
- **Index a new project** — provide a path, Zeocloud indexes all source files
- **View projects** — table of all indexed projects with stats
- **Remove a project** — deletes vectors from Qdrant and config entry

### `zeocloud status`

Check health of all services at a glance:

```
  Services
  ┌─────────┬──────────────────────┬─────────────────┐
  │ Service │ Address              │ Status          │
  ├─────────┼──────────────────────┼─────────────────┤
  │ Ollama  │ http://localhost:... │ ✓  Running      │
  │ Qdrant  │ localhost:6333       │ ✓  Running      │
  └─────────┴──────────────────────┴─────────────────┘
```

---

## How It Works

```
Your Code
    │
    ▼
  Indexer          Walk repo → skip ignored dirs → chunk files (400 tokens, 80 overlap)
    │
    ▼
  Embedder         nomic-embed-text via Ollama → 768-dim vectors
    │
    ▼
  Qdrant           Store in collection zeocloud_{project} (cosine similarity)
    │
    ▼  ──── at query time ────
    │
  Embedder         Embed your question with the same model
    │
    ▼
  Retriever        Top-8 most similar chunks from Qdrant
    │
    ▼
  LLM              Build prompt with context → stream answer via Ollama
    │
    ▼
  Terminal         Streamed tokens, then source file citations
```

---

## Model Selection Guide

Zeocloud auto-detects your hardware and picks the best model:

| Your Machine | Suggested Model | Quality |
|-------------|----------------|---------|
| < 8 GB RAM | `phi3.5:3.8b` | ★★☆☆☆ Lite |
| 8–16 GB RAM | `llama3.2:3b` | ★★★☆☆ Good |
| 16+ GB RAM | `llama3.1:8b` | ★★★★☆ Great |
| Apple Silicon 16GB+ | `llama3.1:8b` | ★★★★☆ Great |
| Apple Silicon 32GB+ | `llama3.3:70b` | ★★★★★ Best |
| NVIDIA GPU ≥ 8GB VRAM | `llama3.1:8b` | ★★★★☆ Great |
| NVIDIA GPU ≥ 24GB VRAM | `llama3.3:70b` | ★★★★★ Best |

> **Hindi support:** `llama3.1:8b` and above handle Hindi well. Lighter models (3B and below) have limited Hindi understanding.

---

## Project Layout

```
zeocloud/
├── src/                     ← Package root (maps to zeocloud.*)
│   ├── cli/                 ← Commands: main, install, chat
│   ├── config/              ← Settings model + persistence
│   ├── llm/                 ← Ollama LLM client (generate, pull, status)
│   ├── embedder/            ← Embedding client (nomic-embed-text)
│   ├── indexer/             ← File traversal + token-based chunking
│   ├── retriever/           ← Qdrant vector store + RAG pipeline
│   └── utils/               ← Display (Rich), system detection, safety, session
├── docker/                  ← Qdrant docker-compose (bundled)
├── docs/                    ← Architecture docs
├── sessions/                ← (gitignored) session log output during dev
├── tests/                   ← pytest unit tests
└── scripts/install.sh       ← bootstrap script
```

---

## Session Logs

After every chat session, Zeocloud writes a structured markdown log to `~/.zeocloud/sessions/`:

```
~/.zeocloud/sessions/
  2024-01-15_14-32-07.md
  2024-01-16_09-45-22.md
```

Each log contains:
- Session summary (agent, duration, question count)
- List of projects queried and indexed
- Full Q&A transcript

---

## Privacy

Zeocloud is designed from the ground up to keep your code private:

- **No cloud calls** — Ollama and Qdrant both run on `localhost`
- **No telemetry** — zero analytics, no crash reporting, nothing leaves your machine
- **No accounts** — no sign-up, no API keys
- **Vectors are local** — stored in a Docker volume on your machine
- **Config is local** — `~/.zeocloud/config.json`, readable only by you

---

## Development

```bash
git clone https://github.com/manishdashsharma/Zeocloud.git
cd Zeocloud
uv sync              # install deps + package in editable mode
uv run zeocloud install
uv run zeocloud
```

### Running tests

```bash
uv run pytest tests/ -v
```

### Linting

```bash
uv run ruff check src/
uv run ruff format src/
uv run mypy src/
```

---

## Contributing

Contributions are very welcome! This is a community project.

1. Fork the repository
2. Create a feature branch (`git checkout -b feat/your-feature`)
3. Write tests for your changes
4. Run `uv run ruff check src/ && uv run pytest tests/`
5. Open a pull request

Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting your first PR.

### Ideas for contributions

- [ ] Incremental reindexing (only re-embed changed files)
- [ ] `zeocloud config` command to update settings from CLI
- [ ] Support for remote Ollama / Qdrant instances
- [ ] Export session logs to different formats
- [ ] File-level filtering when asking questions
- [ ] VS Code extension

---

## FAQ

**Q: How is this different from GitHub Copilot or Cursor?**  
A: Those send your code to external servers. Zeocloud runs entirely on your machine — your code never leaves.

**Q: Does it work on Windows?**  
A: Not officially tested yet. Docker and Ollama support Windows, so it should work. PRs welcome!

**Q: Can I use a different LLM provider?**  
A: Currently Ollama-only. Support for other local providers is on the roadmap.

**Q: How do I update the model after install?**  
A: Run `zeocloud install` again and choose a different model when prompted.

**Q: My Hindi answers aren't great. What model should I use?**  
A: Use `llama3.1:8b` or larger. Smaller models have limited multilingual support.

---

## Author

<div align="center">

<a href="https://www.manishdashsharma.com/"><b>Manish Dash Sharma</b></a>
<br />
<sub>Senior Software Engineer</sub>
<br /><br />
Architecting AI-powered systems that scale.<br />
From GenAI integrations to full-stack solutions — turning complex problems into elegant code.
<br /><br />
<a href="https://www.manishdashsharma.com/">🌐 Website</a> · <a href="https://github.com/manishdashsharma">GitHub</a>

</div>

---

## License

MIT © [Manish Dash Sharma](https://www.manishdashsharma.com/)

---

<div align="center">

Built with ❤️ for the developer community · 100% local · 100% yours

**[⭐ Star this repo](https://github.com/manishdashsharma/Zeocloud)** if Zeocloud helps you understand code faster!

</div>
