{"id":34075100,"url":"https://github.com/agenttorch/agenttorch","last_synced_at":"2025-12-14T09:04:09.563Z","repository":{"id":213620734,"uuid":"657311127","full_name":"AgentTorch/AgentTorch","owner":"AgentTorch","description":"large population models","archived":false,"fork":false,"pushed_at":"2025-11-29T02:19:51.000Z","size":142165,"stargazers_count":503,"open_issues_count":9,"forks_count":80,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-12-01T03:21:47.219Z","etag":null,"topics":["agent-based-modeling","ai-agents-framework","autograd","differentiable-simulations","scientific-computing"],"latest_commit_sha":null,"homepage":"https://lpm.media.mit.edu/docs","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AgentTorch.png","metadata":{"files":{"readme":"readme.md","changelog":"change_log.txt","contributing":"docs/contributing.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2023-06-22T19:32:49.000Z","updated_at":"2025-12-01T03:17:38.000Z","dependencies_parsed_at":"2024-02-02T12:31:58.806Z","dependency_job_id":"22aa8f7f-9d7e-4dd5-9261-2c675042755f","html_url":"https://github.com/AgentTorch/AgentTorch","commit_stats":{"total_commits":121,"total_committers":5,"mean_commits":24.2,"dds":"0.25619834710743805","last_synced_commit":"ebfa7a33124b61fa5da8c2f2a990144fc2191157"},"previous_names":["agenttorch/agenttorch"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/AgentTorch/AgentTorch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentTorch%2FAgentTorch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentTorch%2FAgentTorch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentTorch%2FAgentTorch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentTorch%2FAgentTorch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AgentTorch","download_url":"https://codeload.github.com/AgentTorch/AgentTorch/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentTorch%2FAgentTorch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27724149,"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-14T02:00:11.348Z","response_time":56,"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":["agent-based-modeling","ai-agents-framework","autograd","differentiable-simulations","scientific-computing"],"created_at":"2025-12-14T09:04:08.473Z","updated_at":"2025-12-14T09:04:09.554Z","avatar_url":"https://github.com/AgentTorch.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003ca href=\"https://media.mit.edu/projects/ai-lpm\" target=\"_blank\"\u003e\n    Large Population Models\n  \u003c/a\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003emaking complexity simple\u003c/strong\u003e\u003cbr\u003e\n  differentiable learning over millions of autonomous agents\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\n  \u003ca href=\"https://agenttorch.github.io/AgentTorch/\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Quick%20Introduction-green\" alt=\"Documentation\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://twitter.com/intent/follow?screen_name=ayushchopra96\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/twitter/follow/ayushchopra96?style=social\u0026label=Get%20in%20Touch\" alt=\"Get in Touch\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://join.slack.com/t/largepopulationmodels/shared_invite/zt-2jalzf9ki-n9nXG5FryVSMaPmEL7Wm2w\" target=\"_blank\"\u003e\n     \u003cimg src=\"https://img.shields.io/badge/Slack-4A154B?logo=slack\u0026logoColor=white\" alt=\"Join Us\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Overview\n\nMany grand challenges like climate change and pandemics emerge from complex interactions of millions of individual decisions. While LLMs and agent simulations excel at individual behavior, they can't model these intricate societal dynamics. Enter Large Population Models (LPMs): a new paradigm to simulate millions of interacting entities, capturing behaviors at collective scale. It like scaling up LLMs exponentially to understand the ripple effects of countless decisions. While LLMs build \"digital humans\", LPMs build \"digital societies\".\n\nAgentTorch, our open-source platform, makes building and running massive LPMs accessible. It's optimized for GPUs, allowing efficient simulation of large-scale systems. Think PyTorch, but for large-scale agent-based simulations. AgentTorch LPMs have four design principles:\n\n- **Scalability**: AgentTorch models can simulate large-scale populations in\n  seconds across commodity hardware to computing clusters.\n- **Differentiability**: AgentTorch models can differentiate through simulations\n  with stochastic dynamics and conditional interventions, enabling\n  gradient-based optimization.\n- **Composition**: AgentTorch models can compose with deep neural networks (eg:\n  LLMs), mechanistic simulators (eg: mitsuba) or other LPMs. This helps describe\n  agent behavior using LLMs, calibrate simulation parameters and specify\n  expressive interaction rules.\n- **Generalization**: AgentTorch helps simulate diverse ecosystems - humans in\n  geospatial worlds, cells in anatomical worlds, autonomous avatars in digital\n  worlds.\n\nOur research is making an impact - winning awards at AI conferences and being used in real-world applications.\nLearn more [here](https://media.mit.edu/projects/ai-lpm).\n\nhttps://github.com/AgentTorch/AgentTorch/assets/13482350/4c3f9fa9-8bce-4ddb-907c-3ee4d62e7148\n\n## Installation\nInstall the most recent version from source using `pip`:\n\n```sh\n\u003e pip install git+https://github.com/agenttorch/agenttorch\n```\n\n\u003e Some models require extra dependencies that have to be installed separately.\n\u003e For more information regarding this, as well as the hardware the project has\n\u003e been run on, please see [`docs/install.md`](docs/install.md).\n\nAlternately, the easiest way to install AgentTorch (v0.6.0) is from pypi:\n```\n\u003e pip install agent-torch\n```\n\n\u003e AgentTorch is meant to be used in a Python \u003e=3.9 environment. If you have not\n\u003e installed Python 3.9, please do so first from\n\u003e [python.org/downloads](https://www.python.org/downloads/).\n\n## Getting Started\n\nThe following section depicts the usage of existing models and population data\nto run simulations on your machine. It also acts as a showcase of the Agent\nTorch API.\n\n### Executing a Simulation\n\n```py\n# re-use existing models and population data easily\nfrom agent_torch.examples.models import movement\nfrom agent_torch.populations import astoria\nfrom agent_torch.core.environment import envs\n\nrunner = envs.create(model=movement, population=astoria) # create simulation and init runner\n\nsim_steps = runner.config[\"simulation_metadata\"][\"num_steps_per_episode\"]\nnum_episodes = runner.config[\"simulation_metadata\"][\"num_episodes\"]\n\nfor epi in range(num_episodes):\n  runner.step(sim_steps)\n\n  runner.reset() # re-initializes the sim parameters for new episode\n\n```\n\n## License\nCopyright (c) 2023-2025 Ayush Chopra\n\nThis project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). This means:\n- You can freely use, modify, and distribute this software\n- If you use this software to provide services over a network, you must make your source code available to users\n- Any modifications or derivative works must also be licensed under AGPL-3.0\n- You must give appropriate credit and indicate any changes made\n- For full terms, see [LICENSE.md](LICENSE.md) file in this repository\n\nFor inquiries about using this software in a proprietary product, please reach out to request a license wavier.\n\n## Guides and Tutorials\n\n### Understanding the Framework\n\nA detailed explanation of the architecture of the Agent Torch framework can be\nfound [here](docs/architecture.md).\n\n### Creating a Model\n\nA tutorial on how to create a simple predator-prey model can be found in the\n[`tutorials/`](docs/tutorials/) folder.\n\n### Prompting Agent Behavior with LLM Archetypes\n```py\nfrom agent_torch.core.llm.archetype import Archetype\nfrom agent_torch.core.llm.behavior import Behavior\nfrom agent_torch.core.llm.backend import LangchainLLM\nfrom agent_torch.populations import NYC\nuser_prompt_template = \"Your age is {age} {gender},{unemployment_rate} the number of COVID cases is {covid_cases}.\"\n# Using Langchain to build LLM Agents\nagent_profile = \"You are a person living in NYC. Given some info about you and your surroundings, decide your willingness to work. Give answer as a single number between 0 and 1, only.\"\nllm_langchain = LangchainLLM(\n    openai_api_key=OPENAI_API_KEY, agent_profile=agent_profile, model=\"gpt-3.5-turbo\"\n)\n# Create an object of the Archetype class\n# n_arch is the number of archetypes to be created. This is used to calculate a distribution from which the outputs are then sampled.\narchetype = Archetype(n_arch=7)\n# Create an object of the Behavior class\n# You have options to pass any of the above created llm objects to the behavior class\n# Specify the region for which the behavior is to be generated. This should be the name of any of the regions available in the populations folder.\nearning_behavior = Behavior(\n    archetype=archetype.llm(llm=llm_langchain, user_prompt=user_prompt_template), region=NYC\n)\nkwargs = {\n    \"month\": \"January\",\n    \"year\": \"2020\",\n    \"covid_cases\": 1200,\n    \"device\": \"cpu\",\n    \"current_memory_dir\": \"/path-to-save-memory\",\n    \"unemployment_rate\": 0.05,\n}\noutput = earning_behavior.sample(kwargs)\n```\n\n### Contributing to Agent Torch\n\nThank you for your interest in contributing! You can contribute by reporting and\nfixing bugs in the framework or models, working on new features, creating new models, or by writing documentation for the project.\n\nTake a look at the [contributing guide](docs/contributing.md) for instructions\non how to setup your environment, make changes to the codebase, and contribute\nthem back to the project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagenttorch%2Fagenttorch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagenttorch%2Fagenttorch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagenttorch%2Fagenttorch/lists"}