---
title: Silicon Sampling Lab
emoji: 📊
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
---

# Silicon Sampling Lab

Korean silicon-sampling web app for running persona-agent survey simulations with OpenAI API calls.

This repository contains only the silicon sampling app:

- React/Vite frontend
- Python standard-library HTTP server
- LLM-backed silicon sampling runtime
- local Nemotron-Personas-Korea dataset helpers

It does not include the broader multi-framework social simulation UI.

## Local Run

```bash
npm ci
npm run build
python3 -m pip install -r requirements.txt
OPENAI_API_KEY=... python3 server.py --host 127.0.0.1 --port 8765
```

Open:

```text
http://127.0.0.1:8765/silicon/
```

## Hugging Face Spaces

This repo is configured as a Docker Space. For Hugging Face Spaces, set secrets in the Space dashboard under Settings → Secrets, not in a committed file.

Required secrets:

- `OPENAI_API_KEY`: your OpenAI API key. This is required for the LLM-backed simulation runs.

Optional secrets:

- `HF_LOG_REPO_ID`: Hugging Face Dataset repo for run logs. Defaults to `kyu823/silicon-sampling-logs`.
- `HF_LOG_TOKEN`: Hugging Face token with write access to the log dataset repo. If omitted, the backend falls back to `HF_TOKEN`.
- `HF_LOG_REPO_PRIVATE`: set to `true` to create/use a private log dataset repo.

Deployment flow:

1. Create or connect a Docker Space for this repository.
2. Add the above secrets in the Space settings.
3. Deploy the Space.
4. The app listens on port `7860`.

The backend reads these values from environment variables, so Space secrets are the correct way to provide them. Without `OPENAI_API_KEY`, the app can still start, but the simulation run will fail when the LLM call is attempted.

## Logs

Every completed silicon-sampling run is logged anonymously. By default logs are written to SQLite:

- `/data/silicon_logs.sqlite3` if a persistent Space volume is mounted
- `runs/silicon_logs.sqlite3` locally
- `/app/runs/silicon_logs.sqlite3` on a default Hugging Face Docker Space without persistent storage

Hugging Face Dataset mirroring is optional and recommended for deployed runs. To enable it, set:

```text
HF_LOG_REPO_ID=kyu823/silicon-sampling-logs
HF_LOG_TOKEN=<write token>
HF_LOG_REPO_PRIVATE=true
```

When enabled, each run also writes one JSON file to the dataset repo under `runs/YYYY-MM-DD/`. The JSON includes respondent settings, question definitions, and aggregate result summaries; raw LLM responses are not mirrored.

## Optional Nemotron Dataset

The app works with fallback distributions if the local dataset is not present. To enable local Nemotron-Personas-Korea metadata and sampling:

```bash
python3 scripts/download_nemotron_personas_korea.py
python3 scripts/build_nemotron_persona_index.py
```

Downloaded dataset files are intentionally ignored by git.