Human-readable, machine-deterministic instructions for AI systems.
NADL represents a fundamental paradigm shift in AI engineering - from artisanal prompt crafting to mathematical architecture description.
Traditional AI Development:
# Chaotic, manual, unpredictable
prompt = """
You are a helpful assistant.
Please analyze this data: {data}
Be nice and professional.
"""FACET NADL:
@var_types user_query: { type: "string", min_length: 1, max_length: 1000 }
@vars user_query: "Analyze sales data"
@system role: "data_analyst"
model: "gpt-4"
instructions: "You are a professional data analyst. Analyze: $user_query"
@user content: $user_query |> trim() |> lowercase()
| Principle | Traditional AI | FACET NADL |
|---|---|---|
| Architecture | Prompt strings | Typed AST + DAG |
| Execution | Runtime interpretation | Compile-time validation |
| Behavior | Emergent properties | Deterministic algorithms |
| Testing | Manual verification | Automated test suites |
| Maintenance | Git + hope | Type checking + contracts |
| Scaling | Trial & error | Mathematical guarantees |
┌─────────────────────────────────────────┐
│ FACET NADL: Neural Architecture Language│
├─────────────────────────────────────────┤
│ Type System (FTS) - Static typing │
│ Reactive DAG - Execution ordering │
│ Token Box Model - Context management │
│ Lens System - Data transformations │
│ Testing Framework - Behavior validation │
└─────────────────────────────────────────┘
↑
Infrastructure-as-Code for Neural Networks
NADL solves the three fundamental problems of AI engineering:
-
🎲 Determinism Problem: Neural networks are stochastic by nature. NADL makes their behavior deterministic.
-
🔧 Maintenance Problem: AI systems rot like code. NADL provides type checking, testing, and refactoring tools.
-
📈 Scaling Problem: AI development doesn't scale. NADL brings software engineering discipline to AI.
Result: AI systems that behave like software - versionable, testable, maintainable, scalable.
"Write once, run everywhere. Predict behavior, guarantee performance, scale infinitely."
NADL transforms AI from black-box magic into white-box engineering.
| Approach | Method | Determinism | Scalability | Maintenance |
|---|---|---|---|---|
| Prompt Engineering | Manual crafting | ❌ Low | ❌ Poor | ❌ Difficult |
| Fine-tuning | Model training | ❌ Hard | ||
| RAG Systems | Vector search + prompts | ✅ Good | ||
| Agent Frameworks | Code + prompts | ✅ Good | ✅ Code-like | |
| FACET NADL | Declarative architecture | ✅ High | ✅ Excellent | ✅ Software-grade |
FACET introduces four breakthrough innovations:
- 📋 Facet Type System (FTS) - First type system specifically for neural architectures
- 🔄 Reactive DAG Engine - Mathematical execution ordering with dependency resolution
- 📦 Token Box Model - CSS-like layout algorithm for context window management
- 🔧 Lens System - Pure functional transformations for neural data pipelines
Together, these create the first true programming language for describing neural network behavior.
Quick Start • Documentation • Specification • Examples
AI development today is broken. Here's why:
- "It works on my machine" - Prompts behave differently across models, versions, temperatures
- Fragile string manipulation - One character change breaks everything
- No reusability - Copy-paste prompt fragments between projects
- No testing - Can't unit test AI behavior
- No versioning - Prompt evolution is tribal knowledge
- Token counting nightmares - Manual calculation, off-by-one errors
- Budget overruns - AI calls fail mid-conversation due to token limits
- Layout unpredictability - System messages, examples, user input - what fits?
- Cost unpredictability - Token usage spikes destroy budgets
- No type safety - Runtime errors from malformed data
- No modularity - Monolithic prompts, hard to maintain
- No contracts - AI outputs don't match expectations
- No debugging - Black box behavior, hard to troubleshoot
- Environment drift - Different behavior in dev/staging/prod
- Scaling issues - Performance degrades under load
- Compliance gaps - No audit trails, hard to govern
- Team collaboration - Prompt changes break other features
AI engineering deserves the same rigor as software engineering.
Instead of: Fragile prompt strings and tribal knowledge We believe: AI behavior should be coded, versioned, tested, and deployed like software
Instead of: Runtime surprises and context limit failures We believe: AI systems should have mathematical guarantees about resource usage
Instead of: Manual prompt engineering We believe: AI architectures should be modular, reusable, and composable
FACET v2.0 transforms the chaotic world of prompt engineering into a rigorous engineering discipline. It is a strict compiler that turns .facet architecture files into canonical, reproducible JSON agent definitions with mathematically stable behavior across all platforms.
Problem: AI systems are unpredictable, expensive, and hard to maintain Solution: Treat AI behavior as compiled, typed, tested code
Problem: Context windows are manual guesswork with failure modes Solution: Mathematical token allocation with zero surprise failures
Problem: AI development is artisanal craft Solution: Engineering discipline with tools, processes, and guarantees
This isn't just another GitHub repository. This is the foundation of how AI engineering will be done at scale.
- 📈 Vision 2025: Leading AI engineering companies adopt FACET
- 🎯 Vision 2026: FACET becomes the default choice for enterprise AI
- 🌟 Vision 2030: FACET is the infrastructure standard for AI behavior
FACET transforms "AI prompt hacking" into "AI software engineering."
- 🧬 Type System (FTS) - Static analysis catches errors before deployment
- ⚡ Reactive Engine (R-DAG) - Declarative variable resolution, order-independent
- 📐 Token Box Model - Mathematical context allocation, guaranteed fitting
- 🔬 Testing Framework - Unit tests for AI behavior, mocks for external APIs
- 📦 Compilation Pipeline - Predictable, reproducible, auditable outputs
Result: AI systems that behave like software - deterministic, maintainable, scalable.
FACET is not just another AI tool—it's the infrastructure standard that transforms AI engineering from chaos to industrial discipline.
| Infrastructure Layer | Before | After | FACET's Role |
|---|---|---|---|
| Physical | Manual labor | Industrial machines | Hardware → Software |
| Compute | Bare metal | Virtualization | VMs → Containers |
| Cloud | Manual provisioning | IaC | ClickOps → Terraform |
| AI | Prompt engineering | Structured behavior | Chaos → FACET |
Just as Docker brought containers to software, FACET brings structure to AI behavior.
FACET targets Fortune 500 AI transformation:
- 75% reduction in AI development time
- 90% fewer production AI failures
- 50% cost savings on AI infrastructure
- Zero "AI went wrong" incidents
By 2026, FACET becomes:
- ✅ Default choice for enterprise AI engineering
- ✅ Referenced in RFCs for AI system design
- ✅ Integrated by default in major AI platforms
- ✅ Taught in universities as AI engineering standard
"If you build AI systems, FACET is your engineering discipline."
Not just a tool. Not just a framework. The standard that makes AI engineering possible at scale.
Most AI tools are frameworks. They give you building blocks but leave engineering to chance.
FACET is a compiler. It gives you mathematical guarantees about behavior and resource usage.
| Aspect | Traditional AI Tools | FACET v2.0 |
|---|---|---|
| Approach | Frameworks & libraries | Compiler & type system |
| Safety | Runtime validation | Compile-time guarantees |
| Resources | Guesswork & failure | Mathematical allocation |
| Testing | Manual & external | Built-in unit testing |
| Modularity | Ad-hoc composition | Typed interfaces |
| Reproducibility | "Works on my machine" | Deterministic across platforms |
| Maintainability | Tribal knowledge | Versioned, documented code |
| Scalability | Performance degrades | Predictable scaling |
"Performance isn't optional - it's guaranteed."
- Sub-second compilation for enterprise-scale configurations
- Zero token allocation surprises - mathematical guarantees
- Predictable scaling - R-DAG engine optimizations
- Memory efficiency - compiled to optimal runtime representations
"Zero-trust architecture from the ground up."
- Hermetic execution - no network access during compilation
- Type safety - prevents injection attacks
- Audit trails - every transformation is traceable
- Sandboxing - lenses run in controlled environments
"AI behavior should be engineered, not prompted."
- Code, not magic - explicit, versioned, testable
- Composition over concatenation - modular, reusable components
- Contracts over hope - typed interfaces with guarantees
- Engineering over art - systematic, repeatable processes
FACET v2.0 is engineered for high-reliability enterprise environments.
| Metric | Status | Description |
|---|---|---|
| Test Coverage | 100% | 54/54 tests passing, covering unit, integration, and E2E scenarios. |
| Error Handling | 100% | Full coverage of all 29 error codes (F001-F902). Zero unhandled panics. |
| Performance | <50ms | Sub-second compilation time for enterprise-scale configurations. |
| Safety | Hermetic | No network access during compilation. Zero-trust architecture. |
| Stability | Stable | R-DAG engine guarantees deterministic execution order. |
- Facet Type System (FTS): Full static typing for variables (
string,int,struct,list). - Compile-time Checks: Catch type mismatches (F451) and constraint violations (F452) before deployment.
- Constraint Enforcement: Native support for regex patterns, min/max ranges, and enums.
- R-DAG Engine: Reactive Dependency Graph automatically resolves execution order. Declarative syntax means order of definition doesn't matter.
- Token Box Model: A revolutionary algorithm for context management (CSS-like
priority,grow,shrinkfor text). Guarantees you never hit context limits unexpectedly.
- Lens System: 32+ built-in pure functions for data transformation (
trim,split,json,template). - Pipeline Syntax: Unix-style piping:
$input |> trim() |> uppercase() |> summarize().
- Modular Import System: Compose agents from reusable modules with circular dependency detection.
- Testing Framework: Built-in
@testblocks with mocking and assertions. Test your prompts like code. - WASM Support: Runs in the browser, Node.js, and on the edge.
The FACET compiler operates as a strictly typed, multi-phase pipeline:
graph LR
A[Source .facet] --> B(Parser)
B --> C(Resolver)
C --> D(Type Checker)
D --> E{R-DAG Engine}
E --> F(Token Box Model)
F --> G[Canonical JSON]
- Resolution: Parse AST, resolve imports, detect cycles.
- Validation: Enforce FTS types, interface contracts, and lens signatures.
- Compute: Execute reactive graph, apply lenses, track gas usage.
- Layout: Allocate context window budget deterministically.
- Render: Generate vendor-agnostic or specific (OpenAI/Anthropic) payloads.
Prerequisites: Rust 1.70+
# Clone and build optimized release binary
git clone https://github.com/rokoss21/facet-compiler.git
cd facet-compiler
cargo build --release
# Add to PATH (optional)
export PATH="$PWD/target/release:$PATH"📦 NPM Package (Coming Soon):
npm install -g facet-compiler🐍 PyPI Package (Coming Soon):
pip install facet-compilerNote: JavaScript/TypeScript and Python packages will be available in the coming weeks. For now, use the Rust binary above.
@var_types
user_name: { type: "string", pattern: "^[a-zA-Z]+$" }
@vars
user_name: "Alice"
# Pipeline transformation
greeting: $user_name |> trim() |> uppercase()
@system
role: "assistant"
model: "gpt-4"
# Variables are interpolated safely
instructions: "You are a helpful assistant for user: $greeting"
@user
query: "Hello, world!"
# 1. Build (Validate syntax and types)
fct build --input agent.facet
# 2. Run (Execute pipeline and render JSON)
fct run --input agent.facet --budget 4096 --format pretty// Traditional approach - fragile, untestable
const systemPrompt = `
You are a customer support agent for ACME Corp.
Handle inquiries about our products: ${products.join(', ')}
Be friendly but professional. Use our brand voice.
If they ask about pricing, mention our discount program.
Always end with: "How else can I help you today?"
`;
// Runtime concatenation - error-prone
const userMessage = `Hi! I bought ${productName} yesterday.
${complaint ? `I'm having this issue: ${complaint}` : ''}
${refund ? 'I want a refund.' : 'I have a question.'}`;
// Token counting - manual, error-prone
const totalTokens = estimateTokens(systemPrompt) + estimateTokens(userMessage);
if (totalTokens > 4000) {
// Truncate or fail - unpredictable behavior
systemPrompt = systemPrompt.substring(0, 2000);
}Problems:
- ❌ String manipulation errors
- ❌ No type safety for
products,complaint,refund - ❌ Manual token counting leads to failures
- ❌ Untestable logic
- ❌ Environment-specific behavior
@var_types
user_name: { type: "string", pattern: "^[a-zA-Z]+$" }
products: { type: "list", items: { type: "string" } }
complaint: { type: "string", optional: true }
refund_requested: { type: "boolean", default: false }
@vars
user_name: "Alice"
products: ["Widget Pro", "Gizmo Max", "Tool Kit"]
complaint: null
refund_requested: false
@system
role: "Customer Support Agent"
company: "ACME Corp"
personality: "friendly but professional"
products: $products
discount_program: "Save 15% on your next purchase"
@user
greeting: "Hi $user_name!"
inquiry: $complaint |> default("I have a question about $products |> first")
request: $refund_requested |> if("true", "I want a refund", "I need help")
@output
schema:
type: "object"
required: ["response", "follow_up"]
properties:
response: { type: "string" }
follow_up: { type: "string", pattern: "How else can I help you today\\?" }
Benefits:
- ✅ Type safety - FTS catches errors at compile time
- ✅ Testable - Unit tests for AI behavior
- ✅ Predictable - Guaranteed token allocation
- ✅ Maintainable - Modular, versioned, documented
- ✅ Reusable - Components work across projects
FACET v2.0 transforms how AI agents are built, deployed, and maintained across industries.
Problem: Prompt engineering is artisanal - inconsistent, error-prone, hard to maintain. Solution: Treat prompts as code with type safety, testing, and modularity.
# Reusable agent components
@import "common/personality.facet"
@import "domain/expertise.facet"
@system
role: "Senior Software Architect"
expertise: $expertise_level
personality: $communication_style
@user
request: $user_query
Problem: Context window management, token optimization, deterministic behavior. Solution: Mathematical token allocation with the Token Box Model.
# Guaranteed context fitting
fct run --input pipeline.facet --budget 128000
# Result: Deterministic layout, no surprisesProblem: AI systems need to integrate with existing enterprise workflows. Solution: Type-safe interfaces, validation, and deployment pipelines.
@interface "APIGateway"
endpoint: "https://api.company.com/agents"
auth: { type: "bearer", token: $api_key }
schema: $response_contract
Problem: AI outputs are unpredictable and hard to test. Solution: Built-in testing framework with mocks and assertions.
@test "customer_support"
mock:
CRM.lookup_customer: { status: "premium" }
assert:
- output contains "premium support"
- cost < 0.05
Problem: Manual prompt iteration slows deployment cycles. Solution: Automated validation and testing in CI pipelines.
# GitHub Actions example
- name: Validate FACET files
run: fct build --input agents/*.facet
- name: Run test suite
run: fct test --input agents/tests.facet --output json| Feature | FACET v2.0 | YAML + JSON Schema | Jinja2 Templates | LangChain Prompts |
|---|---|---|---|---|
| Type Safety | ✅ Static FTS | ❌ None | ❌ None | |
| Deterministic | ✅ Mathematical | ✅ Structured | ❌ Template vars | ❌ Randomness |
| Modular | ✅ @import system | |||
| Testable | ✅ Built-in @test | ❌ Manual | ❌ Manual | |
| Compiled | ✅ Native binary | ❌ Interpreted | ❌ Interpreted | ❌ Interpreted |
| Performance | ✅ <50ms | ❌ Slow |
FACET combines the best of all worlds: structure of YAML, safety of TypeScript, modularity of programming languages, and performance of compiled systems.
import { FacetCompiler } from 'facet-compiler';
import OpenAI from 'openai';
const compiler = new FacetCompiler();
const agent = compiler.compile('agent.facet');
// Direct integration
const openai = new OpenAI();
const response = await openai.chat.completions.create({
...agent.system,
messages: agent.messages,
max_tokens: agent.layout.total_budget
});from facet_fct import compile_facet
import anthropic
agent = compile_facet("claude_agent.facet")
client = anthropic.Anthropic()
response = client.messages.create(
model=agent.system.model,
max_tokens=agent.layout.max_tokens,
system=agent.system.instructions,
messages=agent.canonical_messages
)FROM rust:1.70-slim as builder
WORKDIR /app
COPY . .
RUN cargo build --release
FROM debian:bookworm-slim
COPY --from=builder /app/target/release/fct /usr/local/bin/
CMD ["fct", "run", "--input", "/config/agent.facet"]name: Validate AI Agents
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- run: cargo install --git https://github.com/rokoss21/facet-compiler.git
- name: Validate agents
run: fct build --input agents/*.facet
- name: Run tests
run: fct test --input agents/tests.facet --output json >> test-results.json
- name: Upload results
uses: actions/upload-artifact@v4
with:
name: test-results
path: test-results.jsonFor AI Engineering Teams:
- 75% reduction in prompt debugging time
- 90% fewer production token limit failures
- 50% faster AI feature development cycles
- Zero "works in dev, fails in prod" incidents
For Product Teams:
- Predictable AI behavior across releases
- Versioned AI capabilities like software features
- Testable AI features with automated regression testing
- Scalable AI deployment with resource guarantees
For DevOps Teams:
- Automated AI validation in CI/CD pipelines
- Infrastructure cost control with token budgeting
- Compliance & audit trails for AI decision-making
- Multi-environment consistency (dev/staging/prod)
Core Infrastructure:
- ⚡ 5-phase compilation pipeline with sub-second performance
- 🔬 Facet Type System (FTS) with 100% compile-time safety
- 🎯 32 lens functions (extended library beyond specification)
- 🧪 Built-in testing framework with mocks and assertions
- 📦 Modular architecture with clean crate separation
- 🌐 WASM compilation for browser and edge deployment
Enterprise Features:
- 🛡️ Zero-trust security model with hermetic execution
- 📊 Mathematical token allocation via Token Box Model
- 🔄 R-DAG reactive engine for order-independent computation
- 📋 54/54 test coverage with zero unhandled errors
- 🏗️ Production CLI with advanced logging and progress tracking
Advanced Multimodal:
- 🖼️ Image processing pipelines with metadata sanitization
- 🎵 Audio analysis workflows with format validation
- 📊 Embedding generation with vector operations
- 🔒 Content security scanning for malicious inputs
Profile System:
- 👥 Core Profile: Lightweight, text-only execution
- 🏢 Hypervisor Profile: Full enterprise features
- 🔄 Execution Modes: Pure vs Bounded external calls
- ⚙️ Configuration management for different environments
Performance & Scalability:
- 🚀 Parallel compilation for large agent networks
- 💾 Intelligent caching of parsed ASTs and computations
- 📈 Horizontal scaling support for high-throughput deployments
- 💰 Cost optimization algorithms for token usage
Developer Experience:
- 🛠️ VS Code extension with IntelliSense and debugging
- 📝 Language Server Protocol for all major editors
- 🔍 Interactive playground for FACET development
- 📚 Comprehensive documentation with tutorials and guides
SDK Generation:
- 🐍 Python SDKs with Pydantic models and async support
- ☕ Java SDKs with Spring Boot integration
- 🔷 TypeScript SDKs with full type safety
- 🦀 Rust SDKs with zero-cost abstractions
Cloud Integrations:
- ☁️ AWS Lambda deployment with API Gateway integration
- 🔄 Vercel edge functions for global AI deployment
- 🌐 Cloudflare Workers for CDN-integrated AI
- 🐳 Docker containers optimized for AI workloads
Distributed AI Orchestration:
- 🌐 Multi-agent coordination with typed communication protocols
- 🔄 Event-driven architectures for complex AI workflows
- 📊 Distributed tracing across agent networks
- ⚖️ Load balancing for AI service meshes
Advanced AI Capabilities:
- 🧠 RAG orchestration with vector database integration
- 🎨 Multimodal processing pipelines with content understanding
- 🤖 Agent marketplaces with verified, composable components
- 📈 Performance profiling and bottleneck analysis
Enterprise Compliance:
- 🔐 End-to-end encryption for sensitive AI workflows
- 📋 Regulatory compliance frameworks (GDPR, HIPAA, SOX)
- 📊 Audit trails for AI decision-making processes
- 🛡️ Zero-trust security with formal verification
FACET becomes the universal standard for AI behavior engineering - transforming how the world builds, deploys, and maintains AI systems.
This repository evolves from "interesting GitHub project" to "the standard that powers AI infrastructure worldwide."
Like Docker revolutionized containerization, Terraform revolutionized infrastructure, FACET revolutionizes AI engineering.
The transformation is complete: From chaos to industrial discipline.
- 🏪 Agent Marketplaces: Verified, composable AI components
- 🌍 Cross-Platform Compatibility: Works with every LLM provider
- ⚖️ Regulatory Frameworks: Compliance-built-in AI deployment
- 🔗 Interoperability: AI agents communicate via standardized protocols
- 📈 Enterprise Adoption: Every major company uses FACET for AI
The future of AI is engineered, not prompted.
We welcome contributions from the community! FACET is designed to be extensible and community-driven.
Ways to contribute:
- Code: Bug fixes, features, performance improvements
- Documentation: Tutorials, examples, translations
- Testing: Additional test cases, integration testing
- Ecosystem: SDKs, integrations, tools
Getting started:
# Fork and clone
git clone https://github.com/rokoss21/facet-compiler.git
cd facet-compiler
# Run tests
cargo test --all
# Format code
cargo fmt --all
# Lint
cargo clippy -- -D warnings- Specification - Complete technical reference
- Examples - Real-world usage patterns
- Tutorial - Step-by-step learning guide
- FAQ - Common questions and answers
For enterprise deployments, commercial support, and custom integrations:
- Email: ecsiar@gmail.com
- Website: rokoss21.tech
- GitHub: @rokoss21
- Stars: Community adoption metric
- Forks: Active development and customization
- Issues: Bug reports and feature requests
- PRs: Community contributions
📖 Complete Online Documentation - Interactive docs with navigation and search
We provide comprehensive documentation for all skill levels.
-
Getting Started
- 01-quickstart.md — Get running in 5 minutes
- 02-tutorial.md — Complete learning path
- 06-cli.md — CLI Reference
-
Core Concepts
- 04-type-system.md — Facet Type System (FTS)
- 08-lenses.md — Standard Lens Library
- 13-import-system.md — Modularity & Imports
-
Advanced Engineering
- 03-architecture.md — Compiler Internals
- 09-testing.md — Unit Testing Prompts
- 10-performance.md — Optimization Guide
- 11-security.md — Security Model
FACET is structured as a cargo workspace with clean separation of concerns:
| Crate | Description |
|---|---|
fct-ast |
Abstract Syntax Tree definitions |
fct-parser |
nom-based parser logic |
fct-validator |
Type checker and FTS implementation |
fct-engine |
R-DAG execution and Token Box Model |
fct-std |
Standard Library (Lenses) |
fct-wasm |
WebAssembly bindings |
# Run the full test suite (Unit + Integration)
cargo test --all
# Run benchmarks
cargo benchEmil Rokossovskiy AI & Platform Engineer. Building deterministic, high-performance developer tools. Creator of FACET ecosystem 🚀
- GitHub: @rokoss21
- Compiler Repo: github.com/rokoss21/facet-compiler
- Email: ecsiar@gmail.com
- Website: rokoss21.tech
Compiler & Runtime: Apache License 2.0 Language Specification: MIT License
The FACET compiler, runtime libraries, and all executable code are licensed under:
- Apache License, Version 2.0 (LICENSE-APACHE)
This provides patent protection and compatibility with commercial enterprise use.
The FACET language specification, documentation, and examples are licensed under:
- MIT License (LICENSE-MIT)
This maximizes adoption and allows free use of the FACET language in any implementation.
FACET innovations are protected through multiple layers:
- © Copyright 2025 Emil Rokossovskiy - All rights reserved
- Patent Protection via Apache 2.0 license grants
- First-mover advantage as the original NADL implementation
- Brand protection through trademark and domain ownership
NADL (Neural Architecture Description Language) is a novel paradigm that transforms AI engineering from artisanal practice to systematic discipline.
From "Interesting GitHub Project" to "Industrial Standard" 🚀