ExpertTrace Python SDK

ExpertTrace is an open-source toolkit for eliciting, structuring, and auditing expert judgment. It runs as a deterministic local workflow by default. An optional LLM layer can ask targeted follow-ups when an expert's answer needs more specificity.

Interactive demo

Explore the six-question capture flow and inspect an example knowledge card: elythera-lab.github.io/experttrace

The browser demonstration runs locally in your browser. The installable Python package provides the full toolkit and optional LLM integration.

GitHub is the home for source code and documentation, while PyPI is the distribution channel. See the PyPI package and the Elythera Labs publisher profile.

Install

Core toolkit, with no runtime dependencies or model calls:

pip install elythera-experttrace

Toolkit plus the LiteLLM adapter:

pip install "elythera-experttrace[llm]"

For Amazon Bedrock, install the provider-specific extra, which includes the AWS SDK required by LiteLLM:

pip install "elythera-experttrace[bedrock]"

For local development, clone the repository and use pip install -e . or pip install -e ".[llm]". The distribution is named elythera-experttrace; Python imports and the CLI use experttrace.

Deterministic quickstart

from experttrace import InterviewSession

session = InterviewSession(
    topic="Reviewing high-risk AI use cases",
    domain="AI governance",
    owner="AI Governance Council",
)

while not session.is_complete:
    prompt = session.current_prompt
    session.answer(input(f"{prompt.question}\n> "))

card = session.compile()
print(card.to_json())
print(session.audit().summary())

Adaptive quickstart

Install the llm extra, configure the environment variable required by your chosen provider, and pass a model:

from experttrace import InterviewSession, LiteLLMProvider

session = InterviewSession(
    topic="Reviewing high-risk AI use cases",
    llm=LiteLLMProvider("openai/gpt-5"),
    max_follow_ups_per_prompt=1,
)

while not session.is_complete:
    prompt = session.current_prompt
    if prompt.is_follow_up:
        print(f"Follow-up to {prompt.parent_key} (#{prompt.follow_up_number})")
    session.answer(input(f"{prompt.label}\n{prompt.question}\n> "))

print(session.compile().to_json())

LiteLLM supports hosted providers and local runtimes. Model names and credentials follow the selected provider's LiteLLM configuration. Keep credentials in environment variables; never put them in source code or interview answers.

If you already have a model client, adapt it without installing LiteLLM:

from experttrace import CallableLLM, InterviewSession

def decide(system_prompt: str, user_prompt: str) -> dict:
    # Call your existing client and return the parsed JSON object.
    return {"should_ask": False, "question": "", "reason": "Sufficient detail."}

session = InterviewSession(
    topic="Vendor risk review",
    llm=CallableLLM(decide),
)

The callback must return should_ask as a boolean plus string question and reason fields.

InterviewPrompt exposes adaptive metadata directly. Use prompt.is_follow_up or compare prompt.kind with PromptKind.FOLLOW_UP; do not infer prompt roles from the generated key. For a follow-up, parent_key identifies the owning protocol prompt and follow_up_number is its one-based sequence number.

CLI

Deterministic mode:

experttrace interview \
  --topic "Reviewing high-risk AI use cases" \
  --domain "AI governance" \
  --owner "AI Governance Council" \
  --output knowledge-card.json

Adaptive mode:

export OPENAI_API_KEY="..."
experttrace interview \
  --topic "Reviewing high-risk AI use cases" \
  --model openai/gpt-5 \
  --max-follow-ups 1 \
  --output knowledge-card.json

Audit a saved card:

experttrace audit knowledge-card.json

By default, model failures produce a warning and the deterministic interview continues. Add --strict-llm if a model failure should stop the run.

What the LLM does—and does not do

The optional model evaluates each base answer and may generate concise follow-ups about missing thresholds, exceptions, evidence, or escalation rules, up to max_follow_ups_per_prompt for each base question. The JSON compilation and quality audit remain deterministic. Expert approval remains explicit; the model never certifies that captured knowledge is true.

Privacy behavior is clear at the integration boundary:

• Deterministic mode sends nothing to a model provider.
• Adaptive mode sends the topic, domain, current question, and current answer to the provider chosen by the user.
• ExpertTrace does not require an Elythera service or account.

Design principles

• Offline and dependency-free by default.
• Portable, reviewable knowledge-card JSON.
• Replaceable interview protocols and model providers.
• Explainable audit findings instead of only a score.
• Model calls are opt-in and degrade gracefully unless strict mode is enabled.

Status

Version 0.1.2 is an alpha research release. It helps structure expert-provided knowledge; it does not replace professional review or establish factual truth.

Licensed under Apache-2.0.