# PDSL Quickstart Guide
Get started with Probabilistic DSL in 5 minutes!
## Installation
```bash
npm install logic-thinking-mcp
```
## Your First PDSL Program
Let's model a simple coin flip:
```pdsl
# coin_flip.pdsl
probabilistic_model CoinFlip {
# Fair coin
0.5 :: heads
0.5 :: tails
# Query: What's the probability of heads?
query heads
}
```
Run it:
```bash
logic-thinking probabilistic coin_flip.pdsl
```
Output:
```
heads: 0.5 (50.0%)
```
## Five-Minute Tour
### 1. Probabilistic Facts (30 seconds)
Express uncertain facts with probabilities:
```pdsl
probabilistic_model Weather {
# Simple probability
0.3 :: rain
# Multiple outcomes (annotated disjunction)
0.5 :: temp(cold); 0.3 :: temp(mild); 0.2 :: temp(hot)
query rain
query temp(cold)
}
```
**Natural Language → PDSL:**
- "30% chance of rain" → `0.3 :: rain`
- "50% cold, 30% mild, 20% hot" → `0.5 :: temp(cold); 0.3 :: temp(mild); 0.2 :: temp(hot)`
### 2. Rules and Conditions (1 minute)
Model conditional probabilities:
```pdsl
probabilistic_model BirdFlight {
# Base facts
bird(sparrow)
bird(penguin)
penguin(penguin)
# Conditional rule: 90% of birds fly (if not penguin)
0.9 :: flies(X) :- bird(X), not penguin(X)
# Penguins don't fly
0.0 :: flies(X) :- penguin(X)
query flies(sparrow)
query flies(penguin)
}
```
**Natural Language → PDSL:**
- "Birds usually fly" → `0.9 :: flies(X) :- bird(X)`
- "Unless it's a penguin" → `not penguin(X)`
### 3. Evidence and Inference (1 minute)
Add observations to update beliefs:
```pdsl
probabilistic_model MedicalDiagnosis {
# Prior probabilities
0.01 :: flu
0.001 :: covid
# Symptom probabilities
0.9 :: fever :- flu
0.95 :: fever :- covid
0.1 :: fever # Background rate
# We observed fever
observe fever
# What's P(flu | fever)?
query flu
query covid
}
```
**Natural Language → PDSL:**
- "Patient has fever" → `observe fever`
- "What's the chance of flu?" → `query flu`
Output with Bayes' theorem:
```
flu: 0.087 (8.7%) # Updated from 1%
covid: 0.009 (0.9%) # Updated from 0.1%
```
### 4. Variables and Predicates (1 minute)
Use logical variables for generalization:
```pdsl
probabilistic_model SocialNetwork {
# Facts
person(alice)
person(bob)
person(carol)
# Friendship probabilities
0.3 :: friends(alice, bob)
0.4 :: friends(bob, carol)
0.2 :: friends(alice, carol)
# Transitive friendships
0.7 :: connected(X, Y) :- friends(X, Y)
0.5 :: connected(X, Z) :- friends(X, Y), friends(Y, Z)
query connected(alice, carol)
}
```
**Natural Language → PDSL:**
- "Alice and Bob are friends (30% sure)" → `0.3 :: friends(alice, bob)`
- "Friends of friends are connected (50%)" → `0.5 :: connected(X, Z) :- friends(X, Y), friends(Y, Z)`
### 5. Complex Reasoning (1.5 minutes)
Combine everything for real-world problems:
```pdsl
probabilistic_model NetworkReliability {
# Component reliability
0.95 :: up(server1)
0.98 :: up(server2)
0.90 :: up(router1)
# System availability rules
0.99 :: service_available :- up(server1), up(router1)
0.99 :: service_available :- up(server2), up(router1)
# Cascade failure
0.8 :: up(router1) :- not up(server1), not up(server2)
# Evidence: server1 is down
observe not up(server1)
# What's P(service available)?
query service_available
query up(router1)
}
```
## Common Patterns
### Pattern 1: Noisy-OR Model
```pdsl
# Multiple causes for an effect
0.7 :: alarm :- burglar
0.6 :: alarm :- earthquake
0.01 :: alarm # False alarm rate
```
### Pattern 2: Bayesian Network
```pdsl
probabilistic_model BayesNet {
# Structure: A → B → C
0.3 :: a
0.8 :: b :- a
0.1 :: b :- not a
0.9 :: c :- b
0.2 :: c :- not b
observe c
query a # Backward inference
}
```
### Pattern 3: Annotated Disjunctions
```pdsl
# Mutually exclusive outcomes
0.4 :: traffic(light); 0.4 :: traffic(moderate); 0.2 :: traffic(heavy)
# Travel time depends on traffic
15.0 :: travel_time(15) :- traffic(light)
30.0 :: travel_time(30) :- traffic(moderate)
60.0 :: travel_time(60) :- traffic(heavy)
```
### Pattern 4: Parameter Learning
```pdsl
probabilistic_model LearnFromData {
# Learnable probabilities
p1 :: disease(X) :- symptom1(X)
p2 :: disease(X) :- symptom2(X)
# Learn from data
learn parameters from dataset("medical_data.csv")
query disease(patient123)
}
```
## Quick Reference Card
| Construct | Syntax | Example |
|-----------|--------|---------|
| Probabilistic fact | `P :: fact` | `0.7 :: sunny` |
| Rule | `P :: head :- body` | `0.9 :: flies(X) :- bird(X)` |
| Annotated disjunction | `P1 :: opt1; P2 :: opt2` | `0.3 :: low; 0.7 :: high` |
| Observation | `observe fact` | `observe fever` |
| Query | `query fact` | `query disease` |
| Negation | `not fact` | `not penguin(X)` |
| Conjunction | `,` | `bird(X), flies(X)` |
| Disjunction | `;` | `bird(X); bat(X)` |
| Variable | Uppercase | `X, Y, Person` |
| Constant | Lowercase | `alice, flu, 42` |
| Comment | `#` | `# This is a comment` |
## PDSL vs ProbLog
PDSL compiles to ProbLog but adds:
1. **Model declarations** - Named, scoped models
2. **Type checking** - Probability validation at parse time
3. **Better syntax** - More readable queries and observations
4. **Error messages** - Clear, actionable feedback
### PDSL
```pdsl
probabilistic_model Example {
0.3 :: rain
observe cloudy
query rain
}
```
### Equivalent ProbLog
```prolog
0.3::rain.
evidence(cloudy, true).
query(rain).
```
## Next Steps
1. **Try more examples**: See [PROBABILISTIC_DSL_EXAMPLES.md](PROBABILISTIC_DSL_EXAMPLES.md)
2. **Learn the full syntax**: Read [PROBABILISTIC_DSL_SPECIFICATION.md](PROBABILISTIC_DSL_SPECIFICATION.md)
3. **Understand translation**: Check [PROBABILISTIC_DSL_PROBLOG_TRANSLATION.md](PROBABILISTIC_DSL_PROBLOG_TRANSLATION.md)
## Tips for Success
1. **Start simple** - Begin with basic facts and queries
2. **Validate probabilities** - Ensure annotated disjunctions sum to 1.0
3. **Test incrementally** - Add observations one at a time
4. **Use descriptive names** - `fever` not `f`, `disease(flu)` not `d(1)`
5. **Comment your models** - Explain probability choices
## Common Mistakes to Avoid
❌ **Don't**: Forget probability bounds
```pdsl
1.5 :: impossible # Error: P > 1.0
```
✅ **Do**: Keep probabilities in [0, 1]
```pdsl
0.5 :: possible
```
❌ **Don't**: Inconsistent annotated disjunctions
```pdsl
0.5 :: a; 0.6 :: b # Error: sum = 1.1 > 1.0
```
✅ **Do**: Ensure sum ≤ 1.0
```pdsl
0.5 :: a; 0.5 :: b
```
❌ **Don't**: Mix variables and constants
```pdsl
0.7 :: Flies(bird) # Confusing: is Flies a var or pred?
```
✅ **Do**: Use clear naming
```pdsl
0.7 :: flies(X) :- bird(X)
```
## Getting Help
- **Syntax errors**: See [PROBABILISTIC_DSL_SPECIFICATION.md](PROBABILISTIC_DSL_SPECIFICATION.md)
- **Parser design**: See [PROBABILISTIC_DSL_PARSER_DESIGN.md](PROBABILISTIC_DSL_PARSER_DESIGN.md)
- **Translation issues**: See [PROBABILISTIC_DSL_PROBLOG_TRANSLATION.md](PROBABILISTIC_DSL_PROBLOG_TRANSLATION.md)
---
**You're ready to start!** Try modifying the examples or create your own probabilistic models. Happy reasoning! 🎲
