{"id":34021117,"url":"https://github.com/josh-ashkinaze/plurals","last_synced_at":"2026-02-22T12:24:04.926Z","repository":{"id":237755796,"uuid":"795184123","full_name":"josh-ashkinaze/plurals","owner":"josh-ashkinaze","description":"Plurals: A System for Guiding LLMs Via Simulated Social Ensembles","archived":false,"fork":false,"pushed_at":"2025-11-20T10:45:30.000Z","size":15237,"stargazers_count":28,"open_issues_count":6,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-27T19:02:52.734Z","etag":null,"topics":["artificial-intelligence","democracy","democracy-enhancing-technologies","ethics-in-ai","lllm","multi-agent-system","pluralism"],"latest_commit_sha":null,"homepage":"https://josh-ashkinaze.github.io/plurals/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/josh-ashkinaze.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-05-02T18:42:01.000Z","updated_at":"2025-11-19T12:22:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"f13355f5-e590-4ee3-85e3-c1a32fa3b210","html_url":"https://github.com/josh-ashkinaze/plurals","commit_stats":null,"previous_names":["josh-ashkinaze/plurals"],"tags_count":62,"template":false,"template_full_name":null,"purl":"pkg:github/josh-ashkinaze/plurals","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josh-ashkinaze%2Fplurals","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josh-ashkinaze%2Fplurals/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josh-ashkinaze%2Fplurals/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josh-ashkinaze%2Fplurals/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/josh-ashkinaze","download_url":"https://codeload.github.com/josh-ashkinaze/plurals/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josh-ashkinaze%2Fplurals/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27708211,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-13T02:00:09.769Z","response_time":147,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","democracy","democracy-enhancing-technologies","ethics-in-ai","lllm","multi-agent-system","pluralism"],"created_at":"2025-12-13T15:43:55.168Z","updated_at":"2026-02-22T12:24:04.920Z","avatar_url":"https://github.com/josh-ashkinaze.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Plurals: A System for Guiding LLMs Via Simulated Social Ensembles\n    \n**Package Stats 📊**\n\n![PyPI - Downloads](https://img.shields.io/pypi/dm/plurals)\n![GitHub last commit](https://img.shields.io/github/last-commit/josh-ashkinaze/plurals)\n![GitHub Created At](https://img.shields.io/github/created-at/josh-ashkinaze/plurals)\n\n**Package Build (Tests/Doc Creation/PyPi Releases) 👌**\n\n[![Build](https://github.com/josh-ashkinaze/plurals/actions/workflows/ci.yml/badge.svg)](https://github.com/josh-ashkinaze/plurals/actions/workflows/ci.yml)\n![PyPI](https://img.shields.io/pypi/v/plurals)\n[![Push to pypy](https://github.com/josh-ashkinaze/plurals/actions/workflows/python-publish.yml/badge.svg)](https://github.com/josh-ashkinaze/plurals/actions/workflows/python-publish.yml)\n\n**Paper 📜** [(Click here!)](https://arxiv.org/abs/2409.17213)\n\n**Documentation 📋** [(Click here!)](https://josh-ashkinaze.github.io/plurals/)\n\n\n# Cite ℹ️\nIf you use Plurals in your research, please cite the following [paper](https://arxiv.org/abs/2409.17213) appearing at CHI 25 (Honorable Mention):\n\n_Bibtex:_\n```\n@inproceedings{ashkinaze2025plurals,\n  author = {Ashkinaze, Joshua and Fry, Emily and Edara, Narendra and Gilbert, Eric and Budak, Ceren},\n  title = {Plurals: A System for Guiding LLMs Via Simulated Social Ensembles},\n  booktitle = {CHI Conference on Human Factors in Computing Systems},\n  series = {CHI '25},\n  year = {2025},\n  month = may,\n  location = {Yokohama, Japan},\n  publisher = {Association for Computing Machinery},\n  address = {New York, NY, USA},\n  pages = {1--27},\n  numpages = {27},\n  doi = {10.1145/3706598.3713675},\n  url = {https://doi.org/10.1145/3706598.3713675}\n}\n```\n\n_APA:_\n```\nAshkinaze, J., Fry, E., Edara, N., Gilbert, E., \u0026 Budak, C. (2025). Plurals: A system for guiding LLMs via simulated social ensembles. In CHI Conference on Human Factors in Computing Systems (CHI '25, pp. 1-27). Association for Computing Machinery. https://doi.org/10.1145/3706598.3713675\n```\n# Overview 🌌\n\u003cimg src=\"https://raw.githubusercontent.com/josh-ashkinaze/plurals/main/assets/figure1.png\" alt=\"System Diagram\" width=\"100%\"\u003e\n\nPlurals is an end-to-end generator of simulated social ensembles. (1) **Agents** complete tasks within (2) **Structures**, with communication optionally summarized by (3) **Moderators**. Plurals integrates with government datasets (1a) and templates, some inspired by democratic deliberation theory (1b). \n\nThe building block is Agents, which are large language models (LLMs) that have system instructions and tasks. System instructions can be generated from user input, government datasets (American National Election Studies; ANES), or persona templates. Agents exist within Structures, which define what information is shared. Combination instructions tell Agents how to combine the responses of other Agents when deliberating in the Structure. Users can customize an Agent's combination instructions or use existing templates drawn from deliberation literature and beyond. Moderators aggregate responses from multi-agent deliberation.\n\nPlurals includes support for multiple information-sharing structures (e.g., chains, graphs, debates, ensembles) and [templates](https://github.com/josh-ashkinaze/plurals/blob/main/plurals/instructions.yaml) for customizing LLM deliberation within these.\n\n# Updates 🆕\n1. Paper to appear at CHI 2025 with Honorable Mention!\n2. Changes to debate to decrease sycophancy\n3. Names of Agents in DAG are visible to other Agents \n4. Feature update: Added a best-of-n feature for Agents. This supports things like verifiable rewards and LLM as a Judge. Best-of-n can be used inside of Structures, where different Agents have different optimizing objectives. See the [tutorial](https://josh-ashkinaze.github.io/plurals/tutorial_6_best_of_n.html) on this for details.\n5. Feature update: Added `Interview` class for building rich, story-based personas via simulated interviews, inspired by [1](https://arxiv.org/abs/2504.11673). Also, an Agent can also automatically generate task-specific interview questions (returned as structured JSON), which are then used to conduct a targeted interview. See the [tutorial](https://josh-ashkinaze.github.io/plurals/tutorial_7_interview.html) for details.\n\n# Detailed Documentation 📋\n\nhttps://josh-ashkinaze.github.io/plurals/\n\n# Quick Start ⚡\n\n## Installation\n\n```markddown\npip install plurals\n```\n\n## Set environment variables\n\n```python\n\nimport os\nos.environ[\"OPENAI_API_KEY\"] = 'your_openai_key'\nos.environ[\"ANTHROPIC_API_KEY\"] = 'your_anthropic_key'\n```\n\n## Create a nationally representative ensemble of Agents portrayed by different LLMs\n\n```python\nfrom plurals.agent import Agent\nfrom plurals.deliberation import Ensemble, Moderator\n\ntask = \"What, specifically, would make commuting on a bike more appealing to you? Answer from your perspective. Be specific. You are in a focus group.\"\nagents = [Agent(persona='random', model='gpt-4o') for _ in range(20)]\nensemble = Ensemble(agents=agents, task=task)\nensemble.process()\nfor r in ensemble.responses:\n    print(r)\n\n```\n\n## Create a directed acyclic graph of Agents for story development\n\n\u003cdiv style=\"text-align: center;\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/josh-ashkinaze/plurals/main/assets/mermaid_diagram.svg\" alt=\"System Diagram\" width=\"80%\"\u003e\n\u003c/div\u003e\n\n```python\nfrom plurals.agent import Agent\nfrom plurals.deliberation import Graph, Moderator\n\n\nstory_prompt = \"\"\"\nCraft a mystery story set in 1920s Paris. \nThe story should revolve around the theft of a famous artwork from the Louvre.\n\"\"\"\n\nagents = {\n    'plot': Agent(\n        system_instructions=\"You are a bestselling author specializing in mystery plots\",\n        model=\"gpt-4\",\n        combination_instructions=\"Develop the plot based on character and setting inputs: \u003cstart\u003e${previous_responses}\u003c/end\u003e\"\n    ),\n    'character': Agent(\n        system_instructions=\"You are a character development expert with a background in psychology\",\n        model=\"gpt-4\",\n        combination_instructions=\"Create compelling characters that fit the plot and setting: \u003cstart\u003e${previous_responses}\u003c/end\u003e\"\n    ),\n    'setting': Agent(\n        system_instructions=\"You are a world-building expert with a focus on historical accuracy\",\n        model=\"gpt-4\",\n        combination_instructions=\"Design a rich, historically accurate setting that enhances the plot: \u003cstart\u003e${previous_responses}\u003c/end\u003e\"\n    )\n}\n\n# Create a creative writing moderator\nmoderator = Moderator(\n    persona=\"an experienced editor specializing in mystery novels\",\n    model=\"gpt-4\",\n    combination_instructions=\"Synthesize the plot, character, and setting elements into a cohesive story outline: \u003cstart\u003e${previous_responses}\u003c/end\u003e\"\n)\n\n# Define edges to create a simple interaction pattern\nedges = [\n    ('setting', 'character'),\n    ('setting', 'plot'),\n    ('character', 'plot')\n]\n\n# Create the DAG structure\nstory_dag = Graph(\n    agents=agents,\n    edges=edges,\n    task=story_prompt,\n    moderator=moderator\n)\n\n# Process the DAG\nstory_dag.process()\n\n# Print the final story outline\nprint(story_dag.final_response)\n\n```\n\n\n\n\n# Issues and Features 📝\n\nPlurals is run by a small and energetic team of academics doing the best they can [1]. To report bugs or feature requests, open a GitHub issue. We strongly encourage you to use our Bug or Feature Request issue templates; these make it easy for us to respond effectively to the issue. \n\n[1] Language adopted from (https://github.com/davidjurgens/potato). \n\n\n# Some Potential Uses 🔨🔭🔦✂️\n\n\n- Persona-based experiments (Ex: Create a panel of nationally representative personas)\n\n- Deliberation structure experiments (What are optimal information-sharing structures?) \n\n- Deliberation instruction experiments (What are optimal instructions for combining information?) \n\n- Agent-based models (Ex: understanding contagion in AI networks)\n\n- Curation (Ex: To what extent can Moderator LLMs filter and select the best outputs from other LLMs?)\n\n- Steerable guardrails (Ex: Can LLM deliberation steer abstentions?)\n\n- Persuasive messaging (Use many LLMs to collaboratively brainstorm and refine persuasive messaging for different audiences; Experiment with simulated focus groups)\n\n- Viewpoint augmentation (Provide varied perspectives and information from multiple agents)\n\n- Creative ideation (e.g., get ideas from multiple LLMs with different perspectives/roles for hypothesis generation, creative ideas, or product design)\n\n# Collaborators 🤝\n\nIf you are interested in collaborating, please reach out to Joshua Ashkinaze (jashkina@umich.edu). We are \nactively running both human and AI experiments around (1) how and when simulated social ensembles augment humans; (2) using Plurals for moderation.  \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosh-ashkinaze%2Fplurals","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosh-ashkinaze%2Fplurals","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosh-ashkinaze%2Fplurals/lists"}