[hallelx2]

Rewrites the README to show how llmgate works:

• the Client and Judge seams, providers, and Anthropic-compatible gateways;
• the middleware stack and its order, router and fallback, retry, budget and cache;
• the adaptive concurrency limiter;
• cost tracking, prompt caching, tool calling, capability flags, and testing with the mocks;
• the Judge interface for System One models: Noul, Choice, Score, batching, and the context guard with its fix.

Adds a Measured table with each figure's date and source, and the Go ecosystem comparison. Figures come from the article plus two new ones (the two seams, the guard fix). The three old SVGs are removed; they left out the limiter and the Judge, and drew the stack backwards.

All 16 Go blocks build and vet against main. Rendered on github.com with 12 images and none broken. Lorx CI green, both bit run --all and the cloud run (GitHub Actions can't start jobs, HAL-1712).

Part of HAL-2755 (control plane and pdfgrab READMEs land separately). No-Linear-Issue: HAL-2755 closes with the last of the three.

Summary by Sourcery

Rewrite the README as a measured, example-driven showcase of llmgate’s client, middleware, provider, and Judge capabilities.

Enhancements:

• Replace the README with a comprehensive, example-driven guide to llmgate’s Client and Judge interfaces, providers, middleware composition, routing, retries, budgeting, caching, adaptive concurrency, cost tracking, prompt caching, tool calling, capabilities, and testing.
• Document the Judge workflow for System One models, including typed question primitives, batching, context limits, TypeSafe integration, and the context-guard performance fix.
• Add dated measurements, source references, production usage context, and a comparison with other Go LLM libraries.

Documentation:

• Remove the outdated architecture, middleware-stack, and request-flow SVGs in favor of the new README diagrams and explanations.

[sourcery-ai]

Sorry @hallelx2, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 day and 1 hour by commenting @sourcery-ai review. Upgrade to get a review now.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 6e2c5848-bdbb-430d-a511-bfc5ca48de61

---

📥 Commits

Reviewing files that changed from the base of the PR and between 6dc09b4 and 48d05e5.

---

⛔ Files ignored due to path filters (9)

• docs/architecture.svg is excluded by !**/*.svg
• docs/media/banner.png is excluded by !**/*.png
• docs/media/go-ecosystem.png is excluded by !**/*.png
• docs/media/the-guard.png is excluded by !**/*.png
• docs/media/the-limiter.png is excluded by !**/*.png
• docs/media/the-stack.png is excluded by !**/*.png
• docs/media/two-seams.png is excluded by !**/*.png
• docs/middleware-stack.svg is excluded by !**/*.svg
• docs/request-flow.svg is excluded by !**/*.svg

---

📒 Files selected for processing (1)

• README.md

---

 _________________________________________________________________________
< Congratulations, you implemented a distributed single point of failure. >
 -------------------------------------------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Reviewer's Guide

Rewrites README.md into a comprehensive, dated showcase of llmgate’s Client and Judge seams, provider adapters, middleware ordering, concurrency and cost controls, System One judging, testing, measured results, and ecosystem positioning, while replacing the old diagrams with updated media and removing obsolete SVGs.

Sequence diagram for adaptive limiter retries

sequenceDiagram
    participant Caller
    participant Retry as retry.New
    participant Limiter as limit.Client
    participant Provider

    Caller->>Retry: Complete(ctx, req)
    Retry->>Limiter: Complete(ctx, req)
    Limiter->>Provider: Complete(ctx, req)
    Provider-->>Limiter: rate_limited error
    Limiter->>Limiter: reduce limit and apply Retry-After
    Limiter-->>Retry: error
    Retry->>Limiter: Complete(ctx, req)
    Limiter->>Provider: Complete(ctx, req)
    Provider-->>Limiter: Response
    Limiter-->>Retry: Response
    Retry-->>Caller: Response

Loading

Sequence diagram for batched Judge decisions with context guard

sequenceDiagram
    participant Caller
    participant Judge as typesafe.Judge
    participant Guard as Context guard
    participant Jev as TypeSafe Jev API

    Caller->>Judge: Judge(ctx, JudgeRequest)
    Judge->>Guard: CountTokens(ctx, state and questions)
    Guard-->>Judge: Valid batch or context_length error
    alt batch fits limits
        Judge->>Jev: POST one batch of questions
        Jev-->>Judge: Noul, Choice and Score answers
        Judge-->>Caller: Judgment with Usage
    else batch exceeds limits
        Judge-->>Caller: context_length error
    end

Loading

Flow diagram for the ordered Client middleware stack

flowchart TD
    Request --> Retry[retry.New]
    Retry --> Limit[limit.Client]
    Limit --> Budget[budget.New]
    Budget --> Cache[cache.New]
    Cache --> Router[router.New]
    Router --> Provider[Provider adapter]
    Provider --> Response

    CacheHit[Cache hit] --> Response
    ProviderError[Rate limit or transient error] --> Retry
    ProviderError --> Router

    Budget -. cache hits do not debit .-> Cache
    Limit -. each retry attempt takes a slot .-> Retry

Loading

Flow diagram for provider adaptation and response accounting

flowchart LR
    Request[llmgate.Request] --> Adapter[internal/adapter]
    Adapter --> GenerateContent[langchaingo GenerateContent]
    GenerateContent --> Provider[Anthropic / OpenAI / Gemini]
    Provider --> GenerateContent
    GenerateContent --> Adapter
    Adapter --> Response[llmgate.Response]
    Response --> Usage[Usage and CostUSD]
    Response --> ToolCalls[ToolCalls]
    Response --> Capabilities[Capability flags]

Loading

File-Level Changes

Change	Details	Files
Replaces the README with an implementation-focused walkthrough of llmgate’s two seams and end-to-end request paths.	Introduces Client and Judge interface examples, provider/adaptor boundaries, Anthropic-compatible gateway configuration, and shared error classification. Documents middleware composition and ordering for retry, adaptive limiting, budget enforcement, caching, and routing/fallback. Explains client features including usage/cost normalization, pricing resolution, prompt caching, tool calling, capability flags, and mock-based testing. Adds a detailed Judge/System One section covering Noul, Choice, Score, batching, validation, context limits, the tokenizer guard fix, tracing, and TypeSafe configuration. Adds dated/source-linked measured results, production usage, Go ecosystem comparison, and planned-but-unimplemented features. Updates project status and contact/license information, and adds links to runnable examples and media assets.	README.md
Replaces the previous architecture illustrations with updated diagrams that reflect both Client and Judge paths and the corrected middleware/limiter design.	Removes the obsolete architecture, middleware-stack, and request-flow SVGs. References new PNG diagrams for the banner, two seams, middleware stack, limiter, context guard, and ecosystem comparison.	docs/architecture.svg docs/middleware-stack.svg docs/request-flow.svg docs/media/banner.png docs/media/two-seams.png docs/media/the-stack.png docs/media/the-limiter.png docs/media/the-guard.png docs/media/go-ecosystem.png

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.