godaix 1.0.1__tar.gz

godaix-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayush Giri
+
+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.

godaix-1.0.1/PKG-INFO

@@ -0,0 +1,325 @@
+Metadata-Version: 2.4
+Name: godaix
+Version: 1.0.1
+Summary: Resilient AI tooling with decorators, coding analysis, provider resilience, and integrations
+Author: Ayush Giri
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ayushgiriai21-cmd/God
+Project-URL: Repository, https://github.com/ayushgiriai21-cmd/God
+Keywords: ai,llm,resilience,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.7
+Requires-Dist: requests>=2.31
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: openai>=1.0
+Requires-Dist: anthropic>=0.30
+Requires-Dist: google-generativeai>=0.8
+Requires-Dist: groq>=0.6
+Requires-Dist: flask>=3.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn>=0.29
+Requires-Dist: pytest>=7.0
+Dynamic: license-file
+
+# godai
+
+> Resilient AI tooling for healing Python calls, understanding code, surviving bad networks, and shipping developer integrations.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ayushgiriai21-cmd/God/main/assets/logo.png" alt="godai logo" width="180">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/godaix/"><img src="https://img.shields.io/pypi/v/godaix.svg" alt="PyPI version"></a>
+  <a href="https://github.com/ayushgiriai21-cmd/God/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ayushgiriai21-cmd/God.svg" alt="MIT license"></a>
+  <img src="https://img.shields.io/pypi/pyversions/godaix.svg" alt="Python versions">
+  <a href="https://github.com/ayushgiriai21-cmd/God/actions"><img src="https://img.shields.io/github/actions/workflow/status/ayushgiriai21-cmd/God/publish.yml?label=Publish" alt="Publish status"></a>
+</p>
+
+`godai` is one installable package with four deliberately independent sub-libraries. Importing the root stays cheap: `aura`, `nexus`, `aether`, and `apex` load lazily on first access.
+
+## What is godai?
+
+- **Aura** provides decorators for healing, retrying, validating, tracing, caching, sandboxing, auditing, and rate-limiting Python calls.
+- **Nexus** provides direct coding functions for explanation, structured parsing, project agents, reviews, test generation, refactoring, complexity, and security analysis.
+- **Aether** provides resilience primitives for timeouts, circuits, offline queues, fallback providers, health checks, persistent caches, and degraded operation.
+- **Apex** connects godai to pytest, pre-commit, GitHub Actions, web frameworks, CLI workflows, dashboards, metrics, tenants, and on-premise deployments.
+
+The package is authored by **Ayush Giri**. The verified repository is [github.com/ayushgiriai21-cmd/God](https://github.com/ayushgiriai21-cmd/God). No separate project website URL is configured in the repository metadata; the static documentation site lives in [`docs/`](docs/).
+
+## Dependencies
+
+`pip install godaix` installs these dependencies together. They are normal project dependencies, not optional extras.
+
+| Dependency | Purpose |
+| --- | --- |
+| `rich>=13.7` | Rich terminal output for CLI-oriented integrations. |
+| `requests>=2.31` | HTTP transport for provider and integration calls. |
+| `python-dotenv>=1.0` | Loading provider configuration from `.env` files. |
+| `pydantic>=2.0` | Input/output schemas and structured parsing. |
+| `openai>=1.0` | OpenAI SDK compatibility. |
+| `anthropic>=0.30` | Anthropic Claude integration. |
+| `google-generativeai>=0.8` | Google Gemini integration. |
+| `groq>=0.6` | Groq fast-inference integration. |
+| `flask>=3.0` | Flask middleware integration. |
+| `fastapi>=0.110` | FastAPI middleware integration. |
+| `uvicorn>=0.29` | ASGI serving for FastAPI-based tooling. |
+| `pytest>=7.0` | The Apex pytest plugin and test-oriented tooling. |
+
+## Installation
+
+### Normal environments
+
+Use a virtual environment, especially on Linux distributions that enforce PEP 668:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install godaix
+```
+
+Windows PowerShell equivalent:
+
+```powershell
+py -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install godaix
+```
+
+### Installing on Termux (Android)
+
+Installing directly in Termux is expected to fail when `pydantic-core` has no matching Android wheel and falls back to a Rust/maturin build. Errors commonly include `Unsupported Android architecture`. Use Ubuntu inside `proot-distro` instead:
+
+```bash
+pkg install proot-distro
+proot-distro install ubuntu
+proot-distro login ubuntu
+apt update && apt upgrade -y
+apt install -y python3 python3-pip python3-venv
+python3 -m venv godenv
+source godenv/bin/activate
+pip install godaix
+```
+
+During `apt upgrade`, `tzdata` may show a timezone prompt. Select your geographic area and city when prompted. On a non-interactive setup, set `DEBIAN_FRONTEND=noninteractive` and `TZ=UTC` before the upgrade, or run `dpkg-reconfigure tzdata` later.
+
+## Known Environment Issues
+
+### Termux / Android
+
+`pydantic-core` is a Rust extension and Android/Termux may not have a compatible prebuilt wheel. Maturin can report `Unsupported Android architecture`. Install through Ubuntu in `proot-distro` using the steps above; do not try to work around it by removing a required dependency.
+
+### iSH / iPadOS terminal apps
+
+iSH uses an Alpine/musl-based environment and often runs under x86 emulation. A matching `pydantic-core` wheel may not exist, and a usable Rust toolchain may not be available. Use a proper Linux VM/container or a cloud development environment such as GitHub Codespaces or Replit on iPad instead of installing this package directly in iSH.
+
+### `externally-managed-environment` / PEP 668
+
+Newer Debian and Ubuntu installations may reject system-wide pip writes. Create and activate a virtual environment first:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install godaix
+```
+
+Do not remove the distribution's `EXTERNALLY-MANAGED` marker. `pip install --break-system-packages` is a last-resort system choice, not the recommended installation path.
+
+### Rust, maturin, or missing wheel errors
+
+On unsupported Python/platform combinations, pip may attempt to compile `pydantic-core` and fail with `cargo`, `rustc`, or `maturin` errors. Use a supported CPython release with a compatible wheel, preferably Python 3.10 or newer, and upgrade pip before retrying. The package metadata allows Python 3.9, but current `pydantic-core` releases declare Python 3.10+; Python 3.9 users may need a compatible dependency resolution or should use Python 3.10+.
+
+### Dependency resolution conflicts
+
+If pip reports `ResolutionImpossible`, inspect the first conflicting requirement and update pip in a fresh environment. Do not mix unrelated global packages into the install:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip setuptools wheel
+python -m pip install godaix
+```
+
+### Alpine, musl, emulated, or unusual architectures
+
+Alpine's musl libc, iSH's emulated x86 environment, and less common CPU
+architectures can all lack a compatible `pydantic-core` wheel. In that case
+pip falls back to a native build even when the Python version is supported.
+Prefer a glibc-based Ubuntu environment with CPython 3.10+ and a matching
+wheel. If you must retry the build, make the build tools explicit first:
+
+```bash
+python -m pip install --upgrade pip setuptools wheel
+python -m pip install godai
+```
+
+Termux package maintainers sometimes ship Rust-backed extensions as separate
+native packages, but that does not make arbitrary pip builds on Android
+reliable; the Ubuntu `proot-distro` route above remains the supported setup.
+
+### TLS certificate failures
+
+`SSLCertVerificationError`, `CERTIFICATE_VERIFY_FAILED`, and similar errors usually mean the host Python or corporate proxy lacks a trusted CA bundle. Update the operating-system CA certificates, configure the organization’s CA bundle as documented by its proxy, and retry in a fresh environment. Avoid disabling TLS verification.
+
+### Missing provider or system dependency
+
+Provider SDKs are installed by default, but an environment can still have a broken or incomplete installation. godai’s dependency helper raises a clear `ImportError` naming the exact command, such as `python -m pip install torch`, rather than hiding the problem behind a raw traceback. Install the named package in the active virtual environment and retry.
+
+## Examples
+
+Run examples from the repository root, inside an activated environment where godai is installed:
+
+```bash
+python3 examples/aura_examples.py
+python3 examples/nexus_examples.py
+python3 examples/aether_examples.py
+python3 examples/apex_examples.py
+python3 examples/combined_examples.py
+```
+
+All five files use offline or local paths and run without an API key. The combined workflow touches all 60 public members.
+
+## Quick Start
+
+```python
+from godai import aura, nexus, aether, apex
+
+@aura.trace
+@aura.heal(retries=1)
+def add(left: int, right: int) -> int:
+    return left + right
+
+print(add(2, 3))
+print(nexus.explain(KeyError("name")))
+print(aether.heuristics(ZeroDivisionError()))
+print(apex.redact("api_key=do-not-send-this"))
+```
+
+## API Reference
+
+Every public member is listed below. The static site in [`docs/`](docs/) expands each entry with an executable example taken from the repository’s example files.
+
+### Aura
+
+| Member | Description |
+| --- | --- |
+| `heal` | Diagnoses runtime exceptions, logs an explanation, retries, and re-raises after failures. |
+| `patch` | Requests corrected Python, strips fences, validates with `ast.parse()`, and executes the replacement in a controlled namespace. |
+| `retry` | Retries transient/network errors with exponential backoff and fails fast on logic errors. |
+| `validate` | Validates inputs and outputs against a Pydantic model or dictionary schema. |
+| `trace` | Logs arguments, return value, exceptions, and elapsed time. |
+| `cache` | Memoizes results with optional whitespace-normalized semantic caching. |
+| `async_heal` | Async-compatible healing decorator for coroutine functions. |
+| `sandbox` | Runs a decorated function with a restricted builtins mapping. |
+| `explain` | Adds a plain-English explanation note to raised exceptions. |
+| `benchmark` | Measures and logs function execution timing and wrapper overhead. |
+| `guard` | Blocks execution with a clear message when environment variables or packages are missing. |
+| `dry_run` | Logs configured side-effect interception for safe test paths. |
+| `audit` | Writes calls, successes, and exceptions to a JSON-lines audit file. |
+| `fallback` | Returns a fallback function result or default after a failure. |
+| `rate_limit` | Uses a token bucket to throttle calls and cap provider cost. |
+
+### Nexus
+
+| Member | Description |
+| --- | --- |
+| `explain` | Produces a plain-English diagnosis for an exception or traceback. |
+| `parse` | Extracts schema-shaped values from text and validates a Pydantic model. |
+| `agent` | Inspects a project directory and gates edits behind `allow_edits`. |
+| `summarize` | Summarizes functions, classes, and the public shape of Python code. |
+| `review` | Flags risky patterns in a unified diff. |
+| `test_gen` | Generates a runnable pytest skeleton for a callable. |
+| `docstring` | Generates a concise docstring from a function signature. |
+| `translate` | Requests a behavior-preserving translation to another language. |
+| `refactor` | Requests a refactor toward a stated goal after syntax validation. |
+| `complexity` | Estimates cyclomatic complexity offline using `ast`. |
+| `security_scan` | Flags `eval`, `exec`, and likely hardcoded secrets offline. |
+| `dependency_check` | Finds imports and suggests non-stdlib requirements entries. |
+| `commit_message` | Generates a conventional commit subject from a diff. |
+| `changelog` | Formats commit subjects into a changelog entry. |
+| `ask` | Answers a question scoped to supplied code context. |
+
+### Aether
+
+| Member | Description |
+| --- | --- |
+| `timeout` | Enforces a hard deadline and raises `TimeoutError` promptly. |
+| `circuit_breaker` | Tracks provider failures, opens a circuit, and fails fast during cooldown. |
+| `offline_queue` | Persists failed JSON requests in SQLite for later replay. |
+| `heuristics` | Diagnoses common Python exceptions without network access. |
+| `fallback_provider` | Tries configured providers in order and returns the first success. |
+| `degraded_mode` | Detects unavailable networking and logs an offline-mode warning. |
+| `lazy_load` | Imports a heavy module only at first actual use. |
+| `zero_overhead` | Benchmarks decorated fast-path overhead. |
+| `network_probe` | Measures connection quality and recommends timeout/retry values. |
+| `missing_dependency_helper` | Raises an exact pip command for an unavailable dependency. |
+| `cache_store` | Provides bounded TTL disk-and-memory caching. |
+| `debounce` | Suppresses repeated identical calls during a configured window. |
+| `status` | Reports online, offline, degraded, or circuit-open health. |
+| `rust_core` | Uses a future compiled extension when present and a Python reference otherwise. |
+| `config` | Centralizes timeout, retry, circuit, and cache settings. |
+
+### Apex
+
+| Member | Description |
+| --- | --- |
+| `pytest_plugin` | Returns a pytest hook plugin that diagnoses failed tests. |
+| `pre_commit_hook` | Reviews staged Python diffs and returns a hook status code. |
+| `github_action` | Posts suggested fixes to GitHub using `GITHUB_TOKEN`. |
+| `django_middleware` | Captures and diagnoses unhandled Django exceptions with guarded imports. |
+| `flask_middleware` | Registers a Flask exception diagnosis handler. |
+| `fastapi_middleware` | Adds FastAPI middleware that observes unhandled failures. |
+| `cli` | Provides `godai fix`, `godai explain`, and `godai agent` commands. |
+| `vscode_extension` | Serves a documented local JSON-RPC-style editor endpoint. |
+| `redact` | Removes likely secrets and PII before code leaves the process. |
+| `on_prem` | Describes self-hosted OpenAI-compatible endpoint configuration. |
+| `multi_tenant` | Stores tenant keys, quotas, and usage counters. |
+| `shared_cache` | Exposes a shared-backend cache adapter. |
+| `metrics` | Produces Prometheus-compatible call counters. |
+| `dashboard` | Renders an HTML history view from audit events. |
+| `docker_ready` | Validates required environment variables without prompting. |
+
+## Supported LLM Providers
+
+Set the provider and its credential before making an online call. `offline` and `local` are safe defaults for examples.
+
+| Provider | Environment variables |
+| --- | --- |
+| Anthropic Claude | `GODAI_PROVIDER=anthropic`, `ANTHROPIC_API_KEY=...` |
+| OpenAI GPT | `GODAI_PROVIDER=openai`, `OPENAI_API_KEY=...` |
+| Google Gemini | `GODAI_PROVIDER=gemini`, `GOOGLE_API_KEY=...` |
+| Groq | `GODAI_PROVIDER=groq`, `GROQ_API_KEY=...` |
+| xAI Grok | `GODAI_PROVIDER=xai`, `XAI_API_KEY=...` |
+| Ollama | `GODAI_PROVIDER=ollama`, `OLLAMA_BASE_URL=http://localhost:11434` |
+| Qwen | `GODAI_PROVIDER=qwen`, `DASHSCOPE_API_KEY=...` |
+| OpenRouter | `GODAI_PROVIDER=openrouter`, `OPENROUTER_API_KEY=...` |
+| Generic OpenAI-compatible | `GODAI_PROVIDER=openai_compatible`, `GODAI_BASE_URL=https://host/v1`, `GODAI_API_KEY=...` |
+
+For the provider-specific cloud entries, set the provider-specific key shown
+above. The low-level OpenAI-compatible transport sends `GODAI_API_KEY` as its
+Bearer token, so set that shared variable as well when using `openai`, `groq`,
+`xai`, `qwen`, or `openrouter` with the built-in HTTP transport.
+
+Optional model and resilience settings use `GODAI_MODEL`, `GODAI_TIMEOUT`, `GODAI_RETRIES`, `GODAI_CIRCUIT_THRESHOLD`, and `GODAI_CACHE_TTL`.
+
+## License
+
+godai is released under the [MIT License](LICENSE).
+
+## Contributing
+
+Open an issue or pull request on [ayushgiriai21-cmd/God](https://github.com/ayushgiriai21-cmd/God). Keep changes focused, add or update runnable examples for public behavior, and run the offline example suite before requesting review.
+
+## About the Author
+
+**Ayush Giri** · GitHub: [@ayushgiriai21-cmd](https://github.com/ayushgiriai21-cmd) · Repository: [github.com/ayushgiriai21-cmd/God](https://github.com/ayushgiriai21-cmd/God)
+
+The repository does not currently declare a separate project website URL. The local documentation website is available from [`docs/index.html`](docs/index.html).

godaix-1.0.1/README.md

@@ -0,0 +1,295 @@
+# godai
+
+> Resilient AI tooling for healing Python calls, understanding code, surviving bad networks, and shipping developer integrations.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ayushgiriai21-cmd/God/main/assets/logo.png" alt="godai logo" width="180">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/godaix/"><img src="https://img.shields.io/pypi/v/godaix.svg" alt="PyPI version"></a>
+  <a href="https://github.com/ayushgiriai21-cmd/God/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ayushgiriai21-cmd/God.svg" alt="MIT license"></a>
+  <img src="https://img.shields.io/pypi/pyversions/godaix.svg" alt="Python versions">
+  <a href="https://github.com/ayushgiriai21-cmd/God/actions"><img src="https://img.shields.io/github/actions/workflow/status/ayushgiriai21-cmd/God/publish.yml?label=Publish" alt="Publish status"></a>
+</p>
+
+`godai` is one installable package with four deliberately independent sub-libraries. Importing the root stays cheap: `aura`, `nexus`, `aether`, and `apex` load lazily on first access.
+
+## What is godai?
+
+- **Aura** provides decorators for healing, retrying, validating, tracing, caching, sandboxing, auditing, and rate-limiting Python calls.
+- **Nexus** provides direct coding functions for explanation, structured parsing, project agents, reviews, test generation, refactoring, complexity, and security analysis.
+- **Aether** provides resilience primitives for timeouts, circuits, offline queues, fallback providers, health checks, persistent caches, and degraded operation.
+- **Apex** connects godai to pytest, pre-commit, GitHub Actions, web frameworks, CLI workflows, dashboards, metrics, tenants, and on-premise deployments.
+
+The package is authored by **Ayush Giri**. The verified repository is [github.com/ayushgiriai21-cmd/God](https://github.com/ayushgiriai21-cmd/God). No separate project website URL is configured in the repository metadata; the static documentation site lives in [`docs/`](docs/).
+
+## Dependencies
+
+`pip install godaix` installs these dependencies together. They are normal project dependencies, not optional extras.
+
+| Dependency | Purpose |
+| --- | --- |
+| `rich>=13.7` | Rich terminal output for CLI-oriented integrations. |
+| `requests>=2.31` | HTTP transport for provider and integration calls. |
+| `python-dotenv>=1.0` | Loading provider configuration from `.env` files. |
+| `pydantic>=2.0` | Input/output schemas and structured parsing. |
+| `openai>=1.0` | OpenAI SDK compatibility. |
+| `anthropic>=0.30` | Anthropic Claude integration. |
+| `google-generativeai>=0.8` | Google Gemini integration. |
+| `groq>=0.6` | Groq fast-inference integration. |
+| `flask>=3.0` | Flask middleware integration. |
+| `fastapi>=0.110` | FastAPI middleware integration. |
+| `uvicorn>=0.29` | ASGI serving for FastAPI-based tooling. |
+| `pytest>=7.0` | The Apex pytest plugin and test-oriented tooling. |
+
+## Installation
+
+### Normal environments
+
+Use a virtual environment, especially on Linux distributions that enforce PEP 668:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install godaix
+```
+
+Windows PowerShell equivalent:
+
+```powershell
+py -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install godaix
+```
+
+### Installing on Termux (Android)
+
+Installing directly in Termux is expected to fail when `pydantic-core` has no matching Android wheel and falls back to a Rust/maturin build. Errors commonly include `Unsupported Android architecture`. Use Ubuntu inside `proot-distro` instead:
+
+```bash
+pkg install proot-distro
+proot-distro install ubuntu
+proot-distro login ubuntu
+apt update && apt upgrade -y
+apt install -y python3 python3-pip python3-venv
+python3 -m venv godenv
+source godenv/bin/activate
+pip install godaix
+```
+
+During `apt upgrade`, `tzdata` may show a timezone prompt. Select your geographic area and city when prompted. On a non-interactive setup, set `DEBIAN_FRONTEND=noninteractive` and `TZ=UTC` before the upgrade, or run `dpkg-reconfigure tzdata` later.
+
+## Known Environment Issues
+
+### Termux / Android
+
+`pydantic-core` is a Rust extension and Android/Termux may not have a compatible prebuilt wheel. Maturin can report `Unsupported Android architecture`. Install through Ubuntu in `proot-distro` using the steps above; do not try to work around it by removing a required dependency.
+
+### iSH / iPadOS terminal apps
+
+iSH uses an Alpine/musl-based environment and often runs under x86 emulation. A matching `pydantic-core` wheel may not exist, and a usable Rust toolchain may not be available. Use a proper Linux VM/container or a cloud development environment such as GitHub Codespaces or Replit on iPad instead of installing this package directly in iSH.
+
+### `externally-managed-environment` / PEP 668
+
+Newer Debian and Ubuntu installations may reject system-wide pip writes. Create and activate a virtual environment first:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install godaix
+```
+
+Do not remove the distribution's `EXTERNALLY-MANAGED` marker. `pip install --break-system-packages` is a last-resort system choice, not the recommended installation path.
+
+### Rust, maturin, or missing wheel errors
+
+On unsupported Python/platform combinations, pip may attempt to compile `pydantic-core` and fail with `cargo`, `rustc`, or `maturin` errors. Use a supported CPython release with a compatible wheel, preferably Python 3.10 or newer, and upgrade pip before retrying. The package metadata allows Python 3.9, but current `pydantic-core` releases declare Python 3.10+; Python 3.9 users may need a compatible dependency resolution or should use Python 3.10+.
+
+### Dependency resolution conflicts
+
+If pip reports `ResolutionImpossible`, inspect the first conflicting requirement and update pip in a fresh environment. Do not mix unrelated global packages into the install:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip setuptools wheel
+python -m pip install godaix
+```
+
+### Alpine, musl, emulated, or unusual architectures
+
+Alpine's musl libc, iSH's emulated x86 environment, and less common CPU
+architectures can all lack a compatible `pydantic-core` wheel. In that case
+pip falls back to a native build even when the Python version is supported.
+Prefer a glibc-based Ubuntu environment with CPython 3.10+ and a matching
+wheel. If you must retry the build, make the build tools explicit first:
+
+```bash
+python -m pip install --upgrade pip setuptools wheel
+python -m pip install godai
+```
+
+Termux package maintainers sometimes ship Rust-backed extensions as separate
+native packages, but that does not make arbitrary pip builds on Android
+reliable; the Ubuntu `proot-distro` route above remains the supported setup.
+
+### TLS certificate failures
+
+`SSLCertVerificationError`, `CERTIFICATE_VERIFY_FAILED`, and similar errors usually mean the host Python or corporate proxy lacks a trusted CA bundle. Update the operating-system CA certificates, configure the organization’s CA bundle as documented by its proxy, and retry in a fresh environment. Avoid disabling TLS verification.
+
+### Missing provider or system dependency
+
+Provider SDKs are installed by default, but an environment can still have a broken or incomplete installation. godai’s dependency helper raises a clear `ImportError` naming the exact command, such as `python -m pip install torch`, rather than hiding the problem behind a raw traceback. Install the named package in the active virtual environment and retry.
+
+## Examples
+
+Run examples from the repository root, inside an activated environment where godai is installed:
+
+```bash
+python3 examples/aura_examples.py
+python3 examples/nexus_examples.py
+python3 examples/aether_examples.py
+python3 examples/apex_examples.py
+python3 examples/combined_examples.py
+```
+
+All five files use offline or local paths and run without an API key. The combined workflow touches all 60 public members.
+
+## Quick Start
+
+```python
+from godai import aura, nexus, aether, apex
+
+@aura.trace
+@aura.heal(retries=1)
+def add(left: int, right: int) -> int:
+    return left + right
+
+print(add(2, 3))
+print(nexus.explain(KeyError("name")))
+print(aether.heuristics(ZeroDivisionError()))
+print(apex.redact("api_key=do-not-send-this"))
+```
+
+## API Reference
+
+Every public member is listed below. The static site in [`docs/`](docs/) expands each entry with an executable example taken from the repository’s example files.
+
+### Aura
+
+| Member | Description |
+| --- | --- |
+| `heal` | Diagnoses runtime exceptions, logs an explanation, retries, and re-raises after failures. |
+| `patch` | Requests corrected Python, strips fences, validates with `ast.parse()`, and executes the replacement in a controlled namespace. |
+| `retry` | Retries transient/network errors with exponential backoff and fails fast on logic errors. |
+| `validate` | Validates inputs and outputs against a Pydantic model or dictionary schema. |
+| `trace` | Logs arguments, return value, exceptions, and elapsed time. |
+| `cache` | Memoizes results with optional whitespace-normalized semantic caching. |
+| `async_heal` | Async-compatible healing decorator for coroutine functions. |
+| `sandbox` | Runs a decorated function with a restricted builtins mapping. |
+| `explain` | Adds a plain-English explanation note to raised exceptions. |
+| `benchmark` | Measures and logs function execution timing and wrapper overhead. |
+| `guard` | Blocks execution with a clear message when environment variables or packages are missing. |
+| `dry_run` | Logs configured side-effect interception for safe test paths. |
+| `audit` | Writes calls, successes, and exceptions to a JSON-lines audit file. |
+| `fallback` | Returns a fallback function result or default after a failure. |
+| `rate_limit` | Uses a token bucket to throttle calls and cap provider cost. |
+
+### Nexus
+
+| Member | Description |
+| --- | --- |
+| `explain` | Produces a plain-English diagnosis for an exception or traceback. |
+| `parse` | Extracts schema-shaped values from text and validates a Pydantic model. |
+| `agent` | Inspects a project directory and gates edits behind `allow_edits`. |
+| `summarize` | Summarizes functions, classes, and the public shape of Python code. |
+| `review` | Flags risky patterns in a unified diff. |
+| `test_gen` | Generates a runnable pytest skeleton for a callable. |
+| `docstring` | Generates a concise docstring from a function signature. |
+| `translate` | Requests a behavior-preserving translation to another language. |
+| `refactor` | Requests a refactor toward a stated goal after syntax validation. |
+| `complexity` | Estimates cyclomatic complexity offline using `ast`. |
+| `security_scan` | Flags `eval`, `exec`, and likely hardcoded secrets offline. |
+| `dependency_check` | Finds imports and suggests non-stdlib requirements entries. |
+| `commit_message` | Generates a conventional commit subject from a diff. |
+| `changelog` | Formats commit subjects into a changelog entry. |
+| `ask` | Answers a question scoped to supplied code context. |
+
+### Aether
+
+| Member | Description |
+| --- | --- |
+| `timeout` | Enforces a hard deadline and raises `TimeoutError` promptly. |
+| `circuit_breaker` | Tracks provider failures, opens a circuit, and fails fast during cooldown. |
+| `offline_queue` | Persists failed JSON requests in SQLite for later replay. |
+| `heuristics` | Diagnoses common Python exceptions without network access. |
+| `fallback_provider` | Tries configured providers in order and returns the first success. |
+| `degraded_mode` | Detects unavailable networking and logs an offline-mode warning. |
+| `lazy_load` | Imports a heavy module only at first actual use. |
+| `zero_overhead` | Benchmarks decorated fast-path overhead. |
+| `network_probe` | Measures connection quality and recommends timeout/retry values. |
+| `missing_dependency_helper` | Raises an exact pip command for an unavailable dependency. |
+| `cache_store` | Provides bounded TTL disk-and-memory caching. |
+| `debounce` | Suppresses repeated identical calls during a configured window. |
+| `status` | Reports online, offline, degraded, or circuit-open health. |
+| `rust_core` | Uses a future compiled extension when present and a Python reference otherwise. |
+| `config` | Centralizes timeout, retry, circuit, and cache settings. |
+
+### Apex
+
+| Member | Description |
+| --- | --- |
+| `pytest_plugin` | Returns a pytest hook plugin that diagnoses failed tests. |
+| `pre_commit_hook` | Reviews staged Python diffs and returns a hook status code. |
+| `github_action` | Posts suggested fixes to GitHub using `GITHUB_TOKEN`. |
+| `django_middleware` | Captures and diagnoses unhandled Django exceptions with guarded imports. |
+| `flask_middleware` | Registers a Flask exception diagnosis handler. |
+| `fastapi_middleware` | Adds FastAPI middleware that observes unhandled failures. |
+| `cli` | Provides `godai fix`, `godai explain`, and `godai agent` commands. |
+| `vscode_extension` | Serves a documented local JSON-RPC-style editor endpoint. |
+| `redact` | Removes likely secrets and PII before code leaves the process. |
+| `on_prem` | Describes self-hosted OpenAI-compatible endpoint configuration. |
+| `multi_tenant` | Stores tenant keys, quotas, and usage counters. |
+| `shared_cache` | Exposes a shared-backend cache adapter. |
+| `metrics` | Produces Prometheus-compatible call counters. |
+| `dashboard` | Renders an HTML history view from audit events. |
+| `docker_ready` | Validates required environment variables without prompting. |
+
+## Supported LLM Providers
+
+Set the provider and its credential before making an online call. `offline` and `local` are safe defaults for examples.
+
+| Provider | Environment variables |
+| --- | --- |
+| Anthropic Claude | `GODAI_PROVIDER=anthropic`, `ANTHROPIC_API_KEY=...` |
+| OpenAI GPT | `GODAI_PROVIDER=openai`, `OPENAI_API_KEY=...` |
+| Google Gemini | `GODAI_PROVIDER=gemini`, `GOOGLE_API_KEY=...` |
+| Groq | `GODAI_PROVIDER=groq`, `GROQ_API_KEY=...` |
+| xAI Grok | `GODAI_PROVIDER=xai`, `XAI_API_KEY=...` |
+| Ollama | `GODAI_PROVIDER=ollama`, `OLLAMA_BASE_URL=http://localhost:11434` |
+| Qwen | `GODAI_PROVIDER=qwen`, `DASHSCOPE_API_KEY=...` |
+| OpenRouter | `GODAI_PROVIDER=openrouter`, `OPENROUTER_API_KEY=...` |
+| Generic OpenAI-compatible | `GODAI_PROVIDER=openai_compatible`, `GODAI_BASE_URL=https://host/v1`, `GODAI_API_KEY=...` |
+
+For the provider-specific cloud entries, set the provider-specific key shown
+above. The low-level OpenAI-compatible transport sends `GODAI_API_KEY` as its
+Bearer token, so set that shared variable as well when using `openai`, `groq`,
+`xai`, `qwen`, or `openrouter` with the built-in HTTP transport.
+
+Optional model and resilience settings use `GODAI_MODEL`, `GODAI_TIMEOUT`, `GODAI_RETRIES`, `GODAI_CIRCUIT_THRESHOLD`, and `GODAI_CACHE_TTL`.
+
+## License
+
+godai is released under the [MIT License](LICENSE).
+
+## Contributing
+
+Open an issue or pull request on [ayushgiriai21-cmd/God](https://github.com/ayushgiriai21-cmd/God). Keep changes focused, add or update runnable examples for public behavior, and run the offline example suite before requesting review.
+
+## About the Author
+
+**Ayush Giri** · GitHub: [@ayushgiriai21-cmd](https://github.com/ayushgiriai21-cmd) · Repository: [github.com/ayushgiriai21-cmd/God](https://github.com/ayushgiriai21-cmd/God)
+
+The repository does not currently declare a separate project website URL. The local documentation website is available from [`docs/index.html`](docs/index.html).