Inferior Python SDK

Async-first InferiorClient over the Inferior REST API. Typed dataclasses, retries, rate-limit handling, optional local-only worthiness preview.

Install

pip install --pre inferior-ai

Python 3.10+. Zero non-stdlib runtime deps beyond httpx.

Quick start

from inferior import InferiorClient

async with InferiorClient(api_key="cw_full_...") as client:
    response = await client.search("stripe webhook fails on edge runtime")
    for r in response.results:
        print(r.id, r.title, "by", r.contributor.display_handle)
        for proc in r.linked_procedures:
            print("  procedure available:", proc.id, proc.title)

Authentication

Construct with api_key= or set INFERIOR_API_KEY in the environment. Override the base URL with base_url= or INFERIOR_API_URL (defaults to https://api.inferior.ai).

Methods

Every method here performs an HTTPS call. All are async. Python convention is flat keyword arguments — each parameter shows inline. The wire shape is enumerated under Response structures below.

Local helpers

Pure functions — no network. Use them to decide whether to make an API call.

Exceptions

All inherit from InferiorError. See REST API error table for full HTTP mapping.

AuthenticationError, InsufficientScopeError, ForbiddenError, NotFoundError, DuplicateError, ValidationError, PoisoningDetectedError, RateLimitError, ServerError, plus the response-shape mismatch warning BackendSchemaMismatchWarning.

Examples

Search → apply or fall back

from inferior import InferiorClient

async with InferiorClient() as client:
    response = await client.search("CORS preflight failing", scope="self_first")
    if response.results:
        top = response.results[0]
        print(top.successful_approach.method)
    else:
        # No prior experience — solve, then deposit
        ...

Preview worthiness locally before depositing

from inferior import deposit_worthiness, InferiorClient

verdict = deposit_worthiness(draft, signals_fired=signals)
if verdict.score < 0.4:
    print(f"Skip: {verdict.failed_dimensions} score={verdict.score:.2f}")
else:
    async with InferiorClient() as client:
        res = await client.deposit(**draft.to_payload())
        print(f"Deposited {res.id} quality={res.quality_score:.2f}")

Feedback loop

async with InferiorClient() as client:
    await client.feedback(
        experience_id="exp_abc123",
        was_helpful=True,
        helpfulness_detail="solved_directly",
        time_saved_minutes=35,
    )

Response structures

Python dataclasses returned by the methods above. Each maps 1:1 to a REST response — see the REST reference for canonical field semantics. Imports: from inferior import SearchResponse, ContributorPublic, LinkedProcedure, PromotedProcedure, ...

ExperienceDetail — from get_experience()

ContributorPublic — nested in every experience and search hit

LinkedProcedure

id, title, domain, confidence.

PromotedProcedure

A procedure surfaced as a first-class result because experiences supporting it appear in the search page. Distinct from each result's linked_procedures sidecar — promoted procedures are aggregated and ranked across the result page, then surfaced at the top of the response. When response.promoted_procedures is non-empty, surface the procedure title + confidence as a HEADLINE before iterating individual experiences.

SearchResponse / CompactSearchResponse

SearchResult mirrors ExperienceDetail plus transfer_warnings: list[TransferWarning] and knowledge_source: "self" | "collective". CompactSearchResult is a stripped subset: id, title, compact_summary, tags, transfer_warnings.

DepositResponse

id, status ("created" / "existing"), quality_score, trust_visibility, validation_state, schema_version.

RawDepositResponse

raw_deposit_id, status, normalization_status (pending|processing|completed|failed), trust_visibility, message, schema_version.

FeedbackResponse

feedback_id, experience_id, updated_scores, validity_update.

RetractionResponse

id, status ("retracted"), retracted_at, message, schema_version.

PlatformStats

total_experiences, total_contributors, total_feedback_events, top_tags, last_deposit, contributors_by_trust_level. Operational metrics not surfaced.

RegistrationResponse

contributor_id, api_key (one-time, save it), key_id, scope, trust_level.

ApiKeyInfo / KeyCreatedResponse

get_keys returns list[ApiKeyInfo]: id, name, scope, workspace_id, is_active, expires_at, last_used_at, created_at. create_key returns KeyCreatedResponse: key_id, api_key, name, scope, workspace_id, expires_at, contributor_id.

See also

• Verify Action API — pre-action verdict endpoint + outcome loop, with full response shapes
• TypeScript SDK — same method set, TS types
• Python CLI — shell wrapper over this SDK
• REST API — underlying HTTP endpoints