Metadata-Version: 2.4
Name: gitops-by-veera
Version: 1.0.3
Summary: Natural language → Git & GitHub operations, with a beautiful web UI
Author: Veera
License: MIT
Project-URL: Homepage, https://github.com/veera/gitops-by-veera
Project-URL: Issues, https://github.com/veera/gitops-by-veera/issues
Keywords: git,github,gitops,llm,groq,cli,automation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: click>=8.1.0
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: httpx; extra == "dev"

# GitOps by Veera

**Turn natural language into Git and GitHub operations — with a beautiful web UI.**

[![PyPI version](https://badge.fury.io/py/gitops-by-veera.svg)](https://pypi.org/project/gitops-by-veera/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## What is it?

`gitops-by-veera` is an AI-powered GitOps agent that understands plain English and converts it into safe Git commands and GitHub API calls. It launches a polished dark-themed web UI where you can:

- Create GitHub repositories with a single sentence
- Stage, commit, and push code conversationally
- Open pull requests and create issues by describing what you want
- Preview every action in **Dry Run** mode before executing it live
- Use your **voice** to speak commands directly

Powered by **Groq** (free, fast LLM inference) and the **GitHub REST API**.

---

## Quick Start

### 1. Install

```bash
pip install gitops-by-veera
```

### 2. Get your API keys

| Key | Where to get it | Notes |
|---|---|---|
| **Groq API Key** | [console.groq.com](https://console.groq.com) → API Keys | Free tier available |
| **GitHub Token** | [github.com/settings/tokens](https://github.com/settings/tokens) → Classic token | Enable `repo` scope |

### 3. Launch

```python
import gitops_by_veera

gitops_by_veera.launch()
```

The web UI opens in your browser. Enter your keys in **Settings (⚙)** and start typing commands.

---

## Installation Options

```bash
# Latest stable
pip install gitops-by-veera

# Specific version
pip install gitops-by-veera==1.0.3

# Upgrade to latest
pip install --upgrade gitops-by-veera
```

**Requirements:** Python 3.10 or higher. No other system dependencies.

---

## Usage

### Python API

```python
import gitops_by_veera

# Launch with default settings (auto-detect port, open browser)
gitops_by_veera.launch()

# Custom port
gitops_by_veera.launch(port=8080)

# Server only — do not open a browser window
gitops_by_veera.launch(open_browser=False)

# Suppress uvicorn logs
gitops_by_veera.launch(log_level="error")

# Check the version
print(gitops_by_veera.__version__)   # → "1.0.3"
```

### Command-line interface

```bash
# Launch the web UI (same as launch())
gitops serve

# Run a single command from the terminal (no UI)
gitops run "Create a branch called feature-login"

# Store credentials on disk so you don't have to type them every time
gitops setup

# Options
gitops serve --port 9000 --no-browser
gitops run "stage all and commit 'fix: typo'" --dry-run
```

### Environment-variable credentials (CI/scripts)

```bash
export GROQ_API_KEY="gsk_..."
export GITHUB_TOKEN="ghp_..."
gitops run "Create a private repo named my-project"
```

---

## Environment Support

| Environment | Works? | Notes |
|---|---|---|
| Local machine | ✅ | Opens browser automatically |
| Jupyter Notebook | ✅ | Prints the URL; paste it in a new tab |
| Google Colab | ✅ | Displays an inline iframe automatically |
| Replit | ✅ | Reads `$PORT`, prints the public proxy URL |
| Docker / cloud VM | ✅ | Bind to `0.0.0.0`, expose port externally |
| VS Code devcontainer | ✅ | Port-forwarding handled by VS Code |

### Docker example

```dockerfile
FROM python:3.11-slim
RUN pip install gitops-by-veera
EXPOSE 7860
CMD ["python", "-c", \
  "import os, uvicorn; from gitops_by_veera.server import app; \
  uvicorn.run(app, host='0.0.0.0', port=int(os.environ.get('PORT', 7860)))"]
```

### Running as a persistent server (recommended for production)

When you need the process to stay alive without a main-thread loop, run uvicorn directly instead of using `launch()`:

```python
# server.py
import os
import uvicorn
from gitops_by_veera.server import app

port = int(os.environ.get("PORT", 7860))
print(f"GitOps by Veera → http://localhost:{port}")
uvicorn.run(app, host="0.0.0.0", port=port)
```

```bash
python server.py
# or
PORT=8000 python server.py
```

### Jupyter Notebook

```python
import gitops_by_veera

url = gitops_by_veera.launch(open_browser=False)
print(f"Open: {url}")
# Keep the kernel alive — the server runs in a background daemon thread
```

### Google Colab

```python
!pip install gitops-by-veera -q

import gitops_by_veera
gitops_by_veera.launch()  # shows an inline iframe automatically
```

---

## Voice Input

The 🎤 voice button in the web UI uses the browser's built-in **Web Speech API**.

| Browser | Voice support |
|---|---|
| Chrome (desktop & Android) | ✅ Full support |
| Edge (desktop) | ✅ Full support |
| Safari 17+ (macOS/iOS) | ⚠ Partial — may need explicit permission |
| Firefox | ❌ Not supported (Web Speech API not available) |

**Troubleshooting voice:**

- **"Microphone access denied"** — click the lock/camera icon in the address bar → allow microphone, then refresh
- **"Not supported"** — switch to Chrome or Edge
- **Works locally but not on a remote server** — Web Speech API requires HTTPS (or `localhost`). Use a reverse proxy with TLS, or run locally
- **No speech detected** — try again; speak clearly within 5 seconds of clicking 🎤

---

## How It Works

```
You type: "Create a private repo named demo and push my local code"
          ↓
     [Groq LLM] — plans a sequence of operations as structured JSON
          ↓
  Execution Plan:
    1. [cloud] POST /user/repos  { name: "demo", private: true }
    2. [local] git remote add origin git@github.com:you/demo.git
    3. [local] git push --set-upstream origin main
          ↓
  Validator — checks security rules, blocks dangerous operations
          ↓
  Dry Run preview (default) OR Live execution
          ↓
  Results displayed in the chat UI with full output
```

### Security model

- **Dry Run by default** — nothing executes until you toggle it off
- **Whitelist-only** — only pre-approved GitHub API endpoints are allowed
- **No DELETE** — repository deletion and destructive cloud operations are blocked
- **Path traversal protection** — local file paths are validated against the repo root
- **Shell injection prevention** — commands run via `subprocess` with `shell=False`
- **Payload sanitization** — unknown fields are stripped from API payloads

---

## Configuration

### Port resolution order

1. `port` argument to `launch()` or `gitops serve --port`
2. `$PORT` environment variable
3. Default: `7860`

### Credential storage

Credentials can be provided in three ways (checked in priority order):

1. **Environment variables** — `GROQ_API_KEY` and `GITHUB_TOKEN`
2. **Config file** — stored by `gitops setup` at `~/.gitops_by_veera_config.json` (chmod 600)
3. **UI settings** — entered in the Settings modal, saved to browser `localStorage`

---

## REST API

The server exposes two endpoints for programmatic/headless use:

### `GET /api/health`

```json
{ "status": "ok", "version": "1.0.3" }
```

### `POST /api/run`

**Request body:**

```json
{
  "prompt": "Create a private repo named demo",
  "groq_api_key": "gsk_...",
  "github_token": "ghp_...",
  "repo_path": "/path/to/local/repo",
  "dry_run": true
}
```

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `prompt` | string | ✅ | — | Natural language command |
| `groq_api_key` | string | ✅ | — | Groq API key |
| `github_token` | string | ✅ | — | GitHub personal access token |
| `repo_path` | string | ❌ | cwd | Path to local git repo for local operations |
| `dry_run` | boolean | ❌ | `true` | If true, plan is returned but nothing executes |

**Response:**

```json
{
  "plan": [
    {
      "index": 0,
      "type": "cloud",
      "method": "POST",
      "endpoint": "/user/repos",
      "payload": { "name": "demo", "private": true },
      "risk_level": "safe",
      "reason": "Creates a new private GitHub repository."
    }
  ],
  "warnings": [],
  "results": [
    {
      "operation_index": 0,
      "operation_type": "cloud",
      "success": true,
      "stdout": "{ \"id\": 123456, \"full_name\": \"you/demo\", ... }",
      "stderr": "",
      "error_message": ""
    }
  ],
  "mode": "DRY-RUN",
  "metrics": {
    "active_model": "llama-3.3-70b-versatile",
    "total_llm_calls": 1,
    "duration": 1.23
  }
}
```

---

## Example Commands

### GitHub Cloud

```
Create a private repo named my-api in my account
Create a public repo named my-project with description 'Demo project'
Open a PR from feature-branch to main with title 'Add authentication'
Create an issue titled 'Bug: login fails' in repo myorg/myrepo
```

### Local Git

```
Stage all files and commit with message 'feat: initial setup'
Create a branch called feature-xyz
Push to origin main
Show the last 10 commits
git status
git diff
```

### Pipelines (multi-step)

```
Stage all files, commit with message 'first commit', create a private repo named demo, push to it
Create a branch called hotfix, commit all changes with message 'fix: critical bug', push the branch
```

---

## Changelog

### 1.0.3
- Fixed voice input: per-error messages (`not-allowed`, `no-speech`, `network`), no accidental auto-send on error, try/catch on `rec.start()`, graceful message for unsupported browsers
- Added CORS middleware so the server works behind any proxy or cross-origin client
- Dynamic version badge in UI — fetched live from `/api/health`, never stale
- Improved `launch()`: explicit `$PORT` env-var support, better Replit / Colab / local detection, named daemon thread
- Version injected server-side into HTML template via string replacement

### 1.0.2
- Model cascade improvements and fallback hardening
- Validator endpoint whitelist expanded

### 1.0.0
- Initial public release

---

## Development

```bash
git clone https://github.com/veera/gitops-by-veera
cd gitops-by-veera
pip install -e ".[dev]"

# Run the dev server with auto-reload
uvicorn gitops_by_veera.server:app --reload --port 7860

# Run tests
pytest
```

---

## License

MIT — see [LICENSE](LICENSE).

---

## Author

Built by **Veera**. Issues and pull requests welcome on [GitHub](https://github.com/veera/gitops-by-veera).
