Deterministic Avatar

Gera avatares SVG de forma determinística a partir de uma semente (por exemplo, email do usuário). O mesmo valor de semente sempre produzirá o mesmo avatar, garantindo consistência entre diferentes sistemas e sessões.

Avatar gerado com a seed john.doe@example.com

Características

• Determinístico: A mesma semente sempre gera o mesmo avatar
• Baseado em Hash: Utiliza MurmurHash3 para garantir distribuição uniforme
• Formato SVG: Avatares vetoriais escaláveis
• Personalizável: Múltiplas variações de sobrancelhas, olhos, nariz, boca, cores, roupas e acessórios
• Sexo: Suporte para avatares masculinos ("m"), femininos ("f") ou andróginos (None)
• Formal/Casual: Modo formal (subconjunto curado) ou casual (todas as variações disponíveis)
• Leve: Poucas dependências

Instalação

pip install deterministic-avatar

Ou, se você usa uv:

uv pip install deterministic-avatar

Uso Básico

from deterministic_avatar import DeterministicAvatar

# Criar instância do gerador
avatar_generator = DeterministicAvatar()

# Gerar avatar a partir de uma semente (por exemplo, email)
svg_string = avatar_generator.generate_avatar("usuario@example.com")

# Salvar o SVG em um arquivo
with open("avatar.svg", "w") as f:
    f.write(svg_string)

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
seed	str	(obrigatório)	Semente para geração determinística (ex: email)
sex	str | None	None	Sexo do avatar: "m" (masculino), "f" (feminino) ou None (andrógino)
formal	bool	True	True para subconjunto curado; False para todas as variações

Exemplos de Uso

Gerando múltiplos avatares

from deterministic_avatar import DeterministicAvatar

generator = DeterministicAvatar()

usuarios = ["alice@example.com", "bob@example.com", "charlie@example.com"]

for usuario in usuarios:
    svg = generator.generate_avatar(usuario)
    filename = f"avatar_{usuario.split('@')[0]}.svg"
    with open(filename, "w") as f:
        f.write(svg)
    print(f"Avatar gerado: {filename}")

Avatar feminino casual

from deterministic_avatar import DeterministicAvatar

generator = DeterministicAvatar()
svg = generator.generate_avatar("jane.doe@example.com", sex="f", formal=False)

with open("avatar_female_casual.svg", "w") as f:
    f.write(svg)

Avatar masculino formal

from deterministic_avatar import DeterministicAvatar

generator = DeterministicAvatar()
svg = generator.generate_avatar("john.doe@example.com", sex="m")

with open("avatar_male.svg", "w") as f:
    f.write(svg)

Usando em uma aplicação web (Flask)

from flask import Flask, Response
from deterministic_avatar import DeterministicAvatar

app = Flask(__name__)
generator = DeterministicAvatar()

@app.route('/avatar/<user_id>')
def get_avatar(user_id):
    svg = generator.generate_avatar(user_id)
    return Response(svg, mimetype='image/svg+xml')

if __name__ == '__main__':
    app.run()

Usando em uma aplicação web (FastAPI)

from fastapi import FastAPI
from fastapi.responses import Response
from deterministic_avatar import DeterministicAvatar

app = FastAPI()
generator = DeterministicAvatar()

@app.get("/avatar/{user_id}")
async def get_avatar(user_id: str):
    svg = generator.generate_avatar(user_id)
    return Response(content=svg, media_type="image/svg+xml")

Como Funciona

1. A semente (string) é convertida em um hash usando MurmurHash3
2. Com base nos parâmetros sex e formal, o conjunto de características elegíveis é determinado:
   • Formal (formal=True): usa um subconjunto curado de opções para aparência profissional
   • Casual (formal=False): usa todas as variações disponíveis na biblioteca
   • Sexo: controla cabelo e barba (feminino não inclui barba; andrógino combina opções)
3. O hash é usado para selecionar deterministicamente cada característica do avatar:
   • Tipo de sobrancelhas
   • Tipo de olhos
   • Tipo de nariz
   • Tipo de boca
   • Cor do cabelo
   • Acessórios (óculos)
   • Tipo de roupa
   • Cor da roupa
   • Cor da pele
   • Barba (masculino/andrógino)
   • Penteado (varia conforme sexo)
4. Um avatar SVG é gerado e renderizado com essas características

Dependências

• mmh3>=5.2.0: MurmurHash3 para geração de hash
• python-avatars>=1.4.1: Biblioteca para geração de avatares

Desenvolvimento

Instalando dependências de desenvolvimento

uv sync --extra dev

Obs.: o uv.lock no repositório é gerado com --extra dev para travar as ferramentas de desenvolvimento.

Executando testes

uv run pytest

Formatação de código

uv run black src/ tests/
uv run isort src/ tests/

Verificação de tipos

uv run mypy src/

Linting

uv run flake8 src/ tests/

Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou enviar pull requests no repositório do GitHub.

Agradecimentos

• Pablo Stanley pelo design dos avatares Avataaars e ilustrações adicionais via Blush
• ibonn pela biblioteca python-avatars que empacota esses assets

Autor

Daniel Lobato

Links

• Repositório GitHub
• PyPI
• Issues