Metadata-Version: 2.4
Name: gitops-by-veera
Version: 1.0.1
Summary: Conversational autonomous Git and GitHub operations coordinator using Groq-hosted LLMs.
Project-URL: Homepage, https://github.com/vkprince6/gitops-by-veera
Project-URL: Repository, https://github.com/vkprince6/gitops-by-veera
Project-URL: Bug Tracker, https://github.com/vkprince6/gitops-by-veera/issues
Author: Veera
License: MIT License
        
        Copyright (c) 2026 Veerakumar C B
        
        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.
License-File: LICENSE
Keywords: automation,cli,git,github,groq,llm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.1.7
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: typing-extensions>=4.12.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: build>=0.10.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# gitops-by-veera

A production-ready, security-hardened, conversational autonomous Git and GitHub operations coordinator. Convert natural language into safe, validated local Git commands and GitHub REST API calls — powered by Groq-hosted LLMs.

---

## Features

- **Natural language to Git/GitHub actions** — describe what you want, GitOps plans and executes it
- **Dual-domain operations** — local Git commands and GitHub cloud API calls in a single pipeline
- **Security-first architecture** — command injection prevention, path traversal blocking, shell injection defense, and prompt injection resistance
- **Model cascading** — automatic fallback across three Groq-hosted model tiers
- **Self-healing remediation** — failed operations trigger AI-generated fix suggestions (capped at 2 cycles)
- **Direct evaluation bypass** — trivial commands (`git status`, `git diff`, `git log`) skip the LLM entirely for speed
- **Structured JSON contracts** — all LLM output is parsed into strict Pydantic models
- **Session telemetry** — detailed execution metrics available with `--debug`
- **Colab/Jupyter compatible** — runs in notebooks, cloud runtimes, and local terminals

---

## Installation

### From PyPI

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

### From source

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

### Google Colab

```python
!pip install gitops-by-veera
import subprocess
subprocess.run(["git-ops", "setup"])
```

---

## Credentials & Security

GitOps requires two API credentials:

| Credential | Environment Variable | Description |
|---|---|---|
| Groq API Key | `GROQ_API_KEY` | From [console.groq.com](https://console.groq.com) |
| GitHub Token | `GITHUB_TOKEN` | Fine-grained PAT with repo read/write scopes |

> **IMPORTANT:** Classic admin GitHub tokens are strictly prohibited.
> You MUST use [fine-grained Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)
> scoped to specific repositories with only the permissions required for your workflow.

Credentials are stored at `~/.gitops_by_veera_config.json` with `chmod 600` permissions. They are **never** logged or printed to the terminal.

---

## Setup

```bash
git-ops setup
```

You will be prompted (via `getpass`) for your Groq API key and GitHub token. Alternatively, set environment variables:

```bash
export GROQ_API_KEY="gsk_..."
export GITHUB_TOKEN="github_pat_..."
```

---

## Usage

### Run a natural language pipeline

```bash
git-ops run "Stage all files, commit with message 'feat: initial setup', and push to origin main"
```

### Dry-run (plan and validate only — no execution)

```bash
git-ops run "Create a branch called feature-xyz and push it" --dry-run
```

### Debug mode with telemetry

```bash
git-ops run "Open a PR from feature-xyz to main with title 'New Feature'" --debug
```

---

## Supported Operations

### Local Git

| Operation | Risk Level |
|---|---|
| `git status`, `git diff`, `git log` | Safe |
| `git add`, `git commit`, `git fetch`, `git pull` | Safe |
| `git push`, `git branch`, `git checkout`, `git switch` | Safe |
| `git reset --hard`, `git clean -fd`, `git push --force` | Warning — requires confirmation |
| `git rebase`, `git cherry-pick`, `git stash clear` | Warning — requires confirmation |
| `git filter-branch`, `git reflog expire`, `git gc --prune=now` | **Blocked** |

### GitHub Cloud (via REST API)

- Create repositories (`/user/repos`, `/orgs/{org}/repos`)
- Manage branches and refs (`/repos/{owner}/{repo}/git/refs`)
- Open, list, and update Pull Requests (`/repos/{owner}/{repo}/pulls`)
- Merge Pull Requests (`/repos/{owner}/{repo}/pulls/{number}/merge`)
- Create and update Issues (`/repos/{owner}/{repo}/issues`)
- Trigger GitHub Actions workflows (`/repos/{owner}/{repo}/actions/workflows/{id}/dispatches`)

> All `DELETE` requests and repository-level destructive endpoints are strictly blocked.

---

## Example Workflows

```bash
# View repository status (bypasses LLM entirely for speed)
git-ops run "show status"

# Full branch + commit + PR workflow
git-ops run "Create branch feature-auth, commit staged files with message 'feat: add auth', push, and open a PR to main"

# Create a GitHub issue
git-ops run "Create an issue titled 'Bug: login fails on mobile' with a description"

# Trigger a workflow dispatch
git-ops run "Trigger the deploy.yml workflow on the main branch"
```

---

## Google Colab Integration

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

import os
os.environ["GROQ_API_KEY"] = "gsk_..."      # or use Colab secrets
os.environ["GITHUB_TOKEN"] = "github_pat_..."

import subprocess
result = subprocess.run(
    ["git-ops", "run", "show git status", "--dry-run"],
    capture_output=True, text=True
)
print(result.stdout)
```

---

## Architecture

```
User prompt
    │
    ├── Direct Evaluation Router (regex bypass for trivial commands)
    │       └── Returns plan immediately, skips LLM
    │
    └── LLM Cascade (Groq API)
            ├── Tier 1: openai/gpt-oss-120b
            ├── Tier 2: openai/gpt-oss-20b
            └── Tier 3: llama-3.1-8b-instant (also used for remediation)
                    │
                    └── Pydantic-validated ExecutionPlan
                            │
                            └── Multi-stage Validator
                                    ├── Binary whitelist enforcement
                                    ├── Shell injection detection
                                    ├── Path traversal blocking
                                    ├── GitHub endpoint whitelist
                                    └── Payload field sanitization
                                            │
                                            └── Sequential Executor
                                                    ├── Local: subprocess.run (shell=False)
                                                    └── Cloud: requests → GitHub REST API
                                                            │
                                                            └── Self-Healing Remediation (≤2 cycles)
```

---

## Development

```bash
pip install -e ".[dev]"

# Run tests
pytest --cov=src/gitops_by_veera --cov-report=term-missing

# Type checking
mypy src/

# Linting
ruff check src/ tests/
```

---

## License

MIT License — see [LICENSE](LICENSE).

---

## Security

See [SECURITY.md](SECURITY.md) for the full security architecture and responsible disclosure policy.
