Quick Start Guide¶

Get up and running with Mistaber in 5 minutes.

Prerequisites¶

Before you begin, ensure you have:

Python 3.9+ installed
pip package manager
Git for cloning the repository

Installation¶

1. Clone the Repository¶

git clone https://github.com/your-org/mistaber.git
cd mistaber

2. Create a Virtual Environment (Recommended)¶

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies¶

pip install -e .

This installs: - clingo: Answer Set Programming solver (required) - click: Command-line interface framework - xclingo2: Explanation generation (optional, for explain command)

4. Verify Installation¶

mistaber --help

Expected output:

Usage: mistaber [OPTIONS] COMMAND [ARGS]...

  Mistaber - Computational Halacha Reasoning System CLI.

  A command-line interface for querying and analyzing halachic rulings
  using multi-world Kripke semantics.

Options:
  -o, --ontology PATH      Path to ontology directory.
  -f, --format [text|json] Output format.
  --help                   Show this message and exit.

Commands:
  analyze   Analyze a scenario (push mode).
  compare   Compare query results across multiple worlds.
  explain   Generate an explanation for why an atom holds.
  machloket Find disputes (machloket) between halachic authorities.
  query     Query for atoms matching a pattern.

CLI Example: Your First Query¶

Let's query the available worlds in the system:

Step 1: Query All Worlds¶

mistaber -o ./mistaber/ontology query "world(X)"

Output:

Query: world(X)
=================

[1]
  X: base

[2]
  X: mechaber

[3]
  X: rema

[4]
  X: gra

[5]
  X: ashk_mb

[6]
  X: ashk_ah

[7]
  X: sefardi_yo

Step 2: Query World Accessibility (Inheritance)¶

mistaber -o ./mistaber/ontology query "accessible(X, Y)"

Output:

Query: accessible(X, Y)
========================

[1]
  X: mechaber
  Y: base

[2]
  X: rema
  Y: base

[3]
  X: gra
  Y: base

[4]
  X: ashk_mb
  Y: rema

[5]
  X: ashk_ah
  Y: rema

[6]
  X: ashk_ah
  Y: gra

[7]
  X: sefardi_yo
  Y: mechaber

Step 3: Analyze a Basar Bechalav Scenario¶

Create a scenario file my_scenario.lp:

% Define a mixture of beef and cream
mixture(m1).
contains(m1, beef).
contains(m1, cream).

% Classify the foods
food(beef).
food(cream).
food_type(beef, beheima).
food_type(cream, chalav).

Run the analysis:

mistaber -o ./mistaber/ontology analyze my_scenario.lp --world mechaber

Output (abbreviated):

Analysis Results
================

world: mechaber
scenario: mixture(m1). contains(m1, beef). contains(m1, cream)...

atoms:
  - world(base)
  - world(mechaber)
  - accessible(mechaber, base)
  - is_beheima_chalav_mixture(m1)
  - basar_chalav_madrega(m1, d_oraita)
  - asserts(mechaber, issur(achiila, m1, d_oraita))
  - asserts(mechaber, issur(bishul, m1, d_oraita))
  - asserts(mechaber, issur(hanaah, m1, d_oraita))
  - holds(issur(achiila, m1, d_oraita), mechaber)
  ...

This shows that beef + cream is forbidden d'oraita for eating, cooking, and benefit.

Python API Example¶

For programmatic access, use the HsrsEngine class:

from pathlib import Path
from mistaber.engine import HsrsEngine

# Initialize the engine
engine = HsrsEngine(
    ontology_path=Path("./mistaber/ontology"),
    default_world="base"
)

# Basic query: list all worlds
worlds = engine.query("world(X)")
print("Available worlds:")
for w in worlds:
    print(f"  - {w['X']}")

# Boolean query: does a specific fact hold?
is_world = engine.ask("world(mechaber)")
print(f"\nmechaber is a world: {is_world}")

# Compare across worlds
comparison = engine.compare(
    pattern="safek_policy(W, d_oraita, X)",
    worlds=["base", "gra", "ashk_mb"]
)
print("\nSafek d'oraita policies:")
for world, results in comparison.items():
    for r in results:
        print(f"  {world}: {r.get('X', 'N/A')}")

# Analyze a scenario
scenario = """
mixture(m1).
contains(m1, chicken).
contains(m1, butter).
food(chicken).
food(butter).
food_type(chicken, of).
food_type(butter, chalav).
"""

result = engine.analyze(scenario, world="rema")
print("\nAnalysis for chicken + butter (Rema):")
for atom in result["atoms"]:
    if "issur" in atom or "heter" in atom:
        print(f"  {atom}")

Expected Output:

Available worlds:
  - base
  - mechaber
  - rema
  - gra
  - ashk_mb
  - ashk_ah
  - sefardi_yo

mechaber is a world: True

Safek d'oraita policies:
  base: l_chumra
  gra: l_chumra
  ashk_mb: l_chumra

Analysis for chicken + butter (Rema):
  asserts(rema, issur(achiila, m1, d_rabanan))
  asserts(rema, heter(bishul, m1))
  asserts(rema, heter(hanaah, m1))

Understanding the Output¶

Key Predicates¶

Predicate	Meaning	Example
`world(X)`	X is a halachic tradition	`world(mechaber)`
`accessible(X, Y)`	X inherits from Y	`accessible(ashk_mb, rema)`
`asserts(W, P)`	World W directly asserts P	`asserts(mechaber, issur(...))`
`holds(P, W)`	Proposition P is true in W	`holds(issur(...), rema)`
`issur(A, S, L)`	Action A on subject S is forbidden at level L	`issur(achiila, m1, d_oraita)`
`heter(A, S)`	Action A on subject S is permitted	`heter(bishul, m1)`

Action Types¶

Action	Hebrew	Meaning
`achiila`	אכילה	Eating
`bishul`	בישול	Cooking
`hanaah`	הנאה	Deriving benefit

Normative Levels (Madrega)¶

Level	Hebrew	Strength
`d_oraita`	דאורייתא	Biblical (strongest)
`d_rabanan`	דרבנן	Rabbinic
`minhag`	מנהג	Custom
`chumra`	חומרא	Stringency (weakest)

Common Use Cases¶

Find Disputes (Machloket)¶

mistaber -o ./mistaber/ontology machloket "holds(X, W)" --worlds "mechaber,rema"

Get JSON Output¶

mistaber -o ./mistaber/ontology -f json query "world(X)"

Check Completeness¶

mistaber -o ./mistaber/ontology query "issur(achiila, item, X)" --check-completeness

Next Steps¶

Now that you have Mistaber running:

Learn the concepts: Read What is Mistaber?
Understand the science: Review Scientific Contributions
Learn the vocabulary: Browse the Glossary
Explore the ontology: Look at files in mistaber/ontology/worlds/

Troubleshooting¶

"clingo not found" Error¶

Ensure clingo is installed:

pip install clingo

"Ontology path does not exist" Error¶

Make sure you're running from the project root and the path is correct:

# From project root
mistaber -o ./mistaber/ontology query "world(X)"

No Results Returned¶

Check that your query pattern matches the predicate signature. Use uppercase for variables:

# Correct: X is a variable
mistaber query "world(X)"

# Wrong: x is a constant (will find nothing unless there's literally a world named 'x')
mistaber query "world(x)"