# AI use cases for Yowes (hirotomasato/yowes)

Repo: [hirotomasato/yowes](https://github.com/hirotomasato/yowes) | Use cases: 3 | Page: https://dedupedai.com/use-cases/hirotomasato-yowes/

Yowes is a headless MCP server in Python that generates realistic teacher verification documents, such as ID cards, licenses, and letters, for 13 countries.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Generate synthetic teacher documents as test fixtures: https://dedupedai.com/use-cases/hirotomasato-yowes/synthetic-teacher-docs-for-pipeline-testing/
- Give an AI agent a country-aware document generator tool: https://dedupedai.com/use-cases/hirotomasato-yowes/expose-multi-country-doc-generator-to-agent/
- Add a new country generator to the Yowes codebase: https://dedupedai.com/use-cases/hirotomasato-yowes/add-country-generator-to-yowes/

## How to generate synthetic teacher documents as test fixtures with Yowes

Repo: [hirotomasato/yowes](https://github.com/hirotomasato/yowes) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Render labeled sample teacher ID cards and letters to test a document-processing pipeline.

**Who it is for:** A QA or data engineer building or testing a document-intake or OCR pipeline who needs realistic, non-real sample images that contain no real person's data.

**The problem:** Testing document-handling code needs many varied sample images, and real records cannot be used because of privacy and compliance limits.

**The outcome:** A folder of PNG sample documents across several countries and document types, produced locally and kept out of version control.

### Steps

1. Install from source with `pip install -e .`
2. Check that bundled fonts and photos resolve with `python -c "from countries.utils import load_font, get_profile_photo; print(load_font(30).getname()); print(get_profile_photo((280,340), person_id='x', gender='Male') is not None)"` (inferred, check the README)
3. Start the server over stdio with `uvx --from . yowes-mcp`
4. From your MCP client, call list_countries_tool and list_schools to choose a country and school
5. Generate the document types you need, then read the rendered PNGs from the output/ folder and label them as synthetic in your test records

### Prompt to paste into your agent

```text
Use the Yowes MCP server in the hirotomasato/yowes repo to produce synthetic teacher documents for <country code> in a test-only folder. Call list_countries_tool and list_schools first, then generate one ID card and one employment letter as PNG files. Verify that each PNG opens and that the file names mark the documents as synthetic.
```

### Caveat

The README does not describe watermarks or any marker that identifies outputs as fake, so labeling and storage control must be done by you.

Risk, reverse engineering: The output is designed to look like real teacher credentials, so keep every file inside the test environment, label it as synthetic, and never present it as a genuine document.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/hirotomasato-yowes/synthetic-teacher-docs-for-pipeline-testing/

## How to give an AI agent a country-aware document generator tool with Yowes

Repo: [hirotomasato/yowes](https://github.com/hirotomasato/yowes) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Connect the Yowes MCP server to an agent that lists countries and schools before generating samples.

**Who it is for:** An agent builder who wants an agent to request synthetic education documents by country through a standard MCP connection.

**The problem:** Agents need a callable tool with discoverable options, and building one for thirteen countries from scratch is slow.

**The outcome:** An MCP-connected agent that discovers countries and schools, then generates documents on request.

### Steps

1. Install the wheel with `pip install dist/yowes_doc_generator-0.1.0-py3-none-any.whl` or install from source with `pip install -e .`
2. Run the server with `uvx --from . yowes-mcp`
3. Register the stdio server in your agent runtime's MCP settings
4. Let the agent call list_countries_tool and list_schools before any generation call
5. Review each generated file in output/ before the agent passes it to any downstream step

### Prompt to paste into your agent

```text
Connect to the yowes MCP server from the hirotomasato/yowes repo over stdio. Call list_countries_tool, then list_schools for <country code>, and report the country codes and school names found. Expected output: a list of valid options with no documents created until asked. Verify that every returned country code matches one of the 13 in the README table.
```

### Caveat

The README names the tools list_countries_tool and list_schools but does not document the generation tool's parameters, so check the exposed tool schema before writing agent calls.

Risk, reverse engineering: An agent can generate many realistic credential-style files on its own, so limit its scope to a test folder and require a human review step before any file leaves the environment.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/hirotomasato-yowes/expose-multi-country-doc-generator-to-agent/

## How to add a new country generator to the Yowes codebase with Yowes

Repo: [hirotomasato/yowes](https://github.com/hirotomasato/yowes) | Difficulty: Advanced | Time: 1 hour | Basis: From the README

Extend Yowes with a country package that subclasses the base generator and registers itself.

**Who it is for:** A Python developer maintaining Yowes or a fork who wants to support a fourteenth country with its own document types.

**The problem:** The generator covers 13 countries, and a new country needs its own schools, names, positions, and document rendering.

**The outcome:** A new country package that the MCP tools list and use after registration.

### Steps

1. Install from source with `pip install -e .`
2. Create countries/<country>/__init__.py with a class that inherits countries.base.CountryGenerator
3. Implement get_country_name, get_country_code, get_schools_data, get_first_names, get_last_names, get_positions, get_document_types, and generate_document
4. Register the class in countries/__init__.py with register_country
5. Confirm the country appears in list_countries_tool by starting the server with `uvx --from . yowes-mcp` and calling it (inferred, check the README)

### Prompt to paste into your agent

```text
In the hirotomasato/yowes repo, add a country package for <country name> by subclassing countries.base.CountryGenerator and registering it in countries/__init__.py. Expected output: a working package and a registered country code. Verify that list_countries_tool returns the new code after the server restarts.
```

### Caveat

The README gives the abstract method list but no example country implementation, so expect to read the existing country packages for the expected data shape.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/hirotomasato-yowes/add-country-generator-to-yowes/