apiwells 0.1.0__py3-none-any.whl

apiwells/__init__.py

@@ -0,0 +1,2 @@
+"""Small diagnostics for OpenAI-compatible endpoints."""
+__version__ = "0.1.0"

apiwells/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

apiwells/cli.py

@@ -0,0 +1,178 @@
+"""Dependency-free, single-request endpoint diagnostics."""
+import argparse
+import http.client
+import ipaddress
+import json
+import math
+import os
+import socket
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from . import __version__
+
+LIMIT = 2 * 1024 * 1024
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def endpoint(base, allow_http=False):
+    if not base or any(ord(c) <= 32 or ord(c) == 127 for c in base):
+        raise ValueError("Base URL must not contain whitespace/control characters.")
+    p = urllib.parse.urlsplit(base)
+    if p.scheme not in ("http", "https") or not p.hostname:
+        raise ValueError("Use an absolute http(s) API base URL ending in /v1 if required.")
+    if p.username is not None or p.password is not None or p.query or p.fragment:
+        raise ValueError("Do not put credentials, query strings or fragments in the base URL.")
+    try:
+        p.port
+        local = ipaddress.ip_address(p.hostname).is_loopback
+    except ValueError:
+        local = p.hostname == "localhost"
+        # Validate malformed ports separately from non-IP hostnames.
+        p.port
+    if p.scheme == "http" and not local and not allow_http:
+        raise ValueError("Remote HTTP is unencrypted; use HTTPS or explicitly --allow-http.")
+    path = p.path.rstrip("/")
+    if path.endswith(("/models", "/chat/completions")):
+        raise ValueError("Supply the API base, not the /models or /chat/completions endpoint.")
+    return urllib.parse.urlunsplit((p.scheme, p.netloc, path, "", ""))
+
+
+def hint(status):
+    if 300 <= status < 400:
+        return "redirect", "Redirect blocked. Verify the final API base URL."
+    return {
+        400: ("bad_request", "Check model support and request parameters."),
+        401: ("authentication", "Check API key validity and the intended endpoint."),
+        403: ("forbidden", "Check permissions, IP policy and gateway/WAF rules."),
+        404: ("not_found", "Check base path and model name; this does not prove the service is offline."),
+        405: ("method_not_allowed", "Check route and protocol compatibility."),
+        429: ("rate_or_quota", "Check rate limits, quota and account balance; status alone cannot distinguish them."),
+    }.get(status, ("server_error" if status >= 500 else "http_error", "Inspect gateway/upstream logs for this request."))
+
+
+def diagnose(base_url, key="", model=None, timeout=15.0, max_tokens=8,
+             allow_http=False, use_env_proxy=False):
+    """Return a sanitized report. Raises ValueError for invalid local configuration."""
+    base = endpoint(base_url, allow_http)
+    if not math.isfinite(timeout) or timeout <= 0 or timeout > 300:
+        raise ValueError("Timeout must be finite and in (0, 300] seconds.")
+    if not isinstance(max_tokens, int) or not 1 <= max_tokens <= 4096:
+        raise ValueError("max-tokens must be an integer from 1 to 4096.")
+    if any(ord(c) < 33 or ord(c) > 126 for c in key):
+        raise ValueError("API key must contain printable ASCII without spaces.")
+    if model is not None and (not isinstance(model, str) or not model.strip()):
+        raise ValueError("A nonempty model is required for a chat check.")
+    kind = "chat" if model is not None else "models"
+    route = "/chat/completions" if model is not None else "/models"
+    headers = {"Accept": "application/json", "User-Agent": "apiwells/" + __version__}
+    if key:
+        headers["Authorization"] = "Bearer " + key
+    body = None
+    if model is not None:
+        headers["Content-Type"] = "application/json"
+        body = json.dumps({"model": model, "messages": [{"role": "user", "content": "Reply OK."}],
+                           "max_tokens": max_tokens, "stream": False}).encode()
+    req = urllib.request.Request(base + route, data=body, headers=headers)
+    # No redirects, .netrc authentication, retries or implicit environment proxy.
+    opener = urllib.request.build_opener(NoRedirect(), urllib.request.ProxyHandler(
+        None if use_env_proxy else {}))
+    report = {"schema_version": 1, "version": __version__, "check": kind,
+              "ok": False, "http_status": None, "category": "network", "elapsed_ms": 0}
+    start = time.monotonic()
+    try:
+        try:
+            response = opener.open(req, timeout=timeout)
+        except urllib.error.HTTPError as exc:
+            response = exc
+        with response:
+            report["http_status"] = response.code
+            if not 200 <= response.code < 300:
+                report["category"], report["hint"] = hint(response.code)
+                return report
+            raw = response.read(LIMIT + 1)
+        if len(raw) > LIMIT:
+            report.update(category="response_too_large", hint="Response exceeded the 2 MiB limit.")
+            return report
+        try:
+            data = json.loads(raw)
+        except (ValueError, UnicodeError, RecursionError):
+            report.update(category="invalid_json", hint="Expected JSON; check for an HTML login or proxy page.")
+            return report
+        valid = False
+        if isinstance(data, dict) and "error" not in data:
+            if kind == "models":
+                items = data.get("data")
+                valid = isinstance(items, list) and all(
+                    isinstance(x, dict) and isinstance(x.get("id"), str) and bool(x["id"])
+                    for x in items)
+                if valid:
+                    report["model_count"] = len(items)
+            else:
+                choices = data.get("choices")
+                if isinstance(choices, list) and choices and isinstance(choices[0], dict):
+                    message = choices[0].get("message")
+                    valid = (isinstance(message, dict) and message.get("role") == "assistant"
+                             and isinstance(message.get("content"), str) and bool(message["content"].strip()))
+        report.update(ok=valid, category="ok" if valid else "unexpected_schema",
+                      hint=("Minimal response check passed; this is not a full compatibility or quality certification."
+                            if valid else "Expected models data or nonempty assistant text. Inspect upstream protocol/model support."))
+        return report
+    except (urllib.error.URLError, OSError, http.client.HTTPException) as exc:
+        reason = exc.reason if isinstance(exc, urllib.error.URLError) else exc
+        category = "network"
+        if isinstance(reason, (TimeoutError, socket.timeout)):
+            category = "timeout"
+        elif isinstance(reason, ssl.SSLError):
+            category = "tls"
+        elif isinstance(reason, socket.gaierror):
+            category = "dns"
+        report.update(category=category, hint="Check DNS, certificate trust, connectivity and timeout. Raw errors are omitted to protect credentials.")
+        return report
+    finally:
+        report["elapsed_ms"] = round((time.monotonic() - start) * 1000, 2)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="ApiWells Endpoint Doctor: one diagnostic request, no retries.")
+    parser.add_argument("--version", action="version", version="apiwells " + __version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    p = sub.add_parser("doctor", help="Check an OpenAI-compatible API base")
+    p.add_argument("--base-url", required=True, help="Exact API base, e.g. https://host.example/v1; no automatic /v1")
+    p.add_argument("--api-key-env", default="APIWELLS_API_KEY", help="Environment variable containing the key")
+    p.add_argument("--anonymous", action="store_true", help="Send no authentication header")
+    p.add_argument("--chat", action="store_true", help="Opt into one potentially billable chat request")
+    p.add_argument("--model", help="Exact model ID; required with --chat")
+    p.add_argument("--max-tokens", type=int, default=8)
+    p.add_argument("--timeout", type=float, default=15, help="Socket operation timeout in seconds, not total wall-clock deadline")
+    p.add_argument("--allow-http", action="store_true", help="Explicitly allow unencrypted remote HTTP")
+    p.add_argument("--use-env-proxy", action="store_true", help="Opt into system/environment proxy settings")
+    p.add_argument("--json", action="store_true", help="Print sanitized JSON to stdout")
+    args = parser.parse_args(argv)
+    if args.chat != (args.model is not None):
+        p.error("Use --chat and --model together.")
+    key = "" if args.anonymous else os.environ.get(args.api_key_env, "")
+    if not args.anonymous and not key:
+        p.error("API key environment variable is missing/empty; set it or use --anonymous.")
+    try:
+        result = diagnose(args.base_url, key, args.model, args.timeout, args.max_tokens,
+                          args.allow_http, args.use_env_proxy)
+    except (ValueError, UnicodeError):
+        p.error("Invalid configuration. Check URL, port, HTTPS, key characters, model, timeout and token limit.")
+    if args.json:
+        print(json.dumps(result, ensure_ascii=True, allow_nan=False))
+    else:
+        print("{} {} HTTP={} {:.2f}ms [{}]".format(
+            "PASS" if result["ok"] else "FAIL", result["check"],
+            result["http_status"], result["elapsed_ms"], result["category"]))
+        print(result["hint"])
+        if "model_count" in result:
+            print("Models returned:", result["model_count"])
+    return 0 if result["ok"] else 1

apiwells-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: apiwells
+Version: 0.1.0
+Summary: Endpoint Doctor for OpenAI-compatible model APIs
+License-Expression: MIT
+Keywords: api,diagnostics,llm,endpoint
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ApiWells Endpoint Doctor
+
+A small, dependency-free CLI that checks an OpenAI-compatible model API from
+your machine. Useful when onboarding a gateway customer or checking a deployment.
+Python 3.10+. Initial alpha release; not a full SDK or a service monitor.
+
+## Install
+
+After the release is published to PyPI:
+
+```sh
+python -m pip install apiwells
+apiwells --version
+```
+
+For an unpublished local checkout: `python -m pip install .`
+
+## Check a model API
+
+Set `APIWELLS_API_KEY` in your environment using your shell's secret-input
+mechanism. Do not put a real key in a command, screenshot, issue or repository.
+
+```sh
+apiwells doctor --base-url https://YOUR-API-HOST/v1
+apiwells doctor --base-url https://YOUR-API-HOST/v1 --json
+```
+
+Replace the host with your actual API base. `/v1` is **not** added automatically.
+For a gateway using `/openai/v1`, supply that exact prefix. Do not supply the
+full `/models` or `/chat/completions` URL. This command sends one GET to
+`BASE/models`; it checks JSON `data` entries for nonempty string model IDs.
+An empty model list passes the shape check and reports `model_count: 0`.
+A model list does not prove that inference works or is available to this key.
+
+For one potentially billable inference request, opt in explicitly:
+
+```sh
+apiwells doctor --base-url https://YOUR-API-HOST/v1 --chat --model YOUR-MODEL-ID
+```
+
+This sends `Reply OK.` to `BASE/chat/completions`, with `stream: false` and
+`max_tokens: 8`. A pass means a nonempty assistant text response was returned;
+it does not require exactly `OK`. Some reasoning models require a different
+parameter or larger output budget; this release does not support those variants.
+`--max-tokens 32` increases the budget, not a guaranteed cost ceiling.
+There are no automatic retries or fallback models.
+
+For a local unauthenticated development server:
+
+```sh
+apiwells doctor --base-url http://127.0.0.1:3000/v1 --anonymous
+```
+
+Use `--api-key-env NAME` to select another environment variable.
+`--timeout 15` is a socket-operation timeout, not an overall deadline; DNS or
+slow continuous delivery may make total runtime longer. `elapsed_ms` measures
+this client's request/response time, not server inference time or streaming TTFT.
+
+## Results
+
+Exit codes: `0` minimal check passed, `1` endpoint check failed, `2` local usage
+or configuration error. `--json` writes one JSON object to stdout for completed
+checks; usage errors go to stderr and do not produce a JSON report.
+
+HTTP categories include authentication (401), forbidden (403), not_found (404),
+rate_or_quota (429), server_error (5xx), and redirect (3xx). These are diagnostic
+hints, not definitive root-cause identification. Transport categories include
+network, DNS, TLS and timeout. HTTP 200 with HTML, malformed JSON or an invalid
+response shape fails. Response reading is capped at 2 MiB plus one sentinel byte.
+
+## Security and limitations
+
+- Keys are sent only to the supplied endpoint. Verify the host before running.
+- HTTPS certificate verification stays enabled. Remote HTTP requires `--allow-http`;
+  literal loopback addresses and localhost are allowed for development.
+- Redirects are blocked, including same-host redirects.
+- No telemetry, files, raw response bodies, model IDs, URL or keys in reports.
+- Proxy settings are ignored unless `--use-env-proxy` is explicitly supplied.
+- This is a local CLI for endpoints you may test. Do not expose it as an unrestricted
+  server-side URL-fetching service: private/local destinations are intentionally allowed.
+- No streaming, embeddings, images, tool calling, Responses API, native Anthropic
+  or native Gemini protocol coverage in this version.
+- No live provider integration has been certified by the bundled local tests.
+
+## Development
+
+```sh
+python -m venv .venv
+# macOS/Linux: source .venv/bin/activate
+# Windows PowerShell: .\.venv\Scripts\Activate.ps1
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m pip install build twine
+python -m build
+python -m twine check --strict dist/*
+```
+
+See `docs/PUBLISH_ZH.md` for the release walkthrough, sources and maintenance
+plan. License: MIT. Public source URL and maintainer contact can be added to
+project metadata once their real identities are confirmed; no fictitious links
+or authors are included.

apiwells-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+apiwells/__init__.py,sha256=zDgBwe59SKAoLUeABoQYh1uIbd6Lg7Xhn7mAQA06Y0U,79
+apiwells/__main__.py,sha256=ee5vE0xcUZM3fPmxicvcw-IJXkm6nOwxARREHBWpF8Q,47
+apiwells/cli.py,sha256=ew3RFfQMCxszmSyfnFVw5g4hJnSma6FgMDc6yA4eG8Q,9491
+apiwells-0.1.0.dist-info/licenses/LICENSE,sha256=Q9ns_jyx1GkfQczrUe0nfKbcQUE51Dx_cJcZpv3gfcM,1078
+apiwells-0.1.0.dist-info/METADATA,sha256=GYqqbo1IJmWj-f04xOj8yz6KOriFU-fYx_XHpCDZloo,4961
+apiwells-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+apiwells-0.1.0.dist-info/entry_points.txt,sha256=8wSP_AzjrMO1_TdRiTRuwWSe2sfplzcxll4sLB-7t8E,47
+apiwells-0.1.0.dist-info/top_level.txt,sha256=qVwURZwqLzsvtBeMUbFVyZinuzFnrECS6ZIXVQWj6Gs,9
+apiwells-0.1.0.dist-info/RECORD,,

apiwells-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

apiwells-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+apiwells = apiwells.cli:main

apiwells-0.1.0.dist-info/licenses/LICENSE

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

apiwells-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+apiwells