LLM for Computational Social Science

Runnable guidance and examples for using LLM APIs in computational social science research, from a first API call to processing tens of thousands of text messages efficiently and at low cost.

Read the tutorial on the website: https://yang3kc.github.io/llm_for_css/

The website is the canonical version of the tutorial. This repository holds its source: the notebooks and scripts, and the MkDocs configuration that builds the site.

Running the code locally

1. Clone the repository and install the dependencies with uv:

   uv sync

2. Set your API key. Never put the key in a script or notebook. Either export it as an environment variable:

   export OPENAI_API_KEY="<your OpenAI API key>"

   or copy .env.template to .env and fill it in (.env is git-ignored). The API key section on the website has the details, including how to do this on Colab.

3. Run a script, for example:

   uv run async_programming/async_template.py

   or open a notebook from docs/ in Jupyter.

Repository layout

Path	Contents
docs/	The website pages: the notebooks (*.ipynb), the markdown pages, and the batch example's .jsonl files
async_programming/, batch_processing/, local_llms/	Scripts that the chapters embed or link to
basics/, structured_output/	Pointer READMEs kept for old links; the content moved to notebooks in docs/
mkdocs.yml	Site configuration (Material for MkDocs)
.env.template	Template for the local .env file

To preview the website locally:

uv sync --group docs
uv run mkdocs serve

The site is deployed to GitHub Pages by a GitHub Actions workflow on every push to main.

Versions

• v3.0 (current): The tutorial became a website. Every runnable chapter is a Jupyter notebook with an Open in Colab badge, the OpenAI content is updated to the GPT-5.6 models, and there are new chapters for the Anthropic API, open-source models via OpenRouter, and local LLMs with Ollama (laptop and GPU workstation).
• v2.0: Responses API, structured output via the text format method, dependencies managed with uv. Available at the v2.0 tag.
• v1.0: Chat Completions API. Available at the v1.0 tag.

Questions and contributions

If you have questions or suggestions, please open an issue. Pull requests are also welcome.

About

Created by Kaicheng Yang with help from Claude Code.

You may also find other tools from our lab useful:

• daily_arxiv_digest: Using LLMs to select interesting arXiv papers
• LLM Domain Classification dashboard: Evaluate LLMs' ability to classify domains into different categories
• DomainDemo explorer: Check user demographics of over 129,000 domains
• Scicolor Color Picker: A collection of color schemes for scientific visualization
• yanglabkit: A set of opinionated AI agent skills for research