update readme

Author: divagr18

README.md

@@ -7,7 +7,7 @@
 
 [Quick Start](docs/quick-start.md) • [Documentation](docs/) • [Examples](docs/examples) • [Twitter](https://twitter.com/hyperionhq) • [Website](https://hyperionhq.co) • [Blog](https://hyperionhq.co/blog)
 
-**⚡ <5µs Overhead • 2-Layer Caching • Smart Routing • Budget Controls • Spend Forecasting • Key Scoping • Real-time Analytics**
+**⚡ <5µs Overhead • 2-Layer Caching • Smart Routing • Budget Controls • Spend Forecasting • PII Redaction • Key Scoping • Real-time Analytics**
 
 **LLM caching and orchestration for teams who can't afford a single millisecond of overhead.**
 
@@ -31,6 +31,19 @@ What you get beyond just proxying:
 
 ---
 
+## Table of Contents
+- [Quick Start](#quick-start)
+- [Performance](#performance)
+- [Capabilities](#capabilities)
+- [Use Cases](#use-cases)
+- [Architecture Context](#architecture-context)
+- [Documentation](#documentation)
+- [Community & Support](#community--support)
+- [Admin Tools](#admin-tools)
+- [License](#license)
+
+---
+
 ## Quick Start
 
 ```bash
@@ -40,7 +53,7 @@ cp .env.example .env
 docker compose up -d --build
 ```
 
-Make a request through Hyperion using the official Python SDK:
+Make a request through Hyperion using the official [Python](https://github.com/hyperion-hq/hyperion-python) or [TypeScript](https://github.com/hyperion-hq/hyperion-typescript) SDKs. Here is an example using Python:
 
 ```python
 from hyperion import HyperionClient
@@ -88,18 +101,53 @@ All overhead is measured as pure gateway dispatch time (request receive → rout
 
 ## Capabilities
 
-### ⚡ Multi-Layer Response Caching
-- **L1 (Redis) - ~0.5ms:** Sub-millisecond exact-match. Byte-identical requests never touch the external internet. They are served directly from RAM before the upstream connection is even initiated.
-- **L2 (Semantic) - ~15ms:** Vector similarity on prompt embeddings via Qdrant. Catches conceptually equivalent queries that differ in phrasing ("What is the speed of light" vs "How fast does light travel").
+### Cache-First Latency Reduction
+- **L1 exact-match cache:** Redis serves byte-identical requests in the lowest-latency path, often without touching the upstream provider at all.
+- **L2 semantic cache:** Qdrant-backed vector search catches meaning-level duplicates to cut both latency and token spend on repetitive traffic.
+- **Scoped cache safety:** Cache entries can be isolated by tenant, team, and project so higher hit rates do not come at the cost of data leakage.
+
+### Smart Routing And Reliability
+- **Cost-aware model routing:** Hyperion routes traffic to the cheapest capable provider in real time instead of forcing every request through your most expensive model.
+- **Health-based failover:** If a provider is slow, degraded, or unavailable, requests can be transparently redirected to a healthy fallback.
+- **OpenAI-compatible endpoint:** Keep one client integration while Hyperion handles multi-provider orchestration underneath.
+
+### Budgets, Keys, And Policy Controls
+- **Scoped API keys:** Issue keys with model allowlists, quotas, and per-key governance instead of sharing root provider credentials.
+- **Budget enforcement:** Reject requests before they hit the model once a key, project, or tenant crosses its configured spending limit.
+- **PII redaction and policy controls:** Sensitive data can be scrubbed before requests reach cache or upstream providers, and stricter routing paths can be enforced for sensitive workloads.
+
+### Observability And Spend Visibility
+- **Real-time analytics:** Track cost, latency, cache hit rates, and provider health in the dashboard.
+- **Spend forecasting:** Monitor burn rate and projected budget exhaustion before overruns happen.
+- **Audit-friendly telemetry:** Centralized request and spend data gives you one place to understand how traffic is being served across providers.
+
+---
+
+## Use Cases
+
+### High-Volume Support And FAQ Traffic
+When thousands of users ask the same question in slightly different ways, Hyperion turns that repetition into low-latency cache hits instead of repeated model calls. That cuts both response time and token spend without changing your application code.
+
+### Multi-Tenant SaaS AI
+If you serve many customers from one AI platform, Hyperion gives each tenant isolated keys, scoped cache boundaries, and separate budget controls. You get shared infrastructure efficiency without cross-tenant leakage or uncontrolled spend.
+
+### Internal Copilots And Team Tools
+For engineering assistants, support copilots, internal search, and workflow automation, Hyperion becomes the control layer in front of every model call. It lets you standardize access, enforce model policy, and see where money and latency are going across the company.
+
+### Cost-Controlled Agent Workloads
+Agents can burn budget fast through loops, retries, and repeated tool decisions. Hyperion puts hard spend limits, routing controls, and cache-aware request handling in front of those flows so agent systems stay useful without becoming financially unpredictable.
+
+### Privacy-Sensitive AI Applications
+In healthcare, finance, enterprise search, and other sensitive environments, Hyperion can redact PII before prompts ever reach cache or upstream providers. That makes it a practical privacy perimeter for teams that need stronger control over what leaves their infrastructure.
 
-### Intelligent Routing
-An ML classifier runs per-request to assign complexity scores. Simple queries route to cheap models. Complex reasoning gets heavier models. No configuration—it adapts to your traffic dynamically.
+### Multi-Provider Reliability And Failover
+If your product depends on AI being available all the time, Hyperion gives you one endpoint in front of multiple providers with health-aware routing and failover. Instead of wiring fallback logic into every app, you centralize reliability in the gateway.
 
-### Budget Enforcement & Security
-Hard ceilings at the key level. When a limit is hit, traffic stops. Upstream credentials are encrypted at rest (AES-256-GCM). Keys are never logged or stored in plaintext. PII filters scrub sensitive data before it reaches the cache or any upstream.
+### Latency-Sensitive User Experiences
+For chat, autocomplete, copilots, and real-time workflows, a few hundred milliseconds matters. Hyperion improves the fast path with exact-match caching, semantic reuse, and smarter provider selection so your application feels consistently responsive under real production traffic.
 
-### Observability
-ClickHouse captures every request at throughput. The dashboard surfaces cost, latency, cache hit rates, and provider health in real time.
+### Centralized AI Governance
+When multiple teams use different models and providers, governance gets messy fast. Hyperion gives you one layer for API key management, budgets, routing policy, observability, and forecasting so AI usage is easier to scale and easier to control.
 
 ---