Starvex

Starvex Documentation Audit

Marketing site, docs, and SDK are out of sync at every layer — the published Python package exposes a different API surface than the docs describe, every code sample on the docs site uses imports the shipped package doesn't export, the footer is branded for a different company, and most "pages" can't be linked to.

1. Documented SDK API and import paths do not match the published package (critical)

Location: /docs (Quick Start), /docs/guardrails, /docs Built-in Rules, /docs API Reference vs. https://pypi.org/project/starvex/ (starvex 3.0.1, released Feb 6 2026)

Problem: The docs teach an SDK shape — and import paths — that the shipped package does not expose.

Quick Start (Evidence [3]) says:

from starvex import Starvex
vex = Starvex()
result = await vex.secure("User input here", my_agent)

The API Reference (Evidence [19]) documents class Starvex with secure(input_text, agent, …) -> SecureResult. The shipped PyPI README (Evidence [28]) instead exports:

from starvex import StarvexGuard
from starvex.rules import BlockPII, BlockJailbreak

No Starvex class, no vex.secure(), no SecureResult — the published package uses a decorator/checks model (StarvexGuard, @guard.protect, guard.check_input, guard.check_output).

Worse, even where the docs do use StarvexGuard, the import paths still don't match what pip install starvex provides:

• /docs/guardrails (Evidence [7]): from starvex.guardrails import StarvexGuard, BlockPII, BlockJailbreak
• /docs Built-in Rules (Evidence [8]): from starvex.guardrails.rules import BlockJailbreak, BlockPII, ...
• PyPI 3.0.1 (Evidence [28]): from starvex import StarvexGuard / from starvex.rules import BlockPII, ...

So both the starvex.guardrails and starvex.guardrails.rules paths used everywhere in the docs are wrong relative to the shipped package, which puts rules under starvex.rules and the guard under starvex directly.

Consequence: Effectively every code sample on the docs site fails on copy-paste. A developer who follows Quick Start gets ImportError: cannot import name 'Starvex'. A developer who follows the Guardrails Overview gets ModuleNotFoundError: No module named 'starvex.guardrails'. The "From install to production in minutes" promise breaks on the first import line of every example.

The fix: Decide which API is canonical. If StarvexGuard is the shipped API, rewrite Quick Start, How It Works, the homepage code sample (result = await vex.secure(input, agent)), Guardrails Overview, Built-in Rules, Custom Rules, and API Reference to use from starvex import StarvexGuard / from starvex.rules import .... If the Starvex class is the intended public API, cut a release that actually exports it. Either way, pin the docs to a versioned SDK tag.

2. Footer and legal docs are branded for a different company (critical)

Location: Site-wide footer; /privacy; /terms

Problem: Every page footer says © 2026 Velone. All rights reserved. The Privacy Policy (Evidence [26]) opens with Velone ("we", "our", or "us") is committed to protecting your privacy and gives privacy@velone.com as the contact. Terms (Evidence [27]) gives legal@velone.com. Nowhere on the marketing site or docs is the Velone ↔ Starvex relationship explained.

Consequence: A buyer running procurement/security review sees "Starvex" on the contract surface and "Velone" on the legal entity, with no disclosure that they're the same company. That's an immediate flag for compliance review and stalls enterprise deals. It also makes the privacy contact look like it belongs to a different vendor.

The fix: Pick one. Either rebrand the legal docs and footer to "Starvex" (with a one-line "Starvex is operated by Velone Inc." disclosure), or surface the Velone parent relationship prominently on the About/Company pages — which currently 404.

3. Most docs pages are not deep-linkable (critical)

Location: /docs and all sidebar entries

Problem: Only four URLs render distinct content: /docs (Quick Start), /docs/guardrails, /docs/observability, /docs/simulation. Every other sidebar item — Installation, Authentication, How It Works, Built-in Rules, Custom Rules, Advanced, Instrumentation, Tracing, Metrics, Test Suites, Security Scoring, CI/CD Integration, API Reference — only renders inside the SPA at /docs. Direct hits like /docs/installation, /docs/authentication, /docs/api, /docs/reference all 404 (Evidence [20]).

Consequence: Developers can't share a link to "go read the auth page" — they have to say "go to /docs, then click Authentication." Search engines and AI agents (Claude Code, Cursor, etc.) can't index per-page content; they see one giant URL. Stack Overflow answers, internal wikis, and Slack pastes all degrade to the docs root.

The fix: Give each sidebar entry its own URL (/docs/installation, /docs/built-in-rules, etc.) and render it server-side or with proper SPA route handling. Update the sidebar <a href>s to those URLs.

4. No llms.txt, sitemap, or robots — agents can't discover the docs (critical)

Location: /llms.txt, /llms-full.txt, /sitemap.xml, /robots.txt

Problem: All four return the SPA 404 shell (Evidence [22], [23]). No machine-readable index exists for the documentation. Combined with finding #3 (no per-page URLs), an AI coding agent has no efficient way to discover or page through Starvex documentation.

Consequence: Claude Code / Cursor / Copilot users asking "how do I add a Starvex guardrail" can't be helped by tools that crawl docs — there's nothing to crawl. Given the product positions itself at AI-agent developers, this is the audience most likely to be using the very tools that can't find these docs.

The fix: Generate llms.txt with one bullet per docs page and a brief description. Generate llms-full.txt with the full text. Add a sitemap and a permissive robots.txt. None of this can happen until #3 is fixed.

5. "API Reference" documents no API (critical)

Location: /docs → API Reference (sidebar item)

Problem: The page (Evidence [19]) documents the Starvex Python class constructor, the secure() method, and the SecureResult dataclass, plus three CLI commands (login, status, logout). That is the entirety of the "API Reference." There is:

• No REST endpoint listing
• No authentication header format (the docs say "API key" but never show Authorization: Bearer … or equivalent for HTTP)
• No error codes / error response schema
• No rate limit documentation (the pricing page says "10,000 requests/month" / "500,000 requests/month" but nothing tells you what the rate-limit response looks like, retry-after semantics, etc.)
• No OpenAPI / Swagger spec

Consequence: Anyone building a non-Python integration (Node, Go, a Cloudflare Worker, an n8n node) cannot call Starvex. Anyone debugging a 4xx/5xx response from the dashboard sync (sync_settings: bool = True) has zero documented status codes to interpret. The "Edge Deployment" homepage claim has no surface area developers can call.

The fix: Publish either (a) a REST API reference with endpoints, auth header, error codes, and rate-limit headers, or (b) an explicit "Python SDK only; no public REST API" statement so developers stop hunting. If there is an OpenAPI spec, link it.

6. Install extras are inconsistent across pages (significant)

Location: /docs Installation vs. /docs Advanced Engines vs. /docs CI/CD Integration vs. PyPI

Problem: The Installation page (Evidence [4]) lists four install commands: starvex, starvex[guardrails], starvex[eval], starvex[full]. But:

• Advanced Engines (Evidence [10]) says: pip install starvex[semantic,nli]
• CI/CD Integration (Evidence [18]) says: pip install starvex[simulation]
• PyPI's Provides-Extra field (Evidence [28]) lists: dev, eval, full, gliner, guardrails, hybrid, ml, nli, observability, pii, semantic, simulation, vector — 13 extras
• PyPI README references: starvex[pii], starvex[semantic], starvex[nli], starvex[vector]

The docs Installation page mentions only 3 of the 13 published extras.

Consequence: Developers following the Installation page won't enable the semantic router or NLI engine even though they appear in feature docs. They discover the missing extras only when something raises ImportError mid-request. The pii, vector, gliner, hybrid, ml, and observability extras are essentially undocumented.

The fix: Maintain a single canonical extras table on /docs/installation listing every Provides-Extra from pyproject.toml, what each enables, and any external model/runtime dependencies. Cross-link from every page that requires an extra.

7. BlockPII parameter name disagrees between docs and shipped package (significant)

Location: /docs Built-in Rules vs. PyPI README

Problem: The Built-in Rules page (Evidence [8]) documents BlockPII with redact: bool = False, and its own example code uses BlockPII(redact=True). The actual published package's README (Evidence [28]) documents BlockPII(redact_instead=True) — explicitly annotated as "parameter is redact_instead, not redact". The names don't match.

TopicRestriction also disagrees: docs (Evidence [8]) document only allowed_topics; the shipped package (Evidence [28]) shows both allowed_topics and blocked_topics, and the /docs/guardrails example (Evidence [7]) doesn't use either parameter name explicitly.

Consequence: A developer copies BlockPII(redact=True) from the docs and either gets a TypeError: unexpected keyword argument 'redact', or — worse — the parameter is silently ignored and PII is blocked when they expected redaction. Anyone needing a deny-list of topics never learns blocked_topics exists.

The fix: Audit every documented parameter against the shipped class signatures (BlockPII, BlockJailbreak, TopicRestriction, BlockCompetitor, PolicyCompliance, CustomBlocklist) and reconcile.

8. Rule presets shipped by the package are entirely undocumented (significant)

Location: /docs Built-in Rules, /docs Custom Rules, /docs/guardrails vs. PyPI README

Problem: The PyPI README (Evidence [28]) exposes three first-class onboarding helpers:

from starvex.rules import default_rules, strict_rules, enterprise_rules
guard = StarvexGuard(rules=default_rules())     # BlockJailbreak, BlockPII, BlockToxicity
guard = StarvexGuard(rules=strict_rules())      # Default + TopicRestriction
guard = StarvexGuard(rules=enterprise_rules(competitors=[...]))

None of default_rules(), strict_rules(), or enterprise_rules() appears anywhere in the scraped docs (Quick Start, Guardrails Overview, Built-in Rules, Custom Rules, How It Works).

Consequence: The fastest, lowest-friction adoption path the package actually offers — a single-line preset — is invisible to anyone reading the docs. Developers instead hand-wire StarvexGuard(rules=[BlockJailbreak(...), BlockPII(...), ...]) from incorrect imports (see #1), with worse defaults than the preset would give them.

The fix: Add a "Rule Presets" subsection to Built-in Rules listing each preset, its included rules, when to use it, and a one-line example. Cross-reference from Quick Start as the recommended starting point.

9. CLI surface in API Reference is incomplete relative to its own product pages (significant)

Location: /docs API Reference vs. /docs Metrics & Stats vs. /docs CI/CD Integration

Problem: API Reference (Evidence [19]) documents only three CLI commands: starvex login, starvex status, starvex logout. But:

• Metrics & Stats (Evidence [14]) documents: starvex observability stats, starvex observability events, starvex observability export -o events.json
• CI/CD Integration (Evidence [18]) documents: starvex simulation run --suite security [--verbose]

So at least five additional CLI commands are referenced as real, runnable surface area on product pages but never appear in the page titled "API Reference."

Consequence: A developer treating the "API Reference" as the canonical CLI inventory (its name implies completeness) will not discover observability export or simulation run and will conclude they don't exist. Scripts built from the reference will be missing exactly the commands you'd want to wire into CI.

The fix: Make the API Reference's CLI section authoritative: include every starvex <namespace> <command> form documented anywhere on the site, with flags, examples, and exit-code semantics. Add a CI check that diffs starvex --help output against the reference.

10. "14-day free trial" claim contradicts the actual pricing (significant)

Location: Homepage pricing section vs. plan availability

Problem: The homepage pricing block (Evidence [1]) ends with: "All plans include a 14-day free trial. No credit card required." But:

• Starter is $0 forever — there is nothing to trial
• Pro ($49/month) is labeled "Coming Soon"
• Enterprise (Custom) is also labeled "Coming Soon"

There is no plan on which a 14-day free trial could meaningfully apply.

Consequence: A prospective customer reading the pricing section can't reconcile "all plans include a trial" with "the only purchasable plan is $0 forever" and "the paid plans don't exist yet." The line undermines trust in the rest of the marketing copy.

The fix: Remove the trial sentence until paid plans actually ship, or replace it with what's true today ("Starter is free forever; Pro and Enterprise are coming soon — join the waitlist").

11. Roadmap features overlap with features the homepage claims are shipping (significant)

Location: Homepage features vs. /coming-soon

Problem: The homepage (Evidence [1]) lists "Hallucination Detection" and "A/B Comparison" as Simulation Testing features alongside "Scenario Testing" and "CI/CD Integration." But /coming-soon (Evidence [24]) lists "Contextual Grounding Verification" (hallucination filtering) and "A/B Testing Framework" as features still in development. "Real-Time Sandbox Simulation Testing" is also on /coming-soon despite "Simulation Testing" being a top-level shipped pillar. Similarly, "Multi-Agent System Orchestration" is on /coming-soon while the Observability docs talk about "Distributed Tracing" across multi-agent systems as if it ships today.

Consequence: Developers can't tell which features actually work today. They evaluate Starvex against a competitor based on the homepage claims, choose Starvex, then discover during integration that the differentiating capability is unbuilt.

The fix: Mark each homepage bullet with a status badge (Available / Beta / Coming Soon) and link to the roadmap page when it's the latter. Remove unshipped features from the "what you get today" pitch.

12. Footer is a graveyard of dead links (significant)

Location: Site-wide footer

Problem: Eight footer links resolve to /404 (Evidence [2]): Changelog, Roadmap, Blog, Status, About, Careers, Contact, Press. The three social icons (github, twitter, linkedin) point to https://github.com, https://twitter.com, https://linkedin.com — bare homepages, not Starvex accounts. The "Documentation" and "API Reference" footer links both go to the same /docs URL.

Consequence: Every footer click but four lands on a 404 or the wrong site entirely. Status is a particularly bad one to break on an "enterprise-grade" guardrails platform — developers checking whether their dashboard is down get a 404 instead of an incident page.

The fix: Hide nav entries for pages that don't exist; only ship the link when the page exists. Fix the social icons to point at real Starvex/Velone accounts or remove them.

13. Code examples are missing imports / undefined references (significant)

Location: /docs Custom Rules; /docs Security Scoring

Problem: The Custom Rules example (Evidence [9]) uses BlockJailbreak inside StarvexGuard(rules=[BlockProfanity(...), BlockJailbreak()]) without ever importing it (the page only imports GuardRule, RuleResult, RuleAction). The Security Scoring example (Evidence [17]) calls runner.run(TestSuite.security_suite(), guard) but guard is never defined or imported on the page.

Consequence: Copy-paste fails immediately with NameError. AI agents extracting these snippets will produce code that doesn't run. The "snippet runs unmodified" contract — particularly important for agent-consumed docs — is broken (and stacks on top of finding #1, where even the imports that are present don't resolve against the shipped package).

The fix: Make every example self-contained: include the imports and any guard = StarvexGuard(...) setup needed to make the snippet executable on its own. Add a CI check that imports/parses every code block in docs.

14. /pricing 404s; the only pricing surface is a homepage anchor (significant)

Location: /pricing

Problem: https://starvex.in/pricing returns the SPA 404 shell (Evidence [21]). The footer "Pricing" link works only because it points at /#pricing (a homepage anchor). Additionally, the Pro plan ($49/month) is labeled "Coming Soon," and Enterprise (Custom) is also "Coming Soon" — so the only buyable plan is the $0 Starter.

Consequence: Any inbound link from sales decks, comparison sites, or Google results that uses /pricing (the canonical URL pattern) breaks. The "Most Popular" badge on a "Coming Soon" plan is confusing — a developer can't tell whether they can pay $49 today or whether they're stuck on the free tier.

The fix: Make /pricing resolve to the pricing section. Remove the "Most Popular" badge from a plan that can't be purchased, or remove the "Coming Soon" label if Pro actually is available.

15. /dashboard silently redirects to /auth with no notice (significant)

Location: /dashboard (top-nav "Get Started" CTA, in-docs "Dashboard" button, and PyPI README's "Get your API key at starvex.in/dashboard")

Problem: Hitting /dashboard lands on /auth (sign-in screen) with no explanatory message — the URL just changes (Evidence [25]). The PyPI README (Evidence [28]) tells users "Get your API key at starvex.in/dashboard" but they end up on a generic Sign In / Sign Up screen instead. GitHub OAuth is shown but marked "Coming soon," so only email/password and Google work.

Consequence: A developer following the PyPI quickstart hits a sign-in screen and isn't sure they're in the right place. The "GitHub" social auth showing "Coming soon" next to a working "Google" button creates the impression the dashboard itself is half-finished.

The fix: Redirect to /auth?redirect=/dashboard with a "Sign in to continue to the Starvex dashboard" message, or render a real /dashboard landing for logged-out users that explains what's behind the wall. Remove the "Coming soon" GitHub button until it ships.

16. In-docs "GitHub" and "Changelog" controls don't work (significant)

Location: /docs top nav

Problem: The docs nav (Evidence [20]) exposes "GitHub" → https://github.com (the bare GitHub homepage, no Starvex org or repo) and "Changelog" → # (an empty anchor — no destination at all).

Consequence: Developers looking for source, issues, or release notes (an obvious need for a "beta" SDK at 3.0.1 with a documented API that doesn't match the install) hit either GitHub's logged-in feed or jump to the top of the docs page. There is no way to verify SDK history, file an issue, or check what changed between versions.

The fix: Point GitHub at the actual repository (PyPI's "Project links" show one exists). Build a /changelog page or remove the nav item until it exists.

17. Observability auto-instrumentation API may be a fourth piece of doc-vs-package drift (minor)

Location: /docs/observability, /docs Instrumentation, /docs Metrics & Stats vs. PyPI README

Problem: The Observability Overview (Evidence [11]) and Instrumentation page (Evidence [12]) document a substantial API:

from starvex.observability import instrument, get_stats, get_calls
instrument(providers=["openai", "anthropic"])

with auto-instrumentation for OpenAI, Anthropic, LangChain, LlamaIndex, and Cohere. The PyPI README (Evidence [28]) — which documents StarvexGuard, rules, presets, and async support in detail — does not surface this starvex.observability API at all, and the package's primary distinction is between guardrails and rule presets.

Given that every other docs-to-package comparison in this audit (class name, import paths, BlockPII(redact=…), rule presets) has revealed drift, the silence of the PyPI README on starvex.observability is suspicious enough to flag for verification.

Consequence: If this API also doesn't ship in 3.0.1, every observability snippet in the docs fails on import — and developers wire telemetry against an API that doesn't exist. If it does ship, the PyPI README is underselling a major part of the product.

The fix: Verify from starvex.observability import instrument, get_stats, get_calls against the installed wheel. If it works, surface it in the PyPI README. If it doesn't, either ship it or remove the Observability docs.

18. Authentication docs never specify the HTTP API key format or rotation (minor)

Location: /docs Authentication

Problem: The page (Evidence [5]) says "Create an API key from the Dashboard → API Keys" and shows export STARVEX_API_KEY=sv_live_your_key_here. It never explains: how long keys live, how to rotate them, what sv_live_ vs. any test-key prefix means, whether multiple keys are supported, what scopes/permissions exist, or what HTTP header the SDK sends (relevant because the SDK obviously calls some remote endpoint to sync settings — sync_settings: bool = True).

Consequence: Security review can't approve key handling without knowing rotation/scope semantics. Developers can't write a key-rotation runbook.

The fix: Add a "Key formats and rotation" subsection: prefix meanings, lifetime, rotation procedure, and the HTTP header used when keys are sent to the API.

What they do well

• The conceptual model (guardrails + observability + simulation) is clearly explained on each overview page, and the four overview pages that do have deep links are well-scoped.
• Built-in Rules and Custom Rules pages show working extension patterns (subclass GuardRule, return RuleResult with RuleAction.BLOCK/ALLOW) — good shape, just needs the imports.
• Test-suite primitives (TestSuite.security_suite(), TestSuite.jailbreak_suite(), custom TestCase) have a coherent shape that would slot cleanly into CI if the SDK matched.

Top 3 recommendations

1. Reconcile every code sample with the published SDK. Every example on the docs site uses either a class (Starvex) or an import path (starvex.guardrails, starvex.guardrails.rules) that the shipped starvex 3.0.1 does not provide. Pick a canonical surface (from starvex import StarvexGuard / from starvex.rules import ...), rewrite Quick Start, How It Works, Guardrails Overview, Built-in Rules, Custom Rules, and API Reference against it, add the rule presets, and pin the docs to a versioned tag. Add a CI check that imports every code block.
2. Give every docs page its own URL, then publish llms.txt + sitemap. The product targets AI-agent developers; agents need crawlable, deep-linkable docs.
3. Decide what is Starvex and what is Velone, then make every surface agree. Footer, privacy policy, terms, and contact emails should all match the brand the product ships under.