# ASP DSL Documentation Index
**Version:** 1.0.0
**Status:** Phase 3 Complete
**Last Updated:** 2025-10-12
## Overview
The Answer Set Programming Domain-Specific Language (ASP DSL) provides a user-friendly interface for expressing ASP programs that compile directly to valid Clingo syntax. Unlike Phases 1 and 2, the ASP DSL does not translate between languages—it IS valid Clingo syntax, enhanced with natural language support and templates.
## Core Philosophy
**Key Principle:** The ASP DSL outputs valid Clingo syntax that users can copy-paste directly into the Clingo CLI for verification.
- ✅ Valid Clingo syntax (no translation needed)
- ✅ Natural language problem detection
- ✅ Template-based code generation
- ✅ Default logic integration
- ✅ 90%+ LLM generation success rate
## Documentation Structure
### Getting Started
1. **[ASP_DSL_QUICKSTART.md](ASP_DSL_QUICKSTART.md)**
- 5-minute tutorial
- "Hello World" examples
- Common patterns
- Copy-paste-ready code
### Core Reference
2. **[ASP_DSL_SPECIFICATION.md](ASP_DSL_SPECIFICATION.md)**
- Complete language specification
- Syntax rules (Clingo-compatible)
- Type system
- Validation rules
- Error handling
3. **[ASP_DSL_PARSER_DESIGN.md](ASP_DSL_PARSER_DESIGN.md)**
- Parser architecture
- AST structure
- Natural language processing
- Template system design
- Default logic translation
### Examples & Templates
4. **[ASP_DSL_EXAMPLES.md](ASP_DSL_EXAMPLES.md)**
- 30+ comprehensive examples
- Graph problems
- Scheduling
- Configuration
- Puzzles (Sudoku, N-Queens)
- Optimization problems
5. **[ASP_DSL_TEMPLATES.md](ASP_DSL_TEMPLATES.md)**
- Template library (7+ templates)
- Graph coloring
- Hamiltonian path/cycle
- Scheduling
- Configuration
- N-Queens
- Sudoku
- Knapsack
## Quick Links
### By Use Case
**Combinatorial Problems**
→ [Templates](ASP_DSL_TEMPLATES.md#graph-coloring)
→ [Examples](ASP_DSL_EXAMPLES.md#graph-problems)
**Scheduling**
→ [Templates](ASP_DSL_TEMPLATES.md#scheduling)
→ [Examples](ASP_DSL_EXAMPLES.md#scheduling-problems)
**Puzzles**
→ [Templates](ASP_DSL_TEMPLATES.md#sudoku)
→ [Examples](ASP_DSL_EXAMPLES.md#puzzle-problems)
**Optimization**
→ [Specification](ASP_DSL_SPECIFICATION.md#optimization)
→ [Examples](ASP_DSL_EXAMPLES.md#optimization-problems)
### By Learning Path
**New to ASP?**
1. Read [Quickstart](ASP_DSL_QUICKSTART.md)
2. Try [Simple Examples](ASP_DSL_EXAMPLES.md#getting-started)
3. Use [Templates](ASP_DSL_TEMPLATES.md)
**Experienced with ASP?**
1. Check [Specification](ASP_DSL_SPECIFICATION.md) for syntax details
2. Review [Parser Design](ASP_DSL_PARSER_DESIGN.md) for advanced features
3. Explore [Complex Examples](ASP_DSL_EXAMPLES.md#advanced-examples)
**Building with the DSL?**
1. Study [Parser Design](ASP_DSL_PARSER_DESIGN.md)
2. Review [Template System](ASP_DSL_TEMPLATES.md#template-engine)
3. Examine [Natural Language](ASP_DSL_PARSER_DESIGN.md#nl-processing)
## Key Features
### 1. Pure Clingo Syntax
```asp
% This is valid Clingo code!
color(red; blue; green).
1 {assign(X, C) : color(C)} 1 :- vertex(X).
:- assign(X, C), assign(Y, C), edge(X, Y).
#show assign/2.
```
### 2. Natural Language Support
```
Input: "Color a triangle graph with 3 colors"
Output: [Valid Clingo program for graph 3-coloring]
```
### 3. Template System
```typescript
// Apply graph coloring template
const program = applyTemplate('graph_coloring', {
vertices: [1, 2, 3, 4, 5],
edges: [[1,2], [2,3], [3,4], [4,5], [5,1]],
colors: 3
});
```
### 4. Default Logic
```asp
% ADSL syntax (translated to ASP)
typically flies(X) if bird(X) unless penguin(X).
% Compiles to:
flies(X) :- bird(X), not ab_flies(X).
ab_flies(X) :- penguin(X).
```
## Comparison with Other DSLs
| Feature | CSDL (Phase 1) | PDSL (Phase 2) | ASP DSL (Phase 3) |
|---------|----------------|----------------|-------------------|
| **Target** | Z3 (SMT) | ProbLog | Clingo (ASP) |
| **Translation** | Yes | Yes | No (valid Clingo) |
| **Domain** | Constraints | Probabilities | Combinatorial |
| **Output** | SMT-LIB | ProbLog | Clingo ASP |
| **Templates** | No | No | Yes (7+) |
| **NL Support** | Pattern matching | Pattern matching | Problem detection |
## Design Principles
### Principle 1: Valid Clingo First
Every ASP DSL program must be valid Clingo syntax. Users should be able to:
1. Generate program with ASP DSL
2. Copy to file `program.lp`
3. Run `clingo program.lp`
4. Get identical results
### Principle 2: Progressive Enhancement
```
Level 1: Direct Clingo code → Just validate and execute
Level 2: Natural language → Detect problem type and generate
Level 3: Template-based → Fill template with parameters
Level 4: Default logic → Translate ADSL to ASP
```
### Principle 3: Helpful Errors
```
Error: Unsafe variable in rule
Line 5: path(X, Y) :- edge(Y, Z).
^
Variable X appears in head but not in body.
Did you mean: path(Y, Z) :- edge(Y, Z).
```
## Implementation Files
### Source Code (`src/parsers/`)
- `aspLexer.ts` - Tokenizes ASP syntax
- `aspAST.ts` - Abstract syntax tree definitions
- `aspParser.ts` - Parses Clingo syntax
- `aspNaturalLanguage.ts` - Natural language to ASP
- `aspTemplates.ts` - Template library
- `aspDefaultLogic.ts` - Default logic (ADSL) translator
- `aspParser.test.ts` - Comprehensive tests
### Total Implementation
- ~2500 lines of TypeScript
- 7+ problem templates
- 30+ example programs
- 50+ test cases
- Full Clingo syntax support
## Usage Examples
### Example 1: Direct Clingo Code
```typescript
const result = await aspSystem.process('solve', `
vertex(1..5).
edge(1,2). edge(2,3). edge(3,4). edge(4,5). edge(5,1).
color(red; blue; green).
1 {assign(X, C) : color(C)} 1 :- vertex(X).
:- assign(X, C), assign(Y, C), edge(X, Y).
#show assign/2.
`, 'text');
```
### Example 2: Natural Language
```typescript
const result = await aspSystem.process('solve',
'Color a cycle graph with vertices 1-5 using 3 colors',
'text'
);
```
### Example 3: Template-Based
```typescript
const result = await aspSystem.process('solve', {
template: 'graph_coloring',
vertices: [1, 2, 3, 4, 5],
edges: [[1,2], [2,3], [3,4], [4,5], [5,1]],
numColors: 3
}, 'text');
```
## Integration with MCP Server
The ASP DSL integrates as a new logic system:
```json
{
"tool": "logic_reasoning",
"arguments": {
"system": "asp",
"operation": "solve",
"input": "graph coloring problem...",
"format": "text"
}
}
```
## Performance Characteristics
| Problem Size | Grounding Time | Solving Time | Total |
|--------------|----------------|--------------|-------|
| Small (< 10 elements) | < 0.1s | < 0.1s | < 0.2s |
| Medium (10-100) | 0.1-1s | 0.1-0.5s | 0.2-1.5s |
| Large (100-1000) | 1-10s | 0.5-5s | 1.5-15s |
| Very Large (> 1000) | 10s+ | Variable | May timeout |
## Best Practices
### DO ✅
- Use templates for common problems
- Add comments to explain logic
- Use `#show` to control output
- Bound quantifiers with ranges
- Test with small inputs first
### DON'T ❌
- Use unbounded domains
- Create Cartesian products unnecessarily
- Forget safety conditions (unsafe variables)
- Use deep recursion without bounds
- Omit constraint explanations
## Troubleshooting
### Common Issues
**Issue:** UNSATISFIABLE result
**Solution:** Check constraints are not too strict
**Issue:** Grounding takes forever
**Solution:** Reduce domain sizes, use conditional literals
**Issue:** Unsafe variable error
**Solution:** Ensure all head variables appear in positive body literals
**Issue:** Syntax error
**Solution:** Check for missing periods, proper Clingo syntax
## Learning Resources
### Within This Documentation
1. Start: [Quickstart](ASP_DSL_QUICKSTART.md)
2. Practice: [Examples](ASP_DSL_EXAMPLES.md)
3. Reference: [Specification](ASP_DSL_SPECIFICATION.md)
4. Deep Dive: [Parser Design](ASP_DSL_PARSER_DESIGN.md)
### External Resources
- [Potassco Guide](https://github.com/potassco/guide)
- [Clingo Documentation](https://potassco.org/clingo/)
- [ASP-Core-2 Standard](https://www.mat.unical.it/aspcomp2013/ASP-CORE-2.pdf)
- [Teaching ASP](https://teaching.potassco.org/)
## Support & Feedback
For issues, suggestions, or contributions:
- File issues on GitHub
- Contribute examples
- Suggest new templates
- Report bugs
## Version History
**v1.0.0** (2025-10-12) - Initial release
- Full Clingo syntax support
- 7 problem templates
- Natural language processing
- Default logic integration
- 30+ examples
- Comprehensive tests
---
**Next Steps:** Choose your learning path above and dive in!
