Metadata-Version: 2.5
Name: elythera-experttrace
Version: 0.1.2
Summary: Open-source toolkit for eliciting, structuring, and auditing expert knowledge.
Project-URL: Homepage, https://github.com/elythera-lab/experttrace
Project-URL: Repository, https://github.com/elythera-lab/experttrace
Project-URL: Issues, https://github.com/elythera-lab/experttrace/issues
Author: Elythera Labs
License: Apache-2.0
License-File: LICENSE
Keywords: ai-governance,knowledge-management,responsible-ai,tacit-knowledge
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Provides-Extra: bedrock
Requires-Dist: boto3>=1.28.57; extra == 'bedrock'
Requires-Dist: litellm>=1.70; extra == 'bedrock'
Provides-Extra: llm
Requires-Dist: litellm>=1.70; extra == 'llm'
Description-Content-Type: text/markdown

# ExpertTrace Python SDK

[![Install from PyPI](https://img.shields.io/badge/install-pip%20install%20elythera--experttrace-3775A9?logo=pypi&logoColor=white)](https://pypi.org/project/elythera-experttrace/)
[![Latest PyPI version](https://img.shields.io/pypi/v/elythera-experttrace?label=latest%20version)](https://pypi.org/project/elythera-experttrace/)

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](https://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](https://github.com/elythera-lab/experttrace),
while PyPI is the distribution channel. See the
[PyPI package](https://pypi.org/project/elythera-experttrace/) and the
[Elythera Labs publisher profile](https://pypi.org/user/elythera-lab/).

## Install

Core toolkit, with no runtime dependencies or model calls:

```bash
pip install elythera-experttrace
```

Toolkit plus the LiteLLM adapter:

```bash
pip install "elythera-experttrace[llm]"
```

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

```bash
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

```python
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:

```python
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:

```python
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:

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

Adaptive mode:

```bash
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:

```bash
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.
