TypeDialog/README.md

<div align="center">
  <img src="assets/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>

  ![Coverage](https://img.shields.io/badge/coverage-tracking-blue)

# TypeDialog

> ▲ Create Type-Safe Interactive Dialogs.
>
> Prompts, forms, schemas definition, use backends (CLI, TUI, Web, AI).
>
> Extended with LLM agents, IaC generation, and [Nickel](https://nickel-lang.org) validation.

## Features Implemented

### Core

- **6 Backends**: CLI (inquire), TUI (ratatui), Web (axum), AI (RAG/embeddings), Agent (LLM execution), Prov-gen (IaC generation)
- **8 Prompt Types**: text, confirm, select, multi-select, password, date, editor, custom
- **Declarative Forms**: Nickel (`.ncl`) definitions with type contracts, fragments & composition (TOML also supported)
- **4 Output Formats**: JSON, YAML, TOML, Nickel with roundtrip conversion
- **Zero Runtime Dependencies**: Core library works standalone

### Advanced

- **Type-Safe Schemas**: Bidirectional [Nickel](https://nickel-lang.org) integration for validation & serialization
- **Dynamic Logic**: Conditional fields, smart defaults, real-time validation, repeating groups
- **i18n**: Fluent (.ftl) translations with automatic locale detection
- **Encryption**: Field-level encryption with external service integration
- **Contracts**: Pre/post-conditions and business rule enforcement

### Infrastructure

- **3,818 Tests**: Comprehensive coverage (503% growth during development)
- **CI/CD**: GitHub Actions + Woodpecker pipelines with automated testing
- **Docker**: Multi-stage builds with optimization for deployment
- **Cross-compilation**: Linux, macOS, Windows; x86_64, ARM targets
- **Cargo Integration**: Full Rust ecosystem support and toolchain integration

[Full feature breakdown →](./docs/features.md)

## Quick Start

### Installation

See [docs/installation.md](docs/installation.md) for detailed setup.

Requirements:

- **Rust 1.70+** - [Install](https://rustup.rs/)
- **just** - `cargo install just` (or `brew install just`)

### Build & Run

```bash
# Clone
git clone https://github.com/anthropics/typedialog.git
cd typedialog

# Build
just build::default

# Test
just test::all

# Run example
cargo run --example form

# Run with defaults pre-loaded
typedialog form config.ncl --defaults defaults.json
```text

## Unified Command Interface

All backends are accessible through the **single `typedialog` command** with automatic dispatcher:

```bash
# Each backend can be invoked directly via typedialog
typedialog web form config.ncl --port 8080           # Web backend (browser forms)
typedialog tui config.ncl                            # TUI backend (terminal UI)
typedialog ai serve --port 8765                      # AI backend (RAG assistant)
typedialog ag run agent.mdx                          # Agent backend (LLM agents)
typedialog prov-gen generate --spec project.ncl      # Provisioning generator

# Or use specific binaries if you prefer
typedialog-web form config.ncl --port 8080
typedialog-tui config.ncl
typedialog-ai serve --port 8765
typedialog-ag run agent.mdx
typedialog-prov-gen generate --spec project.ncl

# Show help for each backend
typedialog web -h
typedialog tui -h
typedialog ai -h
typedialog ag -h
typedialog prov-gen -h
```text

All backends produce identical JSON output from the same form definition (Nickel or TOML), making it easy to switch between interfaces without changing your data.

## Backends at a Glance

### CLI Backend (inquire)

Interactive terminal prompts for scripting and automation.

```bash
# Simple prompt
typedialog text "Enter your name"

# With options
typedialog select "Choose role" Admin User Guest

# Output as JSON
typedialog text "Email" --format json

# Pre-populate form with defaults
typedialog form schema.ncl --defaults config.json --format json
```text

**Use for:** Scripts, CI/CD pipelines, server tools, piping between tools
**See:** [`examples/04-backends/cli/`](examples/04-backends/cli/)

### TUI Backend (ratatui)

Full terminal UI with keyboard navigation and mouse support.

```bash
# Via dispatcher
typedialog tui config.ncl

# Or run directly
typedialog-tui config.ncl
cargo run -p typedialog-tui --example form_with_autocompletion
```text

**Use for:** Interactive dashboards, system administration tools, complex forms
**See:** [`examples/04-backends/tui/`](examples/04-backends/tui/)

### Web Backend (axum)

HTTP server with browser-based forms.

```bash
# Via dispatcher
typedialog web form config.ncl --port 8080

# Or run directly
typedialog-web form config.ncl --port 8080
cargo run -p typedialog-web -- --config config/web/dev.ncl
# Open http://localhost:8080
```text

**Use for:** SaaS platforms, public forms, mobile-friendly interfaces
**See:** [`examples/04-backends/web/`](examples/04-backends/web/)

### AI Backend (typedialog-ai)

Retrieval-Augmented Generation (RAG) system with semantic search and embeddings.

```bash
# Via dispatcher
typedialog ai serve --port 8765

# Or run directly
typedialog-ai serve --port 8765

# Query knowledge base
typedialog-ai --config config/ai/dev.ncl --query "How do I configure encryption?"

# Build knowledge graph
typedialog-ai --config config/ai/production.ncl --build-graph ./docs
```text

**Use for:** Documentation search, context-aware assistance, knowledge retrieval, semantic search
**Features:**

- Multi-provider embeddings (OpenAI, Ollama)
- Vector store (in-memory, Redis)
- Knowledge graph generation
- Context retrieval for LLMs

**Learn more:** [AI Backend Documentation](docs/ai/)

**Complete backend guide:** [Backend-Specific Examples](examples/04-backends/)

## TypeDialog Agent (typedialog-ag)

**AI agent execution from markdown files** with multi-provider LLM support.

Execute AI agents defined as `.agent.mdx` files with template variables, file imports, shell integration, and output validation.

### Quick Start

```bash
# Via dispatcher
typedialog ag run agent.mdx

# Or run directly
typedialog-ag run agent.mdx

# For more options
typedialog ag -h
```text

### Quick Example

Create `hello.agent.mdx`:

```yaml
---
@agent {
  role: friendly assistant,
  llm: claude-3-5-haiku-20241022
}

@input name: String
---

Say hello to {{name}} in a warm and friendly way!
```text

Run it:

```bash
typedialog-ag hello.agent.mdx
# Prompts: name (String): Alice
# Output: Hello Alice! It's wonderful to meet you! ...
```text

### Supported LLM Providers

| Provider   | Models                           | Best For                  | Privacy           |
| ---------- | -------------------------------- | ------------------------- | ----------------- |
| **Claude** | Haiku, Sonnet, Opus              | Code, reasoning, analysis | Cloud             |
| **OpenAI** | GPT-4o, GPT-4o-mini, o1, o3      | Code, general tasks       | Cloud             |
| **Gemini** | 2.0 Flash, 1.5 Pro               | Creative, multi-modal     | Cloud (free tier) |
| **Ollama** | llama2, mistral, codellama, etc. | Privacy, offline, free    | Local             |

### Features

- **Template System**: Variables (`{{var}}`), conditionals (`{% if %}`), file imports (`@import`) - Tera/Jinja2
- **Context Injection**: Load files with glob patterns, execute shell commands
- **Output Validation**: Format, content, and length validation
- **Streaming**: Real-time token-by-token responses
- **Multi-Provider**: Switch between Claude, OpenAI, Gemini, or local Ollama

### Examples

```bash
# Code review with Claude Sonnet
typedialog-ag examples/12-agent-execution/code-review.agent.mdx

# Creative writing with Gemini
typedialog-ag examples/12-agent-execution/creative-writer.agent.mdx

# Privacy-first analysis with Ollama (local)
typedialog-ag examples/12-agent-execution/local-privacy.agent.mdx
```text

**Learn more:**

- [Agent Documentation](docs/agent/) - Complete guide
- [Getting Started](docs/agent/getting_started.md) - Installation and first agent
- [LLM Providers](docs/agent/llm_providers.md) - Provider comparison
- [Examples](examples/12-agent-execution/) - 8 practical use cases

## Provisioning Generator (typedialog-prov-gen)

**Infrastructure as Code generation** from TypeDialog forms with multi-cloud support.

Generate infrastructure configurations for AWS, GCP, Azure, Hetzner, UpCloud, and LXD from interactive forms or declarative specifications.

### Provisioning Example

```bash
# Generate infrastructure with interactive prompts
typedialog-prov-gen --name myproject --output ./provisioning

# Use specific providers
typedialog-prov-gen --name myproject --providers aws,hetzner --ai-assist

# Dry run (preview without generating)
typedialog-prov-gen --name myproject --dry-run
```text

### Provisioning Features

- **Multi-Cloud Support**: AWS, GCP, Azure, Hetzner, UpCloud, LXD
- **7-Layer Validation**: Forms → Constraints → Values → Validators → Schemas → Defaults → JSON
- **Nickel Integration**: Type-safe configuration contracts with schema validation
- **AI-Assisted Generation**: Optional Claude/Ollama assistance for complex configurations
- **Template Fragments**: Reusable provider-specific configuration blocks
- **Environment Profiles**: Development, staging, production presets

### Supported Providers

| Provider    | Type            | Best For                                                    |
| ----------- | --------------- | ----------------------------------------------------------- |
| **AWS**     | Cloud           | Enterprise, scalability, full service catalog               |
| **GCP**     | Cloud           | Data analytics, ML workloads                                |
| **Azure**   | Cloud           | Enterprise integration, hybrid cloud, Microsoft ecosystem   |
| **Hetzner** | Cloud/Dedicated | Cost-effective European hosting                             |
| **UpCloud** | Cloud           | High-performance SSD, flexible pricing                      |
| **LXD**     | Local/Private   | Development, on-premise, containers                         |

**Learn more:**

- [Prov-gen Documentation](docs/prov-gen/) - Complete guide
- [Examples](examples/11-prov-gen/) - Multi-cloud configurations
- [Templates](crates/typedialog-prov-gen/templates/) - Provider fragments

## Nickel Integration

**Type-safe configuration management** with bidirectional Nickel schema support.

Generate interactive forms from Nickel schemas, collect user input, and produce validated configuration output:

```bash
# 1. Define form directly in Nickel
typedialog form config.ncl --backend tui

# 2. Get validated output in any format
# JSON, YAML, TOML, or back to Nickel with type preservation
```text

**Benefits:**

- Schema validation before/after collection
- Type contracts enforced throughout pipeline
- Documentation embedded in schemas
- Deterministic configuration generation

**Learn more:**

- [Nickel Integration Guide](docs/configuration.md#nickel-integration)
- [Examples: 06-integrations/nickel/](examples/06-integrations/nickel/)
- [Nickel Lang Documentation](https://nickel-lang.org/)

## Documentation

Complete documentation in [`docs/`](docs/):

| Document                                          | Purpose                        |
| ------------------------------------------------- | ------------------------------ |
| [**installation.md**](docs/installation.md)       | Prerequisites & setup          |
| [**development.md**](docs/development.md)         | Development workflows          |
| [**build.md**](docs/build.md)                     | Building & cross-compilation   |
| [**release.md**](docs/release.md)                 | Release process                |
| [**configuration.md**](docs/configuration.md)     | Backend & Nickel configuration |

## Project Examples

Complete working examples in [`examples/`](examples/):

| Category              | Path                                               | Contents                                                                           |
| --------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Getting Started**   | [01-basic](examples/01-basic/)                     | Form syntax, sections, validation                                                  |
| **Advanced Features** | [02-advanced](examples/02-advanced/)               | Conditional logic, dynamic fields                                                  |
| **Styling**           | [03-styling](examples/03-styling/)                 | Themes, borders, visual design                                                     |
| **Backends**          | [04-backends](examples/04-backends/)               | CLI, TUI, Web implementations                                                      |
| **Composition**       | [05-fragments](examples/05-fragments/)             | Reusable components                                                                |
| **Integrations**      | [06-integrations](examples/06-integrations/)       | [Nickel](examples/06-integrations/nickel/), [i18n](examples/06-integrations/i18n/) |
| **Production**        | [09-templates](examples/09-templates/)             | Real-world use cases                                                               |
| **Provisioning**      | [11-prov-gen](examples/11-prov-gen/)               | Infrastructure generation, multi-cloud                                             |
| **Agent Execution**   | [12-agent-execution](examples/12-agent-execution/) | LLM agents, AI workflows                                                           |

**Quick start:** [examples/README.md](examples/README.md)

## Development

Use `just` for all development tasks:

```bash
# Show available commands
just --list

# Format, lint, test
just check-all

# Build & package
just distro::build-release
just distro::create-package

# Full CI/CD
just ci::full
```text

See [docs/development.md](docs/development.md) for details.

## Building & Distribution

### Build from Source

```bash
just build::release
```text

Binaries in `target/release/`

### Create Distribution Package

```bash
just distro::build-release
just distro::create-package
just distro::create-checksums
```text

Package includes binaries, configs, and installers.

See [docs/build.md](docs/build.md) for complete guide.

### Install Distributed Release

```bash
# Linux/macOS
curl -fsSL https://github.com/anthropics/typedialog/releases/download/latest/install.sh | bash

# Windows PowerShell
irm https://github.com/anthropics/typedialog/releases/download/latest/install.ps1 | iex
```text

See [docs/release.md](docs/release.md) for release workflow.

## Configuration

Pre-configured settings for each backend and environment:

```text
config/
├── cli/         # default, dev, production
├── tui/         # default, dev, production
├── web/         # default, dev, production
├── ai/          # default, dev, production (RAG/embeddings)
├── ag/          # default, dev, production (Agent/LLM)
└── prov-gen/    # default, dev, production (IaC generation)
```text

See [docs/configuration.md](docs/configuration.md) and [config/README.md](config/README.md) for all options.

## Project Structure

```text
typedialog/
├── crates/
│   ├── typedialog-core/       # Core library (forms, validation)
│   ├── typedialog/            # CLI binary
│   ├── typedialog-tui/        # TUI binary
│   ├── typedialog-web/        # Web binary
│   ├── typedialog-ai/         # AI backend (RAG, embeddings)
│   ├── typedialog-ag-core/    # Agent core library
│   ├── typedialog-ag/         # Agent CLI binary
│   ├── typedialog-ag-server/  # Agent HTTP server
│   └── typedialog-prov-gen/   # Provisioning generator
├── config/                      # Configuration files (6 backends × 3 envs)
├── examples/                    # Working examples (12 categories)
├── scripts/                     # Build automation
├── installers/                  # Installation scripts
├── docs/                        # Documentation
├── justfile                     # Command orchestration
└── Cargo.toml                   # Workspace manifest
```text

## Key Technologies

**Core:**

- **Rust** - Type-safe systems language
- **Nickel** - Type-safe configuration language (schema integration)
- **TOML** - Form and configuration language
- **Fluent** - Multi-language translation system
- **just** - Command orchestration

**Backends:**

- **inquire** - Interactive prompt library (CLI backend)
- **Ratatui** - Terminal UI framework (TUI backend)
- **Axum** - Web framework (Web backend)

**AI & Agent:**

- **Tera** - Template engine (Jinja2-compatible) for agent files
- **Claude API** - Anthropic's language models
- **OpenAI API** - GPT models
- **Gemini API** - Google's language models
- **Ollama** - Local LLM runtime

**Infrastructure:**

- **Nickel contracts** - Type-safe IaC validation
- **AWS/GCP/Hetzner/UpCloud APIs** - Multi-cloud provisioning

## Commands at a Glance

```bash
# Development
just fmt                # Format code
just lint               # Lint code
just test::all          # Run tests
just dev::watch         # Watch & rebuild
just dev::docs          # Generate docs

# Building
just build::default     # Debug build
just build::release     # Release build
just distro::cross      # Cross-compile

# CI/CD
just ci::full           # Complete pipeline
just check-all          # Format + lint + test

# Distribution
just distro::build-release      # Release build
just distro::create-package     # Package
just distro::create-checksums   # Checksums
just distro::package-release    # Prepare release
```text

## System Requirements

### Minimum

- Rust 1.70+
- 4GB RAM
- 2GB disk space

### For Cross-Compilation

- Docker (or cargo-cross)

### Optional Tools

- **Nickel CLI** - For developing type-safe Nickel schemas (used with `06-integrations/nickel/` examples)
- **cargo-watch** - For hot-reload during development
- **cargo-cross** - For cross-compilation to other platforms

See [docs/installation.md](docs/installation.md) for setup.

## License & Compliance

- **Project License**: [MIT](LICENSE)
- **Dependency SBOM (SPDX)**: [SBOM.spdx.json](SBOM.spdx.json) - ISO/IEC 5962:2021
- **Dependency SBOM (CycloneDX)**: [SBOM.cyclonedx.json](SBOM.cyclonedx.json) - ECMA standard
- **Regenerate SBOMs**: `just distro::generate-sbom`

All dependencies are compatible with MIT license. Audit vulnerabilities: `just ci::audit`

## Getting Help

1. **Documentation** - Start with [docs/README.md](docs/)
2. **Examples** - Check [examples/README.md](examples/)
3. **Issues** - Open on [GitHub](https://github.com/anthropics/typedialog/issues)

## Contributing

Contributions welcome! See documentation for setup and guidelines.

---

**Ready to get started?** → [docs/installation.md](docs/installation.md)