Metadata-Version: 2.4
Name: vibewithai
Version: 1.1.0
Summary: The intelligent developer SDK for Python — AI that performs engineering tasks, not a chat wrapper.
Project-URL: Homepage, https://github.com/ragulraj-d/vibewithai
Project-URL: Documentation, https://github.com/ragulraj-d/vibewithai/tree/main/docs
Project-URL: Repository, https://github.com/ragulraj-d/vibewithai
Project-URL: Changelog, https://github.com/ragulraj-d/vibewithai/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/ragulraj-d/vibewithai/issues
Project-URL: Decision records, https://github.com/ragulraj-d/vibewithai/tree/main/docs/architecture/adr
Project-URL: Security policy, https://github.com/ragulraj-d/vibewithai/blob/main/SECURITY.md
Author-email: ragulraj-d <raguldhamu007@gmail.com>
License: MIT License
        
        Copyright (c) 2026 ragulraj-d
        
        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: ai,code-quality,code-review,developer-tools,llm,refactoring,sarif,sdk,security,static-analysis
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 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: bandit>=1.7
Requires-Dist: httpx>=0.27
Requires-Dist: libcst>=1.4
Requires-Dist: platformdirs>=4.2
Requires-Dist: radon>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: ruff>=0.5
Requires-Dist: typer>=0.12
Provides-Extra: analysis
Provides-Extra: dev
Requires-Dist: black>=24.4; extra == 'dev'
Requires-Dist: coverage[toml]>=7.5; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# vibewithai

**The intelligent developer SDK for Python.**

AI that performs engineering tasks — not a chat wrapper.

[![PyPI](https://img.shields.io/pypi/v/vibewithai.svg)](https://pypi.org/project/vibewithai/)
[![Python](https://img.shields.io/pypi/pyversions/vibewithai.svg)](https://pypi.org/project/vibewithai/)
[![License](https://img.shields.io/pypi/l/vibewithai.svg)](https://github.com/ragulraj-d/vibewithai/blob/main/LICENSE)
[![Tests](https://img.shields.io/badge/tests-1353%20passing-brightgreen.svg)](https://github.com/ragulraj-d/vibewithai)
[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)](https://github.com/ragulraj-d/vibewithai)
[![Typed](https://img.shields.io/badge/mypy-strict-blue.svg)](https://github.com/ragulraj-d/vibewithai)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

</div>

---

```python
import vibewithai

vibewithai.login("sk-proj-...", "AIza...", "sk-ant-...")   # any keys, any order

result = vibewithai.check()

print(result.score)      # 87
print(result.summary)    # "3 issues found across 12 files (1 at or above high)."
```

You describe an **engineering task**. The SDK handles provider selection, context
building, token budgeting, retries, and failover.

---

## Why vibewithai

Most AI coding tools are a prompt box with a system message. This is a working
SDK with an opinion about how AI should be used on real codebases.

| | |
|---|---|
| **Static analysis runs first** | AST, Ruff, Bandit and Radon execute locally before any model call. Most questions are answered deterministically, for free. The model is reserved for reasoning that tools genuinely cannot do. |
| **You never name a provider** | Pass whatever API keys you have. Each is matched to its provider by key shape, verified with a live health check, and the first working one becomes active. |
| **Failover is automatic** | Rate limited, over quota, or a 5xx? The SDK switches to your next verified provider mid-request. A bad credential never triggers a switch — that would hide a real misconfiguration. |
| **Structured results, not prose** | Every command returns a `CommandResult` with a score, typed findings, metrics and token accounting. The CLI is just one renderer. |
| **Nothing runs, nothing is overwritten** | Generated code is returned as data and never executed. Files are never modified without explicit opt-in, and originals are backed up. |
| **~2 ms import** | Lazy attribute resolution means the SDK is usable inside pre-commit hooks and editor plugins. A test fails the build if import exceeds 100 ms. |

---

## Installation

```bash
pip install vibewithai
```

That is everything. Ruff, Bandit, Radon and LibCST come with it, so the first
`vibewithai check` finds real problems rather than reporting that its analyzers
are missing.

**Requires Python 3.11+.** Tested on 3.11–3.14 across Linux, macOS and Windows.

Runtime dependencies are deliberately minimal: `httpx`, `platformdirs`, `rich`,
`typer`. No vendor SDKs — all 16 providers are reached over plain HTTP.

---

## Quick start

### 1. Authenticate

```python
import vibewithai

vibewithai.login(
    "sk-proj-xxxxxxxx",   # OpenAI
    "AIzaSyxxxxxxxx",     # Google Gemini
    "xai-xxxxxxxx",       # xAI Grok
    "sk-ant-xxxxxxxx",    # Anthropic
)
```

Or keep keys out of your code entirely:

```bash
export VIBEWITHAI_OPENAI_API_KEY=sk-proj-...
export ANTHROPIC_API_KEY=sk-ant-...          # conventional vendor variables work too
```

```python
vibewithai.login()    # environment → stored credentials → local Ollama
```

Guided terminal setup:

```bash
vibewithai init
```

### 2. Run a task

```python
result = vibewithai.review("src/app.py")

for finding in result.findings_at_or_above(vibewithai.Severity.HIGH):
    print(f"{finding.location}  [{finding.severity}]  {finding.title}")
    print(f"    {finding.detail}")
    print(f"    via {finding.source} (confidence {finding.confidence})")
```

`finding.source` tells you whether a result came from a deterministic tool
(`"ruff"`, `"bandit"`) or a model (`"ai:openai"`), so you always know how much
to trust it.

### 3. Gate on it

```python
result = vibewithai.security()

if not result:                 # falsy only when the tool itself errored
    raise SystemExit(2)
if not result.passed:          # False when blocking findings exist
    raise SystemExit(result.exit_code)
```

---

## The API

Nineteen commands, grouped by intent. Every one returns a `CommandResult`.

### Understand

```python
vibewithai.check()                    # full quality assessment, scored 0–100
vibewithai.review("src/app.py")       # pull-request style review
vibewithai.explain("src/auth.py")     # what it does and why
vibewithai.ask("Why is login failing?")
vibewithai.chat("How should I structure this service?")
```

### Improve

```python
vibewithai.fix("src/app.py")          # propose corrections
vibewithai.refactor("src/app.py")     # restructure, behaviour preserved
vibewithai.optimize()                 # find real performance problems
vibewithai.comment("src/app.py")      # docstrings where they are missing
```

### Secure and ship

```python
vibewithai.security()                 # vulnerability audit with exploitability reasoning
vibewithai.deploy()                   # production-readiness assessment
vibewithai.debug("KeyError: user_id", traceback=tb)
```

### Create

```python
vibewithai.test("src/app.py")         # generate pytest tests
vibewithai.document()                 # API reference
vibewithai.readme()                   # project README
vibewithai.generate("a FastAPI CRUD API for users")
vibewithai.coverage()                 # measure via pytest --cov
```

### Converse and stream

```python
session = vibewithai.chat()                       # a session that remembers
session.ask("Where is authentication handled?")
session.ask("Can we improve it?")                 # "it" resolves to the answer above

with vibewithai.stream("Explain the request flow") as answer:
    for chunk in answer:
        print(chunk, end="", flush=True)          # arrives as it is written
```

### Version control

```python
vibewithai.commit()                   # Conventional Commits message from staged diff
vibewithai.changelog(since="v1.2.0")  # Keep a Changelog entry
```

Commands that produce files write **nothing** unless you pass `apply=True`:

```python
result = vibewithai.fix("src/app.py")
print(result.artifacts["src/app.py"])          # review first
vibewithai.fix("src/app.py", apply=True)       # then apply; original is backed up
```

---

## Command line

```bash
vibewithai                            # welcome screen with detected environment
vibewithai init                       # guided setup
vibewithai doctor                     # diagnose the installation
vibewithai tutorial                   # learn the commands in five minutes

vibewithai check                      # exits 1 on findings at or above `high`
vibewithai review src/app.py
vibewithai security --fail-on medium
vibewithai fix src/app.py --yes

vibewithai ask "how does auth work?" --stream

vibewithai check --format json        # machine-readable
vibewithai check --format sarif       # GitHub Code Scanning
vibewithai check --format junit       # CI test-report views
vibewithai check --format github      # inline PR annotations, no token needed
vibewithai review --changed-only      # only files changed from HEAD
```

**Exit codes:** `0` clean · `1` findings at or above the threshold · `2` execution error.

---

## Result objects

```python
result = vibewithai.check()

result.score              # 0–100 quality score
result.status             # Status.WARNING
result.summary            # human-readable paragraph
result.findings           # list[Finding] — severity, location, source, confidence
result.suggestions        # list[Suggestion] — title, rationale, effort
result.metrics            # files, lines, complexity, cache hit rate
result.usage              # prompt/completion/cached token accounting
result.provider           # "openai"
result.execution_time     # seconds

result.passed             # quality gate
result.exit_code          # POSIX exit code
result.counts_by_severity # {'critical': 0, 'high': 1, ...}
result.findings_at_or_above(vibewithai.Severity.HIGH)

result.to_dict()          # JSON-serialisable, safe to log
result.to_json()
```

Render to any format:

```python
from vibewithai.reports import render

open("report.html", "w").write(render(result, "html"))
open("report.md", "w").write(render(result, "markdown"))
```

---

## Supported providers

All 16 work with an API key alone — no vendor SDKs, no extra dependencies.

| Category | Providers |
|---|---|
| **Frontier** | OpenAI · Anthropic Claude · Google Gemini · xAI Grok |
| **Aggregators** | OpenRouter · Together AI · Fireworks AI · Hugging Face · GitHub Models |
| **Direct** | DeepSeek · Mistral AI · Cohere · Groq · Perplexity |
| **Enterprise** | Azure OpenAI |
| **Local** | Ollama — no key required |

Provider selection, key detection and failover are entirely automatic. Adding a
new OpenAI-compatible provider is a single entry in `providers/specs.py`.

> **Not yet supported:** AWS Bedrock, Google Vertex AI and OCI Generative AI
> require cloud-native request signing (SigV4, service-account JWTs) rather than
> bearer tokens. Reach those models through OpenRouter or an OpenAI-compatible
> gateway in the meantime.

---

## Configuration

Layered, highest precedence first: **call arguments → environment → project file
→ user file → defaults.**

```toml
# vibewithai.toml
default_provider   = "openai"        # omit to use the first verified provider
offline            = false           # true = local static analysis only
max_context_tokens = 12000

[providers.openai]
model = "gpt-4o-mini"

[analysis]
analyzers         = ["ast", "ruff", "bandit", "radon"]
blocking_severity = "high"
exclude           = [".venv", "node_modules", "*_pb2.py"]

[auth]
fallback        = true               # switch providers on rate limits and outages
preferred_order = ["anthropic", "openai"]

[cache]
enabled = true
ttl     = 86400
```

**Credentials are never read from project files** — only from environment
variables and the user-level credential store — so a key cannot be committed by
accident. Full reference: [docs/configuration.md](docs/guide/configuration.md).

---

## Enterprise considerations

### Security

- **Credentials never leak.** API keys are wrapped in a `Secret` type that masks
  itself in `str()`, `repr()`, f-strings, and refuses to pickle. Independently, a
  logging filter scrubs credential-shaped text from every record before emission.
- **Nothing is written without consent.** Commands that modify the workspace
  raise `ConfirmationRequiredError` unless explicitly authorised; originals are
  backed up; writes outside the project root are refused; every write is atomic.
- **AI output is never executed.** Not `eval`-ed, not `exec`-ed, not imported.
- **Owner-only credential storage** — `0600` file inside a `0700` directory, with
  a warning if permissions loosen.
- Full threat model: [SECURITY.md](SECURITY.md).

### Data governance

Any AI command sends a **bounded, relevant slice** of your code — the file in
question plus its direct collaborators — never the whole repository. For codebases
that must not leave your network:

```toml
offline = true    # local static analysis only; zero network calls
```

Or run entirely on local models via Ollama.

### CI/CD

```yaml
- run: pip install vibewithai
- run: vibewithai check --fail-on high --format json > report.json
  env:
    VIBEWITHAI_OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
```

Ready-made configurations for [GitHub Actions](.github/workflows/ci.yml),
[GitLab CI](docs/guide/ci/gitlab-ci.yml), [Jenkins](docs/guide/ci/Jenkinsfile) and
[Azure DevOps](docs/guide/ci/azure-pipelines.yml), plus a fuller
[GitHub Actions walkthrough](docs/guide/ci/github-actions.yml) covering Code Scanning,
test reports and per-pull-request AI review.

### Performance

Analysis results are cached against file content digests, so unchanged files are
never re-analysed and never re-sent to a model. Independent files are analysed in
parallel. Repeat runs on a large repository complete in milliseconds.

### Extensibility

```python
from vibewithai.plugins import register

register(provider=my_provider_spec)                  # an AI backend
register(analyzer=MyAnalyzer())                      # a static check
register(report_format="teamcity", renderer=render)  # an output format
register(event_sink=my_telemetry)                    # progress and audit events
register(task=my_task_spec)                          # a whole new command
```

A task added this way runs on the same engine as every built-in command — no
engine change is involved, because a command *is* its declaration. Nothing may
replace a built-in: a name collision raises rather than silently redefining a
documented command.

Plugins are discovered through the `vibewithai.plugins` entry-point group, on
the first analysis of a process rather than at import, so `import vibewithai`
stays free of side effects.

---

## Documentation

| Guide | |
|---|---|
| [Installation](docs/guide/installation.md) | Platforms, extras, verification |
| [Quick start](docs/guide/quickstart.md) | First run, walkthrough |
| [Configuration](docs/guide/configuration.md) | Every setting and environment variable |
| [API reference](docs/reference/api-reference.md) | Complete public surface |
| [Architecture](docs/architecture/overview.md) | Layering, pipeline, module map |
| [Decision records](docs/architecture/adr/) | Why it works this way, and what was rejected |
| [Developer guide](docs/contributing/developer-guide.md) | Adding providers and analyzers |
| [Best practices](docs/guide/best-practices.md) | Getting good results |
| [Troubleshooting](docs/guide/troubleshooting.md) | Common failures and fixes |
| [FAQ](docs/guide/faq.md) | |

---

## Project health

| | |
|---|---|
| Tests | 1353 passing |
| Coverage | 90% |
| Type checking | `mypy --strict`, clean |
| Linting | Ruff + Black, clean |
| Security scan | Bandit, clean |
| Import time | ~2 ms |
| Runtime dependencies | 8 |

---

## Status

**1.0.0.** The full pipeline is implemented, tested end to end, and the public
surface is stable — output shapes are pinned by golden tests, and every promise
in [SECURITY.md](SECURITY.md) has a test named after it.

As a first release, the AI-backed commands have had far more automated testing
than real-world mileage. Treat their output as a capable reviewer's opinion rather
than ground truth — which is exactly why every finding carries a `confidence`
score and a `source`. Deterministic static analysis is unaffected by this caveat.

Issues and feedback: [github.com/ragulraj-d/vibewithai/issues](https://github.com/ragulraj-d/vibewithai/issues)

---

## Contributing

Contributions are welcome — see [CONTRIBUTING.md](.github/CONTRIBUTING.md) and the
[Code of Conduct](.github/CODE_OF_CONDUCT.md). To report a vulnerability, follow
[SECURITY.md](SECURITY.md) rather than opening a public issue.

## License

[MIT](LICENSE)
