{"id":16371569,"url":"https://github.com/tom-draper/persona","last_synced_at":"2025-03-23T02:34:31.041Z","repository":{"id":63586083,"uuid":"560367066","full_name":"tom-draper/persona","owner":"tom-draper","description":"Probabilistic generation of character profiles using real-world demographic data.","archived":false,"fork":false,"pushed_at":"2024-07-16T08:52:01.000Z","size":4372,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-18T06:30:45.029Z","etag":null,"topics":["api","character-creation","character-generator","data-api","data-generation","dataset","demographic","demographics","demographics-data","fastapi","generator","probabilistic-models","profile","profile-builder","random-generation","rest-api","sample","story-creation","survey"],"latest_commit_sha":null,"homepage":"https://persona-api.vercel.app/v1","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/tom-draper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-01T10:41:04.000Z","updated_at":"2024-07-16T08:52:04.000Z","dependencies_parsed_at":"2024-07-16T11:04:23.229Z","dependency_job_id":"c6ea6324-f0fc-43a5-bbd6-dd3e52bd642c","html_url":"https://github.com/tom-draper/persona","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-draper%2Fpersona","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-draper%2Fpersona/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-draper%2Fpersona/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-draper%2Fpersona/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tom-draper","download_url":"https://codeload.github.com/tom-draper/persona/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221843212,"owners_count":16890279,"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","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":["api","character-creation","character-generator","data-api","data-generation","dataset","demographic","demographics","demographics-data","fastapi","generator","probabilistic-models","profile","profile-builder","random-generation","rest-api","sample","story-creation","survey"],"created_at":"2024-10-11T03:08:53.872Z","updated_at":"2024-10-28T14:48:24.668Z","avatar_url":"https://github.com/tom-draper.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Persona\n\n**Make your characters more representative and realistic.** \n\nA REST API and CLI tool for probabilistically generating random character profiles from a given input location using real-world demographic data. Generating a new persona rolls the dice on features such as age, sex, sexuality, ethnicity, language and religion. This project was born out of a lack of tools for building representative and realistic characters for stories.\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"https://user-images.githubusercontent.com/41476809/200411754-969a4cc5-12de-4d3d-9189-bd258270cfc6.png\"\u003e\n\u003c/p\u003e\n\n## REST API\n\n### Generate Persona\n\n```\nhttps://persona-api.vercel.app/v1/\u003clocation\u003e/\n```\n\n```bash\n$ curl https://persona-api.vercel.app/v1/england/\n\n[\n  {\n    \"age\": 21,\n    \"sex\": \"Female\",\n    \"sexuality\": \"Heterosexual\",\n    \"ethnicity\": \"British, White\",\n    \"religion\": \"Christian\",\n    \"language\": \"English\",\n    \"location\": \"Oldham, North West\"\n  }\n]\n\n```\n\n#### Count Query\n\nMultiple personas from the same location can be generated at once by providing a `count` query parameter.\n\n```\nhttps://persona-api.vercel.app/v1/\u003clocation\u003e/?count=5\n```\n\n### List Locations\n\nAll locations currently included can be listed with the `/v1/locations/` endpoint.\n\n```bash\nhttps://persona-api.vercel.app/v1/locations/\n```\n\n```bash\n$ curl https://persona-api.vercel.app/v1/locations/\n\n[\n  \"australia\",\n  \"canada\",\n  \"germany\",\n  \"global\",\n  \"united_kingdom\",\n  \"england\",\n  \"london\",\n  \"northern_ireland\",\n  \"scotland\",\n  \"wales\",\n  \"california\",\n  \"florida\",\n  \"texas\"\n]\n\n```\n\n### Location Features\n\nCurrently, not all features are available for each location. For a given location, all features available for generation can be retrieved with the `/v1/\u003clocation\u003e/features/` endpoint.\n\n```\nhttps://persona-api.vercel.app/v1/\u003clocation\u003e/features/\n```\n\n```bash\n$ curl https://persona-api.vercel.app/v1/england/features/\n\n{\n  \"england\": [\n    \"age\",\n    \"sex\",\n    \"sexuality\",\n    \"religion\",\n    \"ethnicity\",\n    \"language\",\n    \"location\"\n  ]\n}\n```\n\n## Command-line Tool\n\n### Installation\n\nInstall Python dependencies from `requirements.txt`.\n\n```py\npip install -r requirements.txt\n```\n\n### Generate Persona\n\nRun `main.py` from the root directory.\n\n```py\npython src/main.py \u003clocation\u003e\n```\n\nThe generated persona can be limited to specific features using the feature flags to include.\n\n```py\npython src/main.py \u003clocation\u003e --age --location --language\n```\n\nMultiple personas can be generated at once using the `-n` flag.\n\n```py\npython src/main.py \u003clocation\u003e -n \u003ccount\u003e\n```\n\n### Example\n\n```bash\npython src/main.py united_kingdom\n\n\u003e United Kingdom\nAge: 48\nSex: Female\nSexuality: Heterosexual\nEthnicity: British, White\nReligion: No religion\nLanguage: English\nLocation: Blackburn with Darwen, North West, England\n```\n\n## Data\n\nThe demographic data is carefully sourced from reputable census data for each location. Sources for each location can be found alongside the data in each `README.md` in `/data`. The data is stored in a raw JSON format to make it as transparent, accessible and modifiable as possible.\n\n### Locations\n\nThe full list of locations currently available can be found [here](data/README.md). It includes countries, groups of locations (e.g. UK, USA), and cities. More locations and features will continue to be added in future.\n\n## Limitations\n\nPersonas generated are basic \u003cb\u003eapproximations\u003c/b\u003e. Character features are naively generated under the assumption that each feature is independent from one another. This assumption is not true; knowing a person's age could help you better predict their religion. However, the sourcing of accurate and large scale data necessary for the joint probabilities for all feature combinations is exponentially harder to achieve. As a result, generated characters should be taken with a pinch of salt, and very occasionally personas will be generated that have a combination of features that may seem extremely unlikely or even impossible. Obviously, the fewer features included in the persona, the easier it is to approximate, and the less likely this is to occur.\n\nDemographic data can change quite rapidly, and surveys take a long time to conduct, so the data used to generate profiles will always be somewhat outdated. Although, I still believe using outdated data in this way is an improvement over manual character creation in terms of representation as it will bypass any biases or misconceptions you may hold.\n\nWith this aim, this project is only as good as its data. There will certainly be minorities that make up a tiny proportion of the population that are missing from survey data (or grouped into an 'other' category) and therefore cannot surface during character generation. Improvement to data is an imperative and continuous goal for this project.\n\n## Contributions\n\nContributions are very welcome for data or general improvements.\n\nTo contribute:\n\n1. Fork the repo.\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am \"Add some feature\"`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new pull request\n\nWhen contributing data, keep content, directory structure and JSON formatting consistent and remember to note your source (including URL) in `data/.../\u003clocation\u003e/README.md`. Sources should be from reputable organisations conducting census research. Avoid \"Other\" as a feature attribute. Do not worry if percentages do not sum to 1 exactly, all feature probabilities are normalised during generation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftom-draper%2Fpersona","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftom-draper%2Fpersona","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftom-draper%2Fpersona/lists"}