480 lines
15 KiB
Markdown
480 lines
15 KiB
Markdown
<div align="center">
|
||
<img src="assets/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
|
||
</div>
|
||
|
||
|
||
|
||
# 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**: TOML-based definitions with fragments & composition
|
||
- **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
|
||
```
|
||
|
||
## 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)
|