​
Basic usage

Predictions are asynchronous and take ~20 seconds to run. Please see the section on handling async results for more details.
from semilattice import Semilattice

semilattice = Semilattice()

response = semilattice.predictions.create(
    population_id="population-id", # Replace with specific ID
    predictions={
        "question": "Which is worse?",
        "answer_options": ["Tech debt", "Confusing error messages"],
        "question_options": {"question_type": "single-choice"}
    }
)

​
Choosing population models

require a specific population model ID. Call the list method on populations to get a list of population models available for simulation. 
response = semilattice.populations.list()
populations = response.data
Alternatively, you can navigate to the populations page on your dashboard and select a population model to use. Copy the ID from the population’s metadata or from the address bar.

Click to copy the population model's ID

​
Question types

​
Single-choice Questions

Simulates respondents selecting exactly one option: 
response = semilattice.predictions.create(
    population_id="population-id",
    predictions={
        "question": "What's your preferred IDE?",
        "answer_options": ["VS Code", "IntelliJ", "Vim", "Sublime Text"],
        "question_options": {"question_type": "single-choice"}
    }
)

​
Multiple-choice Questions

Simulates respondents selecting multiple options: 
response = semilattice.predictions.create(
    population_id="population-id",
    predictions={
        "question": "Which programming languages do you use regularly?",
        "answer_options": ["Python", "JavaScript", "Java", "Go", "Rust"],
        "question_options": {"question_type": "multiple-choice"}
    }
)

​
Handling async results

Simulations run asynchronously. The initial response has status: "Queued", and you need to poll for completion.

​
Initial response

{
    {
        "id": "84a92e29-54e6-4a60-862d-26cd2a78421e",
        "status": "Queued",
        "question": "Which is worse?",
        "answer_options": ["Tech debt", "Confusing error messages"],
        "predicted_answer_percentages": null,
        // ... other fields
    }
}

​
Polling for results

The simulation will progress through these statuses: Queued → Running → Predicted (or potentially Failed). Predictions typically take less than 20 seconds. 
import time

prediction = response.data[0]

while prediction.status != "Predicted":
    time.sleep(1)
    response = semilattice.predictionss.get(prediction.id)
    prediction = response.data

print("Prediction complete!")

​
Understanding results

The predicted_answer_percentages field shows the population-level predicted distribution across your answer options: 
{
    "id": "84a92e29-54e6-4a60-862d-26cd2a78421e",
    "status": "Predicted",
    "question": "Which is worse?",
    "answer_options": ["Tech debt", "Confusing error messages"],
    "predicted_answer_percentages": {
        "Tech debt": 0.5488,
        "Confusing error messages": 0.4512
    }
}
This means:
  • 54.88% of the population would choose “Tech debt”
  • 45.12% would choose “Confusing error messages”

​
Best practices

  • Choose the right population: Select populations built on data similar to your target audience and question topics.
  • Review population metrics: Check the population’s evaluation scores before relying on predictions for critical decisions.
  • Use clear questions: Write unambiguous questions with distinct answer options to get reliable predictions.
  • Benchmark use cases: Test your population with known questions before using it for important predictions.