{"id":31259991,"url":"https://github.com/rokoss21/facet","last_synced_at":"2026-01-20T17:29:06.302Z","repository":{"id":313625184,"uuid":"1052025013","full_name":"rokoss21/FACET","owner":"rokoss21","description":"FACET (Feature‑Aware Contracted Extension for Text) is a human‑readable, machine‑deterministic markup language for AI prompting, orchestration, and tooling","archived":false,"fork":false,"pushed_at":"2025-09-07T12:22:23.000Z","size":82,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-07T12:26:35.041Z","etag":null,"topics":["ai","ai-agents","ai-prompts","development","devops","facet","json","language","language-model","prompt-engineering","yaml"],"latest_commit_sha":null,"homepage":"https://github.com/rokoss21/FACET","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rokoss21.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-07T08:37:15.000Z","updated_at":"2025-09-07T12:22:26.000Z","dependencies_parsed_at":"2025-09-07T12:26:38.637Z","dependency_job_id":"c5e82231-71ce-4c94-ad60-4746ed39ae28","html_url":"https://github.com/rokoss21/FACET","commit_stats":null,"previous_names":["rokoss21/facet"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/rokoss21/FACET","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rokoss21%2FFACET","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rokoss21%2FFACET/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rokoss21%2FFACET/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rokoss21%2FFACET/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rokoss21","download_url":"https://codeload.github.com/rokoss21/FACET/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rokoss21%2FFACET/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276545728,"owners_count":25661361,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-23T02:00:09.130Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","ai-prompts","development","devops","facet","json","language","language-model","prompt-engineering","yaml"],"created_at":"2025-09-23T08:45:32.767Z","updated_at":"2025-09-23T08:45:37.481Z","avatar_url":"https://github.com/rokoss21.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FACET — Feature-Aware Contracted Extension for Text\n\n**A deterministic markup language for the AI era.**\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/rokoss21/FACET/main/assets/logo.png\" alt=\"FACET Logo\" width=\"100%\" height=\"auto\" style=\"max-width: 600px;\"\u003e\n  \u003cbr\u003e\n  \u003ch3\u003e🚀 Feature-Aware Contracted Extension for Text\u003c/h3\u003e\n  \u003cp\u003e\u003cem\u003eHuman-readable, machine-deterministic instructions for AI systems.\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n[![spec](https://img.shields.io/badge/spec-v1.1%20\\(Draft%20r3\\)-4c1)](https://github.com/rokoss21/FACET/blob/main/FACET-Language-Spec-v1.1-r3.md)\n[![status](https://img.shields.io/badge/status-draft-yellow)](https://github.com/rokoss21/FACET/blob/main/FACET-Language-Spec-v1.1-r3.md)\n[![mime](https://img.shields.io/badge/MIME-application%2Ffacet-blue)](#)\n[![ext](https://img.shields.io/badge/ext-.facet-blueviolet)](#)\n[![author](https://img.shields.io/badge/author-Emil%20Rokossovskiy-0aa)](https://github.com/rokoss21)\n\n\u003c!-- PyPI badges --\u003e\n[![PyPI version](https://img.shields.io/pypi/v/facet-lang.svg)](https://pypi.org/project/facet-lang/)\n[![PyPI downloads](https://img.shields.io/pypi/dm/facet-lang.svg)](https://pypi.org/project/facet-lang/)\n[![Python versions](https://img.shields.io/pypi/pyversions/facet-lang.svg)](https://pypi.org/project/facet-lang/)\n[![License](https://img.shields.io/pypi/l/facet-lang.svg)](https://github.com/rokoss21/FACET/blob/main/LICENSE)\n\n---\n\n## ✨ What is FACET?\n\n**FACET** is a markup language for authoring, managing, and executing instructions for AI systems. It merges the **clarity of plain text** with the **rigor of code** to build **reproducible** AI pipelines.\n\nEvery FACET document compiles to a **single canonical JSON** — no YAML-style ambiguity, no hidden magic. Version **v1.1** turns FACET into a **compile-time configuration language** with modularity, logic, static typing, and a pure transformation pipeline (*lenses*).\n\n---\n\n## 🧠 How FACET Works\n\n```\n+------------------+     +------------------+     +-----------------+\n|                  |     |                  |     |                 |\n|   .facet file    | --\u003e |   FACET Parser   | --\u003e |  Canonical JSON |\n|   (Source Text)  |     | (Lenses,         |     |     (Output)    |\n|                  |     |  Contracts)      |     |                 |\n+------------------+     +------------------+     +-----------------+\n        |                        |                       |\n        |-- Facets (@user)       |-- Data transforms     |-- Deterministic\n        |-- Attributes (name=\"\") |-- Schema validation   |-- Reproducible\n        |-- Lenses (|\u003e trim)     |-- Type checking       |-- Tool‑ready\n        |-- Contracts (@output)  |-- Error handling      |-- Always valid\n```\n\nAt authoring time you write readable `.facet` files. The reference parser expands imports, resolves variables, applies conditionals, validates types/contracts, and executes pure lens pipelines — producing a single canonical JSON that downstream tools can rely on.\n\n---\n\n## 🚀 The Innovation (Why Now, Why FACET)\n\nModern AI stacks drown in a mix of ad-hoc prompts, brittle scripts, and ambiguous configs. FACET replaces that with **contracts and determinism**.\n\n* **Deterministic by design:** One source → one canonical JSON. No surprises.\n* **Contract-first prompting:** Use `@output` to enforce **JSON Schema** on model responses. Prompts stop being strings and become **APIs with guarantees**.\n* **Compile-time intelligence:** `@import`, `@vars`, `@var_types`, and `if=\"EXPR\"` give вам модульность, параметризацию и статическую проверку ещё до запуска.\n* **Pure transformation pipeline:** **Lenses (`|\u003e`)** — встроенные детерминированные функции (в т.ч. `choose(seed)`/`shuffle(seed)`), без I/O и сайд-эффектов.\n* **Security model:** Import allowlists, sandboxed lenses, отсутствие неявного доступа к окружению.\n\n**FACET doesn’t just configure AI — it programs the instruction itself.**\n\n---\n\n## 🥊 FACET vs. Existing Options\n\n| Capability / Tooling                       | YAML + JSON | Jsonnet/Cue | Templating (Jinja/Mustache) | **FACET** |\n| :----------------------------------------- | :--------------: | :---------: | :-------------------------: | :-------: |\n| Canonical, deterministic serialization     |        ⚠️ Depends |           ✅ |            ❌ (runtime text) |       **✅** |\n| Contract-first (enforce model output)      |  🟡 External glue |          🟡 |                           ❌ | **✅ `@output`** |\n| Compile-time imports \u0026 deterministic merge |        🟡 Plugins |          🟡 |                           ❌ | **✅ `@import`** |\n| Static typing for variables                |   🟡 Schema hacks |           ✅ |                           ❌ | **✅ `@var_types`** |\n| Conditional inclusion (no runtime eval)    |                🟡 |           ✅ |       ⚠️ Runtime templating | **✅ `if=\"EXPR\"`** |\n| Pure pipelines for text/JSON transforms    |                 ❌ |          🟡 |                           ❌ | ✅ `Lenses` |\n| Deterministic randomness (seeded)          |                 ❌ |          🟡 |                           ❌ | **✅ `choose`/`shuffle`** |\n| Sandbox for user plugins                   |  ⚠️ Tool-specific |          🟡 |                           ❌ | **✅ (spec §12)** |\n\n\u003e FACET combines the **readability of config** with the **guarantees of a DSL** that’s purpose-built for AI orchestration.\n\n---\n\n## 🧩 Core Concepts (v1.1)\n\n* **Facets \u0026 Contracts:** Structured blocks (`@system`, `@user`, `@plan`, `@output`, …).\n* **Modularity:** `@import` with deterministic `merge` / `replace`.\n* **Variables:** `@vars` and string interpolation `{{path}}`; scalar substitution `$name`.\n* **Static Typing:** `@var_types` enforces `type/enum/min/max/pattern` at compile time.\n* **Conditionals:** `if=\"EXPR\"` on any facet or list item (no runtime eval).\n* **Lenses:** `value |\u003e lensA |\u003e lensB(...)` — pure, safe transformations (incl. deterministic `choose(seed)`/`shuffle(seed)`).\n* **Security:** allowlisted imports, sandboxed lenses, no implicit env reads.\n\n---\n\n## 📖 Syntax in Action\n\n```facet\n# 1) Reuse prompt fragments and contracts\n@import \"common/prompts.facet\"\n@import(path=\"common/output_contracts.facet\", strategy=\"merge\")\n\n# 2) Declare and type-check variables at compile-time\n@vars\n  username: \"Alex\"\n  mode: \"expert\"\n  seed: 42\n  features: [\"recursion\", \"tail-calls\"]\n  greetings: [\"Hi\", \"Hello\", \"Hey\"]\n\n@var_types\n  mode: { type: \"string\", enum: [\"user\", \"expert\"] }\n  seed: { type: \"int\", min: 0 }\n\n# 3) Conditional facets\n@system(role=\"Deep Technical Expert\", if=\"mode == 'expert'\")\n  constraints:\n    - \"Use precise terminology.\"\n\n# 4) Interpolation + deterministic choice + formatting\n@user\n  request: \"\"\"\n    {{ greetings |\u003e choose(seed=$seed) }}, {{username}}!\n    Explain recursion with examples.\n  \"\"\" |\u003e dedent\n\n# 5) Conditional list items\n@plan\n  steps:\n    - \"Introduction\"\n    - \"Tail-call optimization\" (if=\"'tail-calls' in features\")\n\n# 6) Contract-first output (enforced by host)\n@output\n  schema:\n    type: \"object\"\n    required: [\"summary\",\"examples\"]\n    properties:\n      summary: { type: \"string\" }\n      examples: { type: \"array\", items: { type: \"string\" } }\n```\n\n✅ Readable • ✅ Dynamic • ✅ Reproducible • ✅ Contract-enforced\n\n---\n\n## 🧭 Canonization Pipeline (Deterministic)\n\n1. **Imports** → 2) **Variable resolution** → 3) **`@var_types` validation** →\n2. **Conditional filtering** → 5) **Anchors/Aliases** → 6) **Lenses** →\n3. **Canonical JSON construction** (stable key order)\n\n\u003e Compile-time facets (`@import`, `@vars`, `@var_types`) **do not appear** in the final JSON.\n\n---\n\n## 🧪 Canonical JSON (Illustrative)\n\n```json\n{\n  \"system\": {\n    \"_attrs\": { \"role\": \"Deep Technical Expert\" },\n    \"constraints\": [\"Use precise terminology.\"]\n  },\n  \"user\": {\n    \"request\": \"Hello, Alex!\\nExplain recursion with examples.\"\n  },\n  \"plan\": {\n    \"steps\": [\"Introduction\", \"Tail-call optimization\"]\n  },\n  \"output\": {\n    \"schema\": {\n      \"type\": \"object\",\n      \"required\": [\"summary\",\"examples\"],\n      \"properties\": {\n        \"summary\": { \"type\": \"string\" },\n        \"examples\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } }\n      }\n    }\n  }\n}\n```\n\n*(The exact content depends on chosen seed and inputs; structure and ordering are deterministic.)*\n\n---\n\n## 🧰 Installation\n\n**Requirements:** Python ≥ 3.9\n\n```bash\npip install facet-lang\n```\n\n### ⚡ 60-second dynamic prompt (after install)\n\n1. Create a file:\n   ```bash\n   cat \u003e my_prompt.facet \u003c\u003c EOF\n   @vars\n     mode: \"user\"\n\n   @system(if=\"mode == 'expert'\")\n     role: \"You are a world-class computer science professor.\"\n\n   @user\n     request: \"Explain recursion to me.\"\n   EOF\n   ```\n2. Run in \"user\" mode (no system block):\n   ```bash\n   facet canon --var \"mode=user\" my_prompt.facet\n   ```\n3. Run in \"expert\" mode (system appears):\n   ```bash\n   facet canon --var \"mode=expert\" my_prompt.facet\n   ```\n\n**Python API**\n\n```python\nfrom facet_lang import canonize\n\ndoc = \"\"\"@user\n  request: \"Hello\"\n\"\"\"\nprint(canonize(doc, resolve_mode=\"all\"))\n```\n\n**CLI**\n\n```bash\n# Canonize a file\nfacet canon --resolve=all samples/complex.facet\n\n# From stdin\ncat samples/complex.facet | facet canon -\n```\n\n---\n\n## 🧠 FACET System Prompt\n\n`FACET_SYSTEM_PROMPT.md` helps LLMs produce valid `.facet` files by following syntax and canonization rules.\nUse it as a system message in your agent/tooling to **generate FACET natively**.\n\n---\n\n## 🔐 Security Model (Essentials)\n\n* **Imports:** allowlisted roots, no network URLs, no path escapes.\n* **Variables:** no implicit env reads — host must pass them explicitly.\n* **Conditionals:** dedicated parser (no `eval`).\n* **Lenses:** sandboxed, timeouts, no I/O/time/random; deterministic `choose`/`shuffle` require explicit `seed`.\n\n---\n\n## 🧭 When to Use FACET (Real-World Wins)\n\n* **Enterprise prompts with SLAs:** enforce output contracts → stable downstream pipelines.\n* **Multi-env orchestration:** one source with `if=\"EXPR\"`/`@vars` → dev/staging/prod without file sprawl.\n* **Agent pipelines:** shared libraries via `@import`, deterministic transforms via lenses.\n* **AB-tests \u0026 seeded variants:** reproducible `choose(seed)`/`shuffle(seed)` for prompt alternatives.\n\n---\n\n## ❓ FAQ (Objections You Might Have)\n\n**“Why a dedicated language? Why not YAML + JSONSchema?”**\nYAML remains ambiguous and typically requires external glue/scripts. FACET provides a **single deterministic pipeline** end‑to‑end: imports → typing → conditionals → lenses → canonical JSON.\n\n**“Why not Cue/Jsonnet?”**\nThey are general‑purpose. FACET is purpose‑built for AI: `@output` contracts, built‑in lenses, explicit conditional semantics, bans on I/O/randomness, and determinism out of the box.\n\n**“How do we keep it secure?”**\nThe spec includes sandboxing and restrictions (see §12). Lenses are pure (no I/O), imports are allowlisted, and variables are only provided explicitly by the host.\n\n---\n\n## 🗺️ Roadmap\n\n### ✅ v1.1 — Foundation\n\n* Finalize spec, strengthen reference parser, expand samples \u0026 docs.\n\n### 🚀 Next — Tooling \u0026 Integrations\n\n* **LSP** (VS Code/JetBrains/Zed/NeoVim): realtime diagnostics, autocomplete, hovers.\n* **SDKs:** TypeScript / Rust (наряду с Python).\n* **CI/CD:** ready-made GitHub Actions for canonization \u0026 schema checks.\n\n### 🔮 Vision — Orchestration Stack\n\n* **FACET MCP Server:** high-performance agent-first runtime.\n* **Plugin Registry:** curated, sandboxed lens ecosystem.\n* **Playground:** visual canonization \u0026 learning.\n\n---\n\n## 🤝 Contributing\n\n* **Discussions:** ideas, proposals, showcases\n* **Issues:** bugs \u0026 tasks\n* **PRs:** features, fixes, docs\n\n---\n\n## 👤 Author\n\n**Emil Rokossovskiy** — [@rokoss21](https://github.com/rokoss21)\n\n---\n\n## 📄 License\n\n**MIT** — see [LICENSE](LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frokoss21%2Ffacet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frokoss21%2Ffacet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frokoss21%2Ffacet/lists"}