{"id":43395318,"url":"https://github.com/namehash/namegraph","last_synced_at":"2026-02-02T14:25:43.481Z","repository":{"id":268895252,"uuid":"496658274","full_name":"namehash/namegraph","owner":"namehash","description":"Help your users discover ENS names they love with NameGraph.","archived":false,"fork":false,"pushed_at":"2025-03-11T22:29:47.000Z","size":115906,"stargazers_count":5,"open_issues_count":4,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-11T23:20:41.275Z","etag":null,"topics":["ens"],"latest_commit_sha":null,"homepage":"https://namegraph.dev","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/namehash.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-05-26T14:44:12.000Z","updated_at":"2025-03-11T22:29:51.000Z","dependencies_parsed_at":"2025-03-11T23:30:20.968Z","dependency_job_id":null,"html_url":"https://github.com/namehash/namegraph","commit_stats":null,"previous_names":["namehash/name-generator","namehash/namegraph"],"tags_count":52,"template":false,"template_full_name":null,"purl":"pkg:github/namehash/namegraph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namehash%2Fnamegraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namehash%2Fnamegraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namehash%2Fnamegraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namehash%2Fnamegraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/namehash","download_url":"https://codeload.github.com/namehash/namegraph/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namehash%2Fnamegraph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29012929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-02T12:48:30.580Z","status":"ssl_error","status_checked_at":"2026-02-02T12:46:38.384Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ens"],"created_at":"2026-02-02T14:25:42.512Z","updated_at":"2026-02-02T14:25:43.476Z","avatar_url":"https://github.com/namehash.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003c!-- VERTICAL WHITESPACE --\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003c!-- LOGO --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://namegraph.dev\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/media/banner-dark.svg\"\u003e\n      \u003cimg alt=\"NameGraph\" src=\"docs/media/banner-light.svg\" width=\"auto\" height=\"auto\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003c!-- TAGLINE --\u003e\n\u003cp align=\"center\"\u003e\n  Surf more than 21 million name ideas across more than 400,000 name collections,\u003cbr\u003eor generate infinite related name suggestions.\n\u003cp\u003e\n\n\u003c!-- PROJECT SHIELDS --\u003e\n\u003cp align=\"center\"\u003e\n  \u003c!-- TODO: Add license shield once license is finalized --\u003e\n  \u003c!-- \u003ca href=\"LICENSE\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://img.shields.io/github/license/namehash/namekit?color=444444\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/license/namehash/namekit?color=444444\" alt=\"MIT License\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e --\u003e\n  \u003ca href=\"https://github.com/namehash/namegraph/actions/workflows/build.yml\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/namehash/namegraph/actions/workflows/build.yml/badge.svg?branch=prod\"\u003e\n      \u003cimg src=\"https://github.com/namehash/namegraph/actions/workflows/build.yml/badge.svg?branch=prod\" alt=\"Python Build Status\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/namehash/namegraph/actions/workflows/ci.yml\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/namehash/namegraph/actions/workflows/ci.yml/badge.svg?branch=master\"\u003e\n      \u003cimg src=\"https://github.com/namehash/namegraph/actions/workflows/ci.yml/badge.svg?branch=master\" alt=\"Python CI Status\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n  \u003ca href=\"#project-status\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://img.shields.io/badge/status-beta-444444\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/status-beta-444444\" alt=\"status: beta\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# Project Status\n\nNameGraph is currently in beta. We are excited to share our work with you and continue to build the greatest web of names in history!\n\n# Overview\n\nNameGraph is a web service that generates name suggestions for a given input label. It is implemented using FastAPI and provides a variety of endpoints to generate suggestions in different modes and with different parameters.\n\n## Label Analysis\n\nThe input label is analyzed to determine the most relevant name suggestions. The analysis includes:\n\n- Defining all possible interpretations of the input label along with their probabilities (whether it is a sequence of common words, a person name, what is the language, etc.)\n- For each interpretation, determining most probable tokenizations (e.g. `armstrong` -\u003e `[\"armstrong\"]`, `armstrong` -\u003e `[\"arm\", \"strong\"]`)\n\nThe suggestions are later generated based on these interpretations, tokenizations being especially important, since many generators greatly rely on them. This is why the endpoints can handle pretokenized input.\n\n## Collections\n\nCollections are curated sets of names that serve as a core component of NameGraph's name suggestion system. The system maintains a vast database of over 400,000 name collections containing more than 21 million unique names. Each collection is stored in Elasticsearch and contains:\n\n- A unique collection ID\n- Collection title and description\n- Collection rank and metadata\n- Member names with their normalized and tokenized forms\n- Collection types and categories\n- Related collections\n\nCollections are used in several key ways:\n\n1. Direct Name Generation:\n   - Searches collections based on input tokens\n   - Uses [learning-to-rank models](#learning-to-rank) to find relevant collections\n\n2. Related Collections:\n   - Finds collections with similar themes and content\n   - Ensures diverse suggestions across different categories\n\n3. Membership Lookup:\n   - Discovers collections containing specific names\n   - Enables finding thematically related names\n\nThe collections are maintained and updated through our [NameGraph Collections](https://github.com/namehash/namegraph-collections) project, ensuring the suggestion database stays current and comprehensive.\n\n## Generators\n\nGenerators are core components that create name suggestions through different methods. Each generator inherits from the base [NameGenerator](namegraph/generation/name_generator.py) class and implements specific name generation strategies. They can be grouped into the categories as shown in the diagram below:\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/media/generators.dark.svg\"\u003e\n    \u003cimg alt=\"NameKit\" src=\"docs/media/generators.light.svg\" width=\"auto\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n## Modes\n\nNameGraph supports three modes for processing requests:\n\n- Instant Mode (`instant`):\n  - Fastest response time\n  - More basic name generations\n  - Some advanced generators like W2VGenerator are disabled (weight multiplier = 0)\n  - Often used for real-time suggestions\n\n- Domain Detail Mode (`domain_detail`):\n  - Intermediate between instant and full\n  - More comprehensive than instant, but still optimized for performance\n  - Some generators have reduced weights compared to full mode\n  - Expanded search window for collection ranking and sampling\n\n- Full Mode (`full`):\n  - Most comprehensive name generation\n  - Includes all enabled generators\n  - Uses full weights for most generators\n  - Accesses advanced generators like `Wikipedia2VGenerator` and `W2VGenerator`\n  - Takes longer to process, but provides the most diverse results\n\n\nDifferent generators are enabled/disabled for each mode. Take a look at the [generators diagram](#generators) to see which generators are available in each mode.\n\n\u003cdiv align=\"center\"\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eIcon\u003c/th\u003e\n    \u003cth\u003eMode\u003c/th\u003e\n    \u003cth\u003eDescription\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/media/instant.dark.svg\"\u003e\u003cimg alt=\"Instant\" src=\"docs/media/instant.light.svg\" width=\"20\"\u003e\u003c/picture\u003e\u003c/td\u003e\n    \u003ctd\u003eInstant\u003c/td\u003e\n    \u003ctd\u003eFastest response, basic generators only\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/media/domain-detail.dark.svg\"\u003e\u003cimg alt=\"Domain Detail\" src=\"docs/media/domain-detail.light.svg\" width=\"20\"\u003e\u003c/picture\u003e\u003c/td\u003e\n    \u003ctd\u003eDomain Detail\u003c/td\u003e\n    \u003ctd\u003eBalanced speed/quality, expanded search\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/media/full.dark.svg\"\u003e\u003cimg alt=\"Full\" src=\"docs/media/full.light.svg\" width=\"20\"\u003e\u003c/picture\u003e\u003c/td\u003e\n    \u003ctd\u003eFull\u003c/td\u003e\n    \u003ctd\u003eComprehensive generation with all generators\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\u003c/div\u003e\n\n## Sampler\n\nThe sampler is a sophisticated component that manages the selection and generation of name suggestions. It implements a probabilistic sampling algorithm that balances diversity, relevance, and efficiency while respecting various constraints.\n\n### Key Components\n\n- **Request Parameters**:\n  - `mode`: Determines which generators are active (`instant`/`domain_detail`/`full`)\n  - `min_suggestions`: Minimum number of suggestions to return\n  - `max_suggestions`: Maximum number of suggestions to return\n  - `min_available_fraction`: Minimum fraction of suggestions that must be available\n\n- **Interpretations**: Each input name can have multiple interpretations, characterized by:\n  - Type (`ngram`, `person`, `other`)\n  - Language\n  - Probability score\n  - Possible tokenizations\n\n### Sampling Algorithm\n\nThe sampler uses a probabilistic approach to generate diverse and relevant name suggestions:\n\n```mermaid\nflowchart TD\n    A[Start] --\u003e B{Enough suggestions?}\n    B --\u003e|Yes| Z[End]\n    B --\u003e|No| C{All probabilities = 0?}\n    C --\u003e|Yes| Z\n    C --\u003e|No| D[Sample type \u0026 language]\n    D --\u003e E[\"Sample tokenization\"]\n    E --\u003e F[Sample pipeline]\n    F --\u003e G{Pipeline exceeds limit?}\n    G --\u003e|Yes| F\n    G --\u003e|No| H[Get suggestion from pipeline]\n    H --\u003e I{Any suggestions left?}\n    I --\u003e|Yes| J{Already sampled?}\n    I --\u003e|No| F\n    J --\u003e|Yes| H\n    J --\u003e|No| K{Available if required?}\n    K --\u003e|No| H\n    K --\u003e|Yes| L{Normalized?}\n    L --\u003e|No| H\n    L --\u003e|Yes| B\n```\n\nThe algorithm works as follows:\n\n1. **Initialization**: For each type-language pair, pipeline probabilities are computed.\n\n2. **Main Loop**: The sampler iterates until either:\n   - Enough suggestions are generated (`max_suggestions` met)\n   - All pipeline probabilities become zero\n\n3. **Sampling Process**:\n   - First samples a type and language pair\n   - Then samples a specific tokenization within that pair\n   - Selects a pipeline using probability-based sampling\n   - First pass uses sampling without replacement for diversity\n   \n4. **Validation Checks**:\n   - Verifies pipeline hasn't exceeded its global limit\n   - Ensures suggestions aren't duplicates\n   - Checks availability status if required\n   - Confirms normalization status\n\n5. **Pipeline Management**:\n   - Exhausted pipelines are removed from the sampling pool\n   - When a pipeline can't generate more suggestions, falls back to other pipelines\n\nThis approach ensures a balanced mix of suggestions while maintaining efficiency and respecting all configured constraints.\n\n# Usage\n\nNameGraph uses [Poetry](https://python-poetry.org/) for dependency management and packaging. Before getting started, make sure you have Poetry installed on your system.\n\n## Prerequisites\n\nInstall Poetry if you haven't already:\n```bash\ncurl -sSL https://install.python-poetry.org | python3 -\n```\n\nVisit [Poetry installation guide](https://python-poetry.org/docs/#installation) for more details.\n\n## Install\n\nClone the repository and install dependencies:\n```bash\ngit clone https://github.com/namehash/namegraph.git\ncd namegraph\npoetry install\n```\n\n## Download resources\n\nAdditional resources need to be downloaded. Run these commands within the Poetry environment:\n\n```bash\npoetry run python download.py  # dictionaries, embeddings\npoetry run python download_names.py\n```\n\n## Configuration\n\nNameGraph uses [Hydra](https://hydra.cc/) - a framework for elegantly configuring complex applications. The configuration is stored in the `conf/` directory and includes:\n\n- Main configuration files (`prod_config_new.yaml`, `test_config_new.yaml`) with core settings like connections, filters, limits, and paths\n- Pipeline configurations in `conf/pipelines/` defining generators, modes, categories, and language settings\n\nThe configuration is highly modular and can be easily modified to adjust the behavior of name generation, filtering, and ranking systems.\n\n## REST API\n\nStart server using Poetry:\n```bash\npoetry run uvicorn web_api:app --reload\n```\n\nQuery with POST:\n```bash\ncurl -d '{\"label\":\"armstrong\"}' -H \"Content-Type: application/json\" -X POST http://localhost:8000\n```\n\nQuery with POST (pretokenized input):\n```bash\ncurl -d '{\"label\":\"\\\"arm strong\\\"\"}' -H \"Content-Type: application/json\" -X POST http://localhost:8000\n```\n\n**Note:** pretokenized input should be wrapped in double quotes.\n\n## Documentation\n\nThe API documentation is available at `/docs` or `/redoc` when the server is running. These are auto-generated Swagger/OpenAPI docs provided by FastAPI that allow you to:\n\n- View all available endpoints\n- See request/response schemas\n- See descriptions of each parameter and response field\n- Test API calls directly from the browser\n\nPublic API documentation is available at [api.namegraph.dev/docs](https://api.namegraph.dev/docs).\n\n## Tests\n\nRun tests using Poetry:\n```bash\npoetry run pytest\n```\n\nTests that interact with external services (Elasticsearch) are marked with `integration_test` marker and are disabled by default. Define environment variables needed to access Elasticsearch and run them using:\n```bash\npoetry run pytest -m \"integration_test\"\n```\n\n## Learning-To-Rank\n\nTo access the LTR features, you need to configure it in the Elasticsearch instance (see [here](https://github.com/namehash/namegraph-collections/tree/master/research/learning-to-rank/readme.md) for more details).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamehash%2Fnamegraph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnamehash%2Fnamegraph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamehash%2Fnamegraph/lists"}