# Intelligent Routing & Reputation

In a decentralized network with hundreds or thousands of potential Seller nodes, the quality of routing logic is a critical determinant of the user experience. Poor routing — sending traffic to slow, unreliable, or overpriced providers — directly degrades the Buyer's experience and wastes their USDC. The Peer Router must be intelligent enough to consistently find and select the best available provider for each request, under dynamic network conditions, without any central coordination.

### The Peer Router: Architecture and Objectives

The Peer Router is the decision-making core of the OpenSeed Buyer proxy. It sits between the incoming request from the local application and the outgoing request to the OpenSeed network, making a routing decision for every request based on the current state of available providers.

The Router has three objectives that it must balance simultaneously. Quality maximization means selecting providers that will return accurate, well-formed responses with low latency and high reliability. Cost minimization means selecting providers that offer the requested model capability at competitive prices relative to the Buyer's budget. Resilience means ensuring that routing decisions are robust to provider failures — that a single provider going down or rate-limiting does not interrupt the Buyer's workflow.

These objectives sometimes conflict. The highest-quality provider may not be the lowest-cost provider. The lowest-cost provider may have the least reliable uptime record. The Router's composite scoring algorithm is designed to find an optimal balance point across all three objectives simultaneously, weighted by the Buyer's expressed preferences.

### Composite Reputation Scoring: The Sixty-Forty Framework

Every Seller node in the OpenSeed network carries a Composite Reputation Score that summarizes their historical performance and current pricing into a single comparable number. This score is the primary input to the Peer Router's provider selection logic.

The composite score is calculated from two dimensions: Reputation, which accounts for sixty percent of the total score, and Price, which accounts for the remaining forty percent. This sixty-forty weighting reflects an empirically-grounded judgment that, for most AI inference use cases, reliability and quality matter more than cost. A provider that fails one in ten requests is not worth the savings over a slightly more expensive but perfectly reliable provider.

The Reputation sub-score is itself a composite of three factors. Latency is measured as time-to-first-token — the elapsed time from request submission to the first streaming byte of the response. This metric is chosen over total response time because it captures the most latency-sensitive part of the interaction: the wait before any output is available. Reliability is measured as the ratio of successfully completed requests to total accepted requests over a rolling time window. A provider that serves requests but occasionally fails, times out, or returns malformed responses will have a lower reliability score. Uptime is measured through the Registry's heartbeat monitoring data — the fraction of the measurement period during which the node was actively heartbeating and available.

These three factors are combined into the Reputation sub-score using a weighted average. The exact weights are protocol parameters — currently set at approximately forty percent latency, forty percent reliability, and twenty percent uptime — but these may be adjusted in future protocol versions based on network data.

The Price sub-score compares the Seller's current pricing against the Buyer's configured price cap. A Seller priced at fifty percent of the price cap earns a high price score. A Seller priced at ninety-five percent of the price cap earns a low price score. Sellers priced above the price cap are excluded from the routing pool entirely. This relative pricing approach means that the price score is specific to each Buyer's preferences — a provider that is expensive relative to one Buyer's budget may be competitive relative to another's.

### Dynamic Re-ranking: Session-Level Learning

The Registry data that informs the initial routing decision for a session reflects historical performance — data accumulated from past sessions, weighted toward more recent observations. This historical data is a good predictor of future performance but is not a perfect one. A provider that was excellent yesterday may be experiencing issues today. A provider with a modest historical score may have recently upgraded their hardware and now performs significantly better than their history suggests.

The Peer Router addresses this gap through session-level dynamic re-ranking. Throughout a session, the Router observes the actual performance of the providers it routes traffic to. It measures the latency of each request to each provider, records any failures or errors, and tracks the actual token counts against the estimated counts in invoices.

These session-level observations are used to compute a session-specific performance weight for each provider, which is combined with the historical Registry data to produce a continuously-updated composite score. If a provider consistently delivers lower latency than their historical average suggests, their session-specific weight increases and they receive more routing priority. If a provider fails several requests in a row, their session-specific weight drops sharply and the Router begins routing to alternatives.

This dynamic re-ranking operates on a short time horizon — it reflects current session behavior, not a permanent reputation update. At the end of the session, the local session data may be reported back to the Registry to contribute to the provider's updated historical reputation score. This closing-of-the-loop between session observations and historical data is how the reputation system remains accurate and current across the network as a whole.

### Atomic Fallbacks: Seamless Failure Handling

Atomic fallbacks are the mechanism that makes OpenSeed's reliability properties genuinely superior to centralized alternatives. They are the answer to the question: what happens when the selected provider fails?

In a centralized system, the answer to a provider failure is limited and often bad. The application can retry the request to the same provider — which fails again if the provider is experiencing an outage. Or it can fail the request — which breaks the user's workflow. There is generally no transparent fallback because the application has a single provider configured and no protocol for automatically switching to another.

In OpenSeed, the Peer Router maintains a ranked list of providers for every request, not just a single selection. The top-ranked provider is selected for the first attempt. But if that attempt fails — whether due to a connection timeout, an HTTP 429 rate limit response, an HTTP 500 server error, or any other failure mode — the Router does not surface this failure to the application. Instead, it immediately selects the next provider in the ranked list and resubmits the request.

This fallback logic is "atomic" in the sense that it is transparent to the application. The application sends a request and receives a response. The number of provider attempts that occurred between the request and the response is invisible to the application. The Buyer proxy absorbs all the failure and retry logic internally, presenting the application with a clean interface that either returns a successful response or, only after all ranked fallback options have been exhausted, returns an error.

The fallback selection is intelligent rather than mechanical. The Router does not simply try providers in a fixed order. It selects fallback providers based on the same composite scoring logic as primary selection, but adjusted for current session observations. A provider that was ranked second globally but has been performing well in this session may be the first fallback choice. A provider that was ranked third globally but has shown signs of degraded performance may be skipped in favor of a fourth-ranked provider with a better current session record.

### Model-Specific Routing and Preference Configuration

Not all routing decisions are purely about price and reputation. Buyers can configure model-specific routing preferences that add additional logic to the routing process.

Model pinning allows a Buyer to configure specific providers for specific models — for example, always using a particular Seller for Llama 3 70B requests while using the general scoring algorithm for all other models. This is useful when a Buyer has established a trusted relationship with a specific high-quality provider for a critical workload.

Quality tiers allow a Buyer to define different routing strategies for different request types. A request flagged as high-priority might route only to providers with reputation scores above a certain threshold, accepting higher prices in exchange for reliability assurance. A request flagged as best-effort might be routed primarily on price, accepting lower-reputation providers that offer significantly cheaper inference.

Fallback model configuration allows a Buyer to specify alternative models that can substitute for the primary requested model when all providers for the primary model are unavailable or rate-limited. This is particularly useful for production workloads where continuity is more important than model consistency — for example, allowing fallback from a GPT-4o-equivalent model to a Llama 3 70B equivalent when the former is unavailable.

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.openseed.gg/core-concepts/intelligent-routing-and-reputation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.