kyu823/silicon-sampling-lab

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

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:

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. 1.Create or connect a Docker Space for this repository.
2. 2.Add the above secrets in the Space settings.
3. 3.Deploy the Space.
4. 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:

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:

python3 scripts/download_nemotron_personas_korea.py
python3 scripts/build_nemotron_persona_index.py

Downloaded dataset files are intentionally ignored by git.