TypeDialog Logo
[![CI](https://github.com/jesusperezlorenzo/typedialog/actions/workflows/ci.yml/badge.svg)](https://github.com/jesusperezlorenzo/typedialog/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/jesusperezlorenzo/typedialog/branch/main/graph/badge.svg)](https://codecov.io/gh/jesusperezlorenzo/typedialog) # TypeDialog > ▲ Create Type-Safe Interactive Dialogs. > Prompts, forms, schemas definition, use backends (CLI, TUI, Web, AI). > Extend with LLM agents, IaC generation, and [Nickel](https://nickel-lang.org) validation. ## Features - **8 Prompt Types**: text, confirm, select, multi-select, password, custom, editor, date - **Declarative Forms**: TOML-based UI definitions with fragments & composition - **Dynamic Logic**: Conditional fields, smart defaults, real-time validation - **Multi-Language Support**: Fluent (.ftl) translations with automatic locale detection - **Multiple Output Formats**: JSON, YAML, TOML, and Nickel output - **Zero Runtime Dependencies**: Core library runs anywhere, no external tools required - **6 Backends**: CLI (inquire), TUI (ratatui), Web (axum), AI (RAG/embeddings), Agent (LLM execution), Prov-gen (IaC generation) ### Integration Key - **Type-Safe Schemas**: Bidirectional [Nickel](https://nickel-lang.org) integration to manage configurations and settings files.
It requires [Nickel CLI](https://nickel-lang.org/getting-started/) ## 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 ``` ## 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 ``` **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 cargo run -p typedialog-tui --example form_with_autocompletion ``` **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 cargo run -p typedialog-web -- --config config/web/dev.toml # Open http://localhost:3000 ``` **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 # Query knowledge base typedialog-ai --config config/ai/dev.toml --query "How do I configure encryption?" # Build knowledge graph typedialog-ai --config config/ai/production.toml --build-graph ./docs ``` **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 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! ``` Run it: ```bash typedialog-ag hello.agent.mdx # Prompts: name (String): Alice # Output: Hello Alice! It's wonderful to meet you! ... ``` ### 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 ``` **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. ### Quick 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 ``` ### 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 schema in Nickel nickel eval config.ncl > schema.toml # 2. Run interactive form typedialog form schema.toml --backend tui # 3. Get validated output in any format # JSON, YAML, TOML, or back to Nickel with type preservation ``` **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 | ## 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 ``` See [docs/development.md](docs/development.md) for details. ## Building & Distribution ### Build from Source ```bash just build::release ``` Binaries in `target/release/` ### Create Distribution Package ```bash just distro::build-release just distro::create-package just distro::create-checksums ``` 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 ``` See [docs/release.md](docs/release.md) for release workflow. ## Configuration Pre-configured settings for each backend and environment: ``` 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) ``` See [docs/configuration.md](docs/configuration.md) and [config/README.md](config/README.md) for all options. ## Project Structure ``` 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 ``` ## 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 ``` ## 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)