​
What is “consensus”?

Consensus is about asking several language‑model instances the same question in parallel, then merging their structured outputs into a single, consolidated result.

Consensus offers higher reliability for extraction tasks, zero‑shot majority voting, uncertainty quantification, and automatic guard‑rail against hallucination—without changing your business logic.

Related to Palantir’s K-LLM strategy: This approach follows similar principles to Palantir’s “K-LLMs” methodology, where multiple models evaluate the same prompt and their outputs are synthesized for increased accuracy, confidence, and reduced hallucinations. Like Palantir’s approach, UiForm’s consensus mechanism helps mitigate biases from any single model while providing flexibility across different LLM providers.

​
How it works

Under the hood UiForm:

  1. Fires n_consensus identical calls.

  2. Parses each raw answer into a Pydantic model / JSON‑Schema object.

  3. Runs a deterministic reconciliation strategy

    • Exact match vote for scalar fields.
    • Deep merge for arrays / objects when all candidates agree on shape.

  4. Returns the reconciled object in response.output_parsed (Responses) or completion.choices[0].message.parsed (Completions).

If any response fails JSON validation the call is retried once; after that a ConsensusError is raised.

We provide a quick, type‑safe wrapper around OpenAI Chat Completions and Responses endpoints with automatic consensus reconciliation.

  • Step 1: Generating diverse answers. We purposely sample each call with temperature > 0 to obtain distinct answers.

  • Step 2: SOTA reconciliation. A bespoke, finetuned LLM (code‑name reconcile‑v1) performs fuzzy string matching and majority‑vote reasoning to merge the candidates with state‑of‑the‑art accuracy.

​
Quick‑Start: Switch in One Line

-  from openai import OpenAI
-  client = OpenAI()
+  from uiform import UiForm
+  uiclient = UiForm()

-  response = client.responses.create(
+  response = uiclient.consensus.responses.create(
      model="gpt-4.1",
      input="Write a one-sentence bedtime story about a unicorn."
+     n_consensus=4
  )

 print(response.output_text)
 event = response.output_parsed

-  from openai import OpenAI
-  client = OpenAI()
+  from uiform import UiForm
+  uiclient = UiForm()

- completion = client.chat.completions.create(
+  completion = uiclient.consensus.completions.create(
      model="gpt-4.1",
      messages=[
          {
              "role": "user",
              "content": "Write a one-sentence bedtime story about a unicorn."
          }
      ],
+     n_consensus=4
  )

 print(completion.choices[0].message.content)

Everything else (models, schema, temperature, etc.) stays untouched.

​
Completions API

MethodDescription
client.consensus.completions.parse(...)Chat completion that returns a parsed object plus the raw OpenAI response.

​
Minimum Arguments

NameTypeDefaultNotes
modelstr—Any OpenAI chat model name.
messageslist[dict]—Same shape as OpenAI’s messages.
response_formatpydantic.BaseModel or dict JSON‑Schema—Target structure.
n_consensusint1>1 enables consensus.

​
Example

from uiform import UiForm
from pydantic import BaseModel

uiclient = UiForm()

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = uiclient.consensus.completions.parse(
    model="gpt-4.1",
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
    ],
    response_format=CalendarEvent,
    n_consensus=4
)

event = completion.choices[0].message.parsed

​
Responses API

Use when you have a single prompt + single expected answer (e.g., function‑calling, multi‑step reasoning).

MethodDescription
client.consensus.responses.parse(...)Thin wrapper for the /responses endpoint; consensus works the same way.

​
Arguments

Same as Completions API: model, input, text_format|text_schema, n_consensus.

​
Example

from uiform import UiForm
from pydantic import BaseModel

uiclient = UiForm()

class Step(BaseModel):
    explanation: str
    output: str

class MathReasoning(BaseModel):
    steps: list[Step]
    final_answer: str

response = uiclient.consensus.responses.parse(
    model="gpt-4o-2024-08-06",
    input=[
        {
            "role": "system",
            "content": "You are a helpful math tutor. Guide the user through the solution step by step.",
        },
        {"role": "user", "content": "how can I solve 8x + 7 = -23"},
    ],
    text_format=MathReasoning,
    n_consensus=4
)

math_reasoning = response.output_parsed

​
Reconcile API

MethodDescription
client.consensus.reconcile(...)Direct access to reconcile multiple dictionaries into a single consensus result.

​
Arguments

NameTypeDefaultNotes
list_dictslist[dict]—List of dictionaries to reconcile.
reference_schemadictNoneOptional schema to validate dictionaries against.
modeLiteral["direct", "aligned"]"direct"Mode for consensus computation.
idempotency_keystrNoneOptional idempotency key for the request.

​
Example

from uiform import UiForm

uiclient = UiForm()

# List of dictionaries to reconcile
results = [
    {"name": "Science Fair", "date": "2023-06-15", "participants": ["Alice", "Bob"]},
    {"name": "Science Fair", "date": "2023-06-15", "participants": ["Alice", "Bob", "Charlie"]},
    {"name": "Science Exhibition", "date": "2023-06-15", "participants": ["Alice", "Bob"]}
]

# Optional schema
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "date": {"type": "string"},
        "participants": {
            "type": "array",
            "items": {"type": "string"}
        }
    },
    "required": ["name", "date", "participants"]
}

# Reconcile the dictionaries
consensus_result = uiclient.consensus.reconcile(
    list_dicts=results,
    reference_schema=schema,
    mode="direct"
)

# Access the reconciled data and confidence scores
reconciled_data = consensus_result["data"]
confidence = consensus_result["likelihoods"]