babyname/fate: a Go engine that scores Chinese names against bazi, wuge and the I Ching

What babyname/fate actually computes, and who needs it

Choosing a Chinese given name is a constraint-satisfaction problem dressed up as a cultural one. The surname is fixed, the birth timestamp is fixed, and the remainder is a search over thousands of two-character combinations that must satisfy stroke-count rules, five-element balance, zodiac compatibility and, ideally, some literary provenance. Doing that by hand means consulting several incompatible references. Fate packages those references as code.

The README describes the engine as covering bazi (Four Pillars), wuge (five-grid numerology), Zhouyi hexagrams and poetry sourcing, with a five-dimension score. That score is the product: cultural impression, five elements, zodiac, grid numerology and phonology, each contributing to a single number that the CLI prints next to a grade such as 上上.

The intended user is a Go developer building a naming service, a mobile app backend, or an internal tool for a naming consultancy. It is not aimed at end users directly, although the repository ships an embedded React front end so a non-developer can use the binary once someone else has built it.

The engine pipeline: session, filter, ExcellentTable

The architecture diagram in the README separates the CLI and HTTP server from a core engine that holds Session, Filter and ExcellentTable, sitting above three domain packages: Bazi, Wuge and Zhouyi. Below those are third-party engines, chronos/v2 for the calendar and astrology arithmetic and yi for hexagram lookup, then Ent ORM over SQLite, with character.json and a Chinese poetry corpus as the data sources.

The data flow is asynchronous. A Session is created with a Filter, given an Input containing the surname pair, birth time and sex, and started. The caller waits, then reads an Output. That Output exposes TopNames, an ExcellentTable and a CharMap.

ExcellentTable is the interesting structure. The README calls it a streaming Top-N container with TryPush, Finalize, TopN and Explore operations. Rather than materialising every candidate and sorting, candidates are pushed in as they are generated and the table keeps the best ones. TopN(10) returns the leaders; Explore(10, predicate) samples randomly subject to a condition, which is what the web UI's exploration mode uses. The README claims O(1) lookup for the 81-number grid table, which is a lookup table rather than an algorithmic result.

Installing fate and generating a first name from the CLI

The README lists Go 1.22 or newer as the requirement, and Bun only for front-end development. Production deployment does not need Bun, because the front end is embedded in the binary. Note that go.mod declares go 1.25.0, which is higher than the badge's 1.22+, so the module directive is the stricter constraint.

Clone, fetch dependencies and initialise the database. The README marks database initialisation as required, so skipping it will leave the server without its character data.

# clone the project
git clone https://github.com/babyname/fate.git
cd fate

# download dependencies
go mod download

# initialise the database (required)
go run ./cmd/dbinit

# start the Web service
go run ./cmd/server
# visit http://localhost:18080

The server listens on port 18080. For command-line use, build the console entry point and pass surname, birth time and gender.

# build the CLI
go build -o fate ./cmd/console

# generate names
./fate name -s 张 -b "2024/06/15 10:30" -g boy

The README's sample output shows a ranked list with a score, a grade, the five-element pair, the four grid values with their fortune labels, and a three-talents line. The example output ends by reporting that 10,000 candidate names were generated in total. If you want the reasoning rather than the list, the README shows a name detail subcommand that prints the five-grid breakdown, the Four Pillars, the favoured and avoided elements, the primary and changed hexagrams, and the five sub-scores.

Using the HTTP API and the Go library instead

The server exposes a small REST surface: a health check, an asynchronous generate endpoint that returns a task_id, a task status endpoint, a paginated name list, a name detail endpoint and an explore endpoint. Generation is asynchronous, so a client posts a request and then polls.

The README gives this request as the example, including the poetry_mode field and an avoid_chars array.

curl -X POST http://localhost:18080/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "surname": "张",
    "born": "2024/06/15 10:30",
    "sex": "boy",
    "poetry_mode": 2,
    "avoid_chars": ["病", "死"]
  }'

For embedding, the module path carries a v4 suffix. The README's integration example constructs a default config, creates the engine, builds a Filter with stroke bounds of 3 to 18 and several boolean switches, opens a session, starts it and waits.

import (
    "github.com/babyname/fate/v4"
    "github.com/babyname/fate/v4/config"
)

cfg := config.DefaultConfig()
f, _ := fate.New(cfg)
filter := fate.NewFilter(fate.FilterOption{
    CharacterFilter: true,
    MinStroke:       3,
    MaxStroke:       18,
    DaYanFilter:     true,
    WuXingFilter:    true,
    AvoidCharacters: []string{"病", "死", "穷"},
})

The FilterOption struct is where most of the practical control lives: stroke range, five-element filtering, the dayan filter, gender and the avoid list. The CLI exposes a subset of this through flags such as --xiyong for choosing the balance or geju algorithm, --strictness for grid tolerance and --filter for excluded characters.

Where fate is the wrong tool

The whole scoring model rests on rules that are contested. Fate implements two methods for choosing the favourable element, a balance method and a geju method covering ten pattern types, and lets the caller pick. That is honest about the disagreement, but it also means the ranking is not a single objective answer. Two runs with different --xiyong values will produce different top names from the same birth data, and the README does not explain which method suits which case.

The poetry corpus is a sourcing layer, not a verification layer. The ExcellentTable entries carry a has_poetry boolean, which tells you a name appears in the corpus but not whether the line is apt for a child. Expect to review candidates rather than accept the top ten.

Operationally, the project is a single-maintainer Go module with a v4 module path and a data directory. The README does not document schema migrations between versions, and the release list is uneven: v3.5.9 in January 2023, v3.5.7 and v3.5.10 both in June 2024, while the README badge advertises version 4.2.0. If you deploy this, treat the SQLite database as something you can regenerate with cmd/dbinit rather than something you upgrade in place.

Finally, this is a Chinese naming engine. Surnames, stroke counts, five-element assignments and hexagram readings are all grounded in Chinese characters and the Chinese calendar. There is no path here for naming in other scripts.

How fate differs from script-based naming tools

The obvious alternative is a collection of scripts: a Python file that reads a character dictionary, applies a stroke-count table and prints combinations. The difference is architectural. A script typically materialises the full candidate set and sorts it, which is why such tools slow down as you widen the stroke range or relax the filters. Fate instead pushes candidates into ExcellentTable as they are produced and keeps only the leaders, which is what makes the Explore operation possible at all: random sampling with a predicate only works if you are not holding every candidate.

The second difference is the data layer. Fate uses Ent ORM over SQLite with a character database and a poetry corpus shipped in the repository, and it exposes the same engine through a CLI, an HTTP API and a Go package. A script gives you one interface. The cost of that structure is a heavier dependency tree: Ent, Atlas, a SQLite driver and the chronos and yi engines all arrive with the module.

A third option is to consume an existing naming website. That trades control for convenience, and it removes the ability to change the scoring weights or the avoid list, which is the main reason to run this locally.

Licence, maintenance and the upgrade question

Fate is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. The repository contains a LICENSE file at the top level. As with any dependency, the licence of the embedded data matters separately from the code: the README names character.json and a chinese-poetry corpus as data sources, and the licence covering those datasets is not stated in the README. If you redistribute the binary, check the data directory's own terms before shipping. That is a factual gap to close, not a legal opinion.

The last push to the default branch was on 2026-06-25, so the repository is not archived and has seen recent activity. The published release tags are older, with v3.5.10 dated 2024-06-27, while the README badge shows version 4.2.0 and the module path is v4. A version badge in a README is not a release. If you depend on tagged versions, confirm which tag corresponds to the v4 module path before pinning.

Upgrade cost is concentrated in the database. Because cmd/dbinit rebuilds the SQLite store from the bundled data, the cheapest upgrade path is to regenerate rather than migrate. The README does not describe an in-place migration path, so plan for a rebuild step in your deployment.

Editorial conclusion

Adopt babyname/fate if you need Chinese naming logic as a Go library or a self-hosted HTTP service and you accept that the ranking rules themselves are the hard part to audit. Do not adopt it if you need multilingual naming, a hosted API, or a project with a documented upgrade path, because the README does not describe database migrations between versions. Before committing, run go run ./cmd/dbinit against a copy of the data directory and confirm the SQLite schema it writes matches the version your code expects.

Frequently asked questions

Official sources

1. babyname/fate on GitHub
2. License: MIT
3. Project website
4. README
5. Releases