Blame for README.md

---
title: SML Conversation Tree Explorer
emoji: 🌳
colorFrom: purple
colorTo: green
sdk: docker
app_port: 7860
pinned: true
short_description: Explore conversation trees with a traceable Python decoder
---

# SML Conversation Tree Explorer

Follow recorded conversation branches in real time. Every selected response keeps
its full history, original tile metadata and JSON pointer back to its source.

[Open the live explorer](https://huggingface.co/spaces/SMLBuilder/SML-Tree-Explorer)
· [Public dataset and decoder](https://huggingface.co/datasets/SMLBuilder/SML-Conversation-Trees)
· [SMLBuilder](https://huggingface.co/SMLBuilder)

## What the demo does

Choose a file and conversation, select a recorded reply, then follow its exact
continuation. Rewind to any selection to explore another branch. Inspect a turn's
original metadata or download a replayable trace containing the full conversation,
zero-based branch indices, pinned repository revision and verified content hash.
Share a link to the same file, conversation and path.

The catalog references the existing public AAC Children and TinkyBrain corpora at
pinned revisions. Files load on demand; one small public starter file is bundled
for immediate use. Source bytes must match their recorded Git/LFS hash before
decoding. Dataset files include trees, linear chats and derived training tables;
unsupported files are explicitly identified rather than turned into conversations.

The runtime has **no neural inference, model weights, GPU requirement or API key**.
It replays recorded content; it does not validate its accuracy or turn specialist
training examples into professional advice.

## Lightweight decoder

`tree_decoder.py` is standalone Python 3.9+ with no third-party dependencies.
It extends the original AAC CLI's branch walker with path-preserving history,
multiple native schemas, exact source pointers, linear-chat replay and JSONL export.
The original is preserved unchanged in `public_decoder/AAC_cli_original.py`.

```sh
python3 tree_decoder.py conversation.json --list
python3 tree_decoder.py conversation.json --conversation 0 --path 0,2,1
python3 tree_decoder.py conversation.json --all > traces.jsonl
```

Supported native schemas: `question/branches/answer`,
`initial_statement/response_branches/aac_response`, hospital `root/doctor/patient`,
both caller/dispatcher orientations, and recorded `messages` sequences. Sentence
text, code examples and metadata are retained exactly. Equal text does not merge
branches. Nested continuations never become separate conversation roots.

`--all` walks every reachable state in every recognized root and includes complete
history for each path. A malformed branch raises an explicit error. An unsupported
file does not silently become a successful empty export. The web interface limits
paths to 128 selections and source files to 64 MiB; the standalone decoder does not
apply those limits. Files can have multiple roots and independently terminating
branches.

## Run and verify

```sh
python3 -B -m unittest discover -s tests -v
python3 app.py
```

Open `http://localhost:7860`. The Docker Space uses Python's standard-library HTTP
server on port 7860, with bounded request concurrency and a three-document LRU
cache. No dependency installation is needed. Runtime state is ephemeral; visitor
paths are encoded in their share links, not saved as personal conversations.

Public read-only endpoints: `/health`, `/api/catalog`, `/api/document?id=…`,
`/api/trace?id=…&conversation=0&path=0,2`, and `/api/export` with the same parameters.
Unrecognized IDs, out-of-range branches, source-integrity failures and unsupported
continuations fail explicitly. Only catalog-listed public URLs can be fetched.

## Provenance and publication scope

The original walker is available in the public
[AAC Children dataset](https://huggingface.co/datasets/SMLBuilder/AAC_Children_Conversations/blob/c060d83904330dd578167e29d7714becd7aaec17/AAC_cli.py).
The catalog records exact source revisions, filenames and Git/LFS hashes. Upstream
dataset terms remain applicable; this showcase does not grant additional rights
to underlying material. Recovery archives, machine-path manifests, credentials and
personal runtime history are excluded from this public release.