Metadata-Version: 2.4
Name: profile-yaml-factory
Version: 0.3.5
Summary: Antidetect profile YAML — validate templates, batch-render Multilogin profile/create JSON. CLI: profile-factory.
Project-URL: Homepage, https://github.com/profile-yaml-factory/profile-yaml-factory
Project-URL: Documentation, https://github.com/profile-yaml-factory/profile-yaml-factory#readme
Project-URL: Repository, https://github.com/profile-yaml-factory/profile-yaml-factory
Project-URL: Issues, https://github.com/profile-yaml-factory/profile-yaml-factory/issues
Author: profile-yaml-factory contributors
License-Expression: MIT
License-File: LICENSE
Keywords: antidetect-profile,batch-profiles,browser-automation,browser-blueprint,folder-profile,multilogin,multilogin-create,profile-create,profile-renderer,profile-schema,profile-template,proxy-template,pydantic-profile,render-json,template-vars,yaml-profile
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: pydantic>=2.5
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-httpx>=0.34; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: rich>=13.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: mlx
Requires-Dist: httpx>=0.27; extra == 'mlx'
Requires-Dist: rich>=13.0; extra == 'mlx'
Description-Content-Type: text/markdown

# profile-yaml-factory

**Antidetect profile YAML templates** — validate blueprints and batch-render Multilogin profile/create JSON from one CLI.

[![PyPI version](https://img.shields.io/pypi/v/profile-yaml-factory.svg)](https://pypi.org/project/profile-yaml-factory/)
[![Python versions](https://img.shields.io/pypi/pyversions/profile-yaml-factory.svg)](https://pypi.org/project/profile-yaml-factory/)
[![License: MIT](https://img.shields.io/pypi/l/profile-yaml-factory.svg)](https://pypi.org/project/profile-yaml-factory/)

```bash
pip install profile-yaml-factory
profile-factory validate examples/templates/ecommerce-us.yaml
```

CLI: **`profile-factory`** · Python **3.10+** · optional **`[mlx]`** for Launcher helpers

> **Partner (optional):** Batch `profile/create` for MLX folders? [Multilogin X](https://multilogin.com?a_aid=saas) · `SAAS50` / `MIN50` on eligible new purchases. `validate` / `render` work offline without an account. [Affiliate disclosure](docs/AFFILIATE.md) · [Multilogin promo codes](https://anti-detect.github.io/).

**Antidetect profile YAML templates** — validate blueprints and batch-render Multilogin `profile/create` JSON from one CLI.

YAML templates for browser profiles with **Pydantic validation**, **JSON Schema export**, and **MLX-ready JSON** output.

Define reusable profile blueprints (proxy, timezone, language, screen, tags) and render them to `POST /profile/create` payloads for [Multilogin](https://multilogin.com?a_aid=saas) or similar antidetect workflows.

## Problem

Hand-rolling MLX `profile/create` JSON does not scale across folders, locales, and proxy lanes. Copy-paste errors in timezone, screen size, or proxy fields cause failed creates and incoherent fingerprints. Teams need validated YAML blueprints that render to identical API payloads every time.

## Install

```bash
pip install profile-yaml-factory

# MLX profile create helper
pip install profile-yaml-factory[mlx]
```

## Quick start

```bash
profile-factory validate examples/templates/ecommerce-us.yaml \
  --vars name=demo,folder_id=YOUR-FOLDER,country=US,timezone=America/New_York,proxy=socks5://u:p@1.2.3.4:1080

profile-factory render examples/templates/ecommerce-us.yaml \
  --vars name=demo,folder_id=YOUR-FOLDER,country=US,timezone=America/New_York,proxy=socks5://u:p@1.2.3.4:1080 \
  -o demo.json
```

Lint the rendered fingerprint with [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) before `mlx-create`.

## CLI

```bash
# Export JSON Schema
profile-factory schema
profile-factory schema -o profile-template.schema.json

# Validate (templates with {{ }} need --vars)
profile-factory validate examples/templates/ecommerce-us.yaml \
  --vars name=shop-us,folder_id=YOUR-FOLDER,country=US,timezone=America/New_York,proxy=socks5://u:p@1.2.3.4:1080

# Render with variables
profile-factory render examples/templates/ecommerce-us.yaml \
  --vars name=shop-us,folder_id=YOUR-FOLDER,country=US,timezone=America/New_York,proxy=socks5://u:p@1.2.3.4:1080 \
  -o rendered/shop-us.json

# Batch render directory (writes manifest.json with checksums)
profile-factory batch examples/templates/ -o rendered/ \
  --vars name=batch-1,folder_id=YOUR-FOLDER,country=US,timezone=America/New_York,proxy=socks5://u:p@1.2.3.4:1080

# Create MLX profile (requires MLX_TOKEN)
export MLX_TOKEN=your_bearer_token
profile-factory mlx-create --input rendered/shop-us.json

# Batch create from manifest.json (after profile-factory batch)
profile-factory mlx-create --input rendered/ --folder-id YOUR-FOLDER --rate-limit 2

# Validate payloads only (no API token required)
profile-factory mlx-create --input rendered/ --dry-run
```

### Strict mode

`--strict` is **on by default** for `validate`, `render`, and `batch`:

- Unknown keys in `--vars` raise an error (use `--no-strict` for legacy/extra keys).
- Unknown fields in YAML are rejected by the Pydantic schema (`extra=forbid`).

## Template authoring guide

### 1. Start from an example

Copy a template from [`examples/templates/`](examples/templates/) (10 bundled verticals):

| Template | Vertical | Typical use |
|----------|----------|-------------|
| `ecommerce-us.yaml` | US retail | Storefront browsing QA |
| `social-uk.yaml` | UK social | Feed and engagement checks |
| `ads-manager.yaml` | Ads (multi) | Meta/Google Ads manager review |
| `qa-checkout.yaml` | Checkout | Cart and coupon regression (Linux) |
| `maps-research.yaml` | Maps (DE) | Local SERP research (`de-DE`) |
| `tiktok-mobile.yaml` | Mobile short-form | Android viewport web QA |
| `meta-ads-us.yaml` | Meta Ads (US) | Campaign and creative diagnostics |
| `amazon-seller-eu.yaml` | Amazon Seller EU | Listing and inventory QA (`de-DE`) |
| `google-maps-local.yaml` | Google Maps (US) | Local listing spot checks |
| `stripe-checkout-qa.yaml` | Stripe Checkout | Payment element regression (Linux) |

Templates organize **locale, screen, proxy, and tags** for authorized QA and research workflows. They are not designed to circumvent platform terms of service, bot detection, or account policies — automate only where you have permission.

### 2. Required YAML fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | yes | Profile display name (often `{{ name }}`) |
| `timezone` | yes | IANA timezone — use `{{ timezone }}` or a literal |
| `language` | yes | BCP-47 locale (e.g. `en-US`) |
| `screen` | yes | `width` / `height` in pixels |
| `proxy` | no | Proxy URL string `{{ proxy }}` or structured block |
| `notes` | no | Free-text workflow notes |
| `tags` | no | String list for organization |
| `folder_id` | no | MLX folder UUID |
| `browser_type` | no | `mimic` (default) or `stealthfox` |
| `os_type` | no | `windows` (default), `macos`, `linux`, `android` |

Validate against the machine-readable schema:

```bash
profile-factory schema -o profile-template.schema.json
```

### 3. Template variables

Use `{{ variable }}` placeholders in YAML strings. Pass values via `--vars key=value,...`.

**Semantic variables** (validated when present):

| Variable | Validation | Example |
|----------|------------|---------|
| `{{ country }}` | ISO-3166 alpha-2 | `US`, `GB`, `DE` |
| `{{ timezone }}` | IANA timezone id | `America/New_York` |
| `{{ proxy }}` | Proxy URL or `host:port[:user:pass]` | `socks5://u:p@1.2.3.4:1080` |

**Common workflow variables:**

| Variable | Description |
|----------|-------------|
| `{{ name }}` | Rendered profile name |
| `{{ folder_id }}` | MLX folder UUID |

When `proxy` is a single string placeholder, it is parsed into `type`, `host`, `port`, and optional credentials before validation.

### 4. Example snippet

```yaml
name: "{{ name }}"
folder_id: "{{ folder_id }}"
timezone: "{{ timezone }}"
language: en-US
screen:
  width: 1920
  height: 1080
proxy: "{{ proxy }}"
tags:
  - ecommerce
  - "{{ country }}"
```

```bash
profile-factory render my-template.yaml \
  --vars name=shop-1,folder_id=uuid,country=US,timezone=America/New_York,proxy=socks5://u:p@10.0.0.1:1080 \
  -o out/shop-1.json
```

### 5. Batch output manifest

`profile-factory batch` renders every `*.yaml` / `*.yml` in a directory and writes `manifest.json`:

```json
{
  "version": 1,
  "generated_at": "2026-06-11T12:00:00+00:00",
  "count": 10,
  "profiles": [
    {"file": "ecommerce-us.json", "sha256": "…", "bytes": 1234}
  ]
}
```

Use checksums to verify artifacts in CI or before uploading to MLX.

## When hand-rolled `profile/create` JSON fails at scale

Teams outgrow copy-paste MLX payloads when folders, locales, and proxy lanes multiply. Typical failure modes:

| Symptom | Likely cause | Fix with `profile-factory` |
|---------|--------------|----------------------------|
| API 400 on create | Wrong `folder_id`, malformed proxy, invalid timezone | `validate` + `mlx-create --dry-run` before network |
| Profiles “work” but sites block | UA/screen/timezone drift in JSON | Render → [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) audit |
| Slow or rate-limited batch | Unthrottled parallel creates | `batch` manifest + `mlx-create --rate-limit 2` |
| Competitor export gaps | Missing fields after migration | `antidetect-import` gap report → fill template vars |

**Recommended production pipeline:**

```bash
proxy-lane check proxies.txt -o lanes.json          # pick clean exits
profile-factory batch examples/templates/ -o out/ \
  --vars name=shop,folder_id=FOLDER,country=US,timezone=America/New_York,proxy=socks5://...
fp-coherence audit out/ecommerce-us.json --strict   # lint rendered fingerprint
profile-factory mlx-create --input out/ --dry-run   # schema check
export MLX_TOKEN=...
profile-factory mlx-create --input out/ --rate-limit 2
cdp-probe mlx --profile-id NEW_UUID --url https://example.com  # post-create exposure check
```


**Coupon hub:** [Multilogin promo codes](https://anti-detect.github.io/) — guides for `SAAS50` / `MIN50`, pricing comparisons, and workflow playbooks.
**Batch-create partner note:** After `batch` + `mlx-create`, profiles run on [Multilogin X](https://multilogin.com?a_aid=saas). Code `SAAS50` (browser) — confirm vendor terms before checkout. Coupons: `profile-factory --show-deal`.

Templates organize **authorized QA and research** workflows — not circumvention of platform terms.

## Python API

```python
from profile_yaml_factory import render_template, validate_template_file

variables = {
    "name": "shop",
    "folder_id": "...",
    "country": "US",
    "timezone": "America/New_York",
    "proxy": "socks5://u:p@1.2.3.4:1080",
}
template = validate_template_file("examples/templates/ecommerce-us.yaml", variables=variables)
payload = render_template("examples/templates/ecommerce-us.yaml", variables=variables)
```

## MLX integration

`mlx-create` posts rendered JSON to `https://api.multilogin.com/profile/create` with your bearer token (`MLX_TOKEN` or `--token`). This uses the public HTTP API directly — not an official Multilogin SDK.

| Flag | Default | Description |
|------|---------|-------------|
| `--input` | required | Single `.json` or batch directory / `manifest.json` |
| `--folder-id` | `MLX_FOLDER_ID` | Override `folder_id` on every payload |
| `--rate-limit` | `2` | Max create requests per second (batch) |
| `--dry-run` | off | Validate payloads only |
| `--no-progress` | off | Disable rich progress bar |

Batch mode reads `manifest.json` from `profile-factory batch`. Partial failures are reported in `failed_profiles`; exit code is non-zero if any profile failed.

## Limitations

- **Offline by default** — `validate`, `render`, and `batch` do not call MLX; `mlx-create` requires `MLX_TOKEN` and network.
- **Template variables** — `{{ name }}`, `{{ proxy }}`, etc. must be supplied via `--vars`; unknown keys fail in strict mode.
- **Not a fingerprint generator** — templates organize locale, screen, and proxy; use [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) to audit signal coherence.
- **Single vendor target** — payloads target MLX `profile/create`; other antidetect APIs may need field mapping.

## Production

Lint templates with [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/), assign proxies via [proxy-lane-checker](https://pypi.org/project/proxy-lane-checker/), then `profile-factory mlx-create` batch manifests. After competitor import, use `antidetect-import` gap reports before create.

**Partner note (affiliate):** If you are standardizing **Multilogin X** `profile/create` at folder scale (not one-off JSON edits), isolated profiles with matched proxy + fingerprint often outperform ad-hoc API payloads. Eligible new browser purchases may accept code **`SAAS50`** at [multilogin.com](https://multilogin.com?a_aid=saas) — verify current terms before checkout. Full disclosure: [docs/AFFILIATE.md](docs/AFFILIATE.md). Deals hub: [anti-detect.github.io](https://anti-detect.github.io/). Coupon details only via `profile-factory --show-deal` (never printed by default).

**FAQ:** [docs/FAQ.md](docs/FAQ.md) — Multilogin YAML templates, batch `mlx-create`, antidetect profile variables.

## Development

```bash
cd profile-yaml-factory
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check .
python -m build
```





## Related tools (on PyPI)

| Package | CLI | Role |
|---------|-----|------|
| [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/) | `cdp-probe` | CDP / WebDriver exposure score |
| [cookie-jar-bridge](https://pypi.org/project/cookie-jar-bridge/) | `cookie-bridge` | Netscape ↔ Playwright cookies |
| [proxy-lane-checker](https://pypi.org/project/proxy-lane-checker/) | `proxy-lane` | Proxy TCP / HTTP / geo / DNSBL |
| [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) | `fp-coherence` | UA / screen / timezone lint |

**Toolkit pipeline:** `proxy-lane check` → `fp-coherence audit` → automate → `cdp-probe run` → `cookie-bridge validate`

## License

MIT

---

**Production antidetect (partner):** [Multilogin X](https://multilogin.com?a_aid=saas) · Code `SAAS50` (-50% browser) · `MIN50` (-50% cloud phone)  
Affiliate disclosure — we may earn a commission; offers change on the vendor site. More scripts: [@Multilogin_Scripts_Bot](https://t.me/Multilogin_Scripts_Bot) · [Multilogin promo codes](https://anti-detect.github.io/)
