Metadata-Version: 2.4
Name: naamkaran
Version: 0.1.0
Summary: Generative model for names.
Author-email: Rajashekar Chintalapati <rajshekar.ch@gmail.com>, Gaurav Sood <gsood07@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/appeler/naamkaran
Project-URL: Documentation, https://naamkaran.readthedocs.io/
Project-URL: Repository, https://github.com/appeler/naamkaran
Project-URL: Issues, https://github.com/appeler/naamkaran/issues
Keywords: generate,names,machine-learning,nlp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: torch<3.0.0,>=2.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: joblib>=1.3.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: importlib-resources>=1.3.0; python_version < "3.9"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: web
Requires-Dist: gradio>=3.0.0; extra == "web"
Requires-Dist: flask>=2.0.0; extra == "web"
Dynamic: license-file

naamkaran: generative model for names
-------------------------------------

.. image:: https://github.com/appeler/naamkaran/actions/workflows/python-package.yml/badge.svg
    :target: https://github.com/appeler/naamkaran/actions?query=workflow%3Apython-package
.. image:: https://img.shields.io/pypi/v/naamkaran.svg
    :target: https://pypi.python.org/pypi/naamkaran
.. image:: https://static.pepy.tech/badge/naamkaran
    :target: https://pepy.tech/project/naamkaran


Naamkaran is a generative model for names. It is based on a character-level RNN trained on names from the Florida Voter Registration Data.

Gradio App.
------------
`Naamkaran on HF <https://huggingface.co/spaces/sixtyfold/generate_names>`__

Installation
------------

Naamkaran can be installed from PyPI using pip:

.. code-block:: bash

    pip install naamkaran

For development with all tools:

.. code-block:: bash

    pip install -e ".[dev,test]"

For web applications (Gradio/Flask):

.. code-block:: bash

    pip install "naamkaran[web]"

General API
-----------

The general API for naamkaran is as follows:

::

    # naamkaran is the package name
    from naamkaran.generate import generate_names

    # generate_names is the function that generates names

    positional arguments:
      start_letter  The letter to start the name with (default: "a")

    optional arguments:
        end_letter  The letter to end the name with (default: None)
        how_many    The number of names to generate (default: 1)
        max_length  The maximum length of the name (default: 5)
        gender      The gender of the name (default: "M")
        temperature The temperature of the model (default: 0.5)

    # generate 10 names starting with 'A'
    generate_names('A', how_many=10)
    ['Allis', 'Alber', 'Aderi', 'Albri', 'Alawa',
    'Arver', 'Agnee', 'Anous', 'Areyd', 'Adria']


    # generate 10 names starting with 'B' and ending with 'n'
    generate_names('B', end_letter='n', how_many=10)
    ['Brian', 'Beran', 'Burin', 'Bahan', 'Balin',
    'Bounn', 'Baran', 'Balan', 'Belin', 'Brion']

    # generate 5 names starting with 'B' and ending with 'n' with a maximum length of 4
    generate_names('B', end_letter='n', how_many=5, max_length=4)
    ['Bern', 'Bren', 'Bran', 'Bonn', 'Brun']

    # generate 10 names starting with 'D' and ending with 'd' with a maximum length of 6
    # and a temperature of 0.5
    generate_names('D', end_letter='d', how_many=5, max_length=6, temperature=0.5)
    ['Derayd', 'Davind', 'Deland', 'Denild', 'David']

    # generate 10 female names starting with 'A' and ending with 'e' with a maximum length of 5
    # and a temperature of 0.5
    generate_names('A', end_letter='e', how_many=10, max_length=5, gender="F", temperature=0.5)
    ['Annhe', 'Annie', 'Altre', 'Anne', 'Ashle',
    'Arine', 'Anice', 'Andre', 'Anale', 'Allie']


Data
----

The model is trained on names from the Florida Voter Registration Data from early 2022.
The data are available on the `Harvard Dataverse <http://dx.doi.org/10.7910/DVN/UBIG3F>`__


Authors
-------

Rajashekar Chintalapati and Gaurav Sood

Contributing
------------

Contributions are welcome. Please open an issue if you find a bug or have a feature request.

License
-------

The package is released under the `MIT License <https://opensource.org/licenses/MIT>`_.
