vibewithai 1.0.0

The intelligent developer SDK for Python — AI that performs engineering tasks, not a chat wrapper.

vibewithai

The intelligent developer SDK for Python.

AI that performs engineering tasks — not a chat wrapper.

---

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

pip install vibewithai                      # core
pip install "vibewithai[analysis]"          # + Ruff, Bandit, Radon, LibCST  (recommended)

Requires Python 3.11+. Tested on 3.11–3.13 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

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:

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

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

Guided terminal setup:

vibewithai init

2. Run a task

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

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

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

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

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

Create

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

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

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:

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

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

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:

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.

# 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.

---

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.

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:

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

Or run entirely on local models via Ollama.

CI/CD

- run: pip install "vibewithai[analysis]"
- 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, GitLab CI, Jenkins and Azure DevOps, plus a fuller GitHub Actions walkthrough 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

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	Platforms, extras, verification
Quick start	First run, walkthrough
Configuration	Every setting and environment variable
API reference	Complete public surface
Architecture	Layering, pipeline, module map
Decision records	Why it works this way, and what was rejected
Developer guide	Adding providers and analyzers
Best practices	Getting good results
Troubleshooting	Common failures and fixes
FAQ

---

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	4

---

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 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

---

Contributing

Contributions are welcome — see CONTRIBUTING.md and the Code of Conduct. To report a vulnerability, follow SECURITY.md rather than opening a public issue.

License

MIT