Tutorial 1: Installation¶

This tutorial guides you through installing Mistaber and verifying your setup.

Learning Objectives¶

Clone the Mistaber repository
Install Python dependencies including clingo
Verify the installation with a simple query

Prerequisites¶

Python 3.10 or higher
Git
Basic command line familiarity

Estimated Time¶

10 minutes

Steps¶

Step 1: Clone the Repository¶

First, clone the Mistaber repository to your local machine:

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

The repository structure looks like this:

mistaber/
├── mistaber/
│   ├── cli/          # Command-line interface
│   ├── dsl/          # HLL compiler
│   ├── engine/       # Reasoning engine
│   └── ontology/     # Halachic knowledge base
├── docs/             # Documentation
├── examples/         # Example scenarios
└── tests/            # Test suite

Step 2: Create a Virtual Environment¶

It's recommended to use a virtual environment to isolate dependencies:

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

Step 3: Install Dependencies¶

Install the required Python packages:

pip install clingo click

The key dependencies are:

Package	Purpose
`clingo`	Answer Set Programming solver (required)
`click`	CLI framework
`lark`	Parser for HLL DSL (optional, for rule authoring)

Installing Clingo¶

Clingo is the core ASP solver. Install it via pip:

pip install clingo

On some systems, you may need to install additional system packages:

Ubuntu/Debian:

sudo apt-get install gringo
pip install clingo

macOS (Homebrew):

brew install clingo
pip install clingo

Windows: The pip package should work directly on Windows 10/11.

Step 4: Verify Clingo Installation¶

Test that clingo is accessible from Python:

import clingo
print(f"Clingo version: {clingo.__version__}")

You should see output like:

Clingo version: 5.6.2

Step 5: Verify the Engine¶

Test that the HSRS engine loads correctly:

from pathlib import Path
from mistaber.engine import HsrsEngine

# Initialize the engine with the ontology
engine = HsrsEngine(Path("mistaber/ontology"))

# Check that it loaded
print(f"Engine loaded: {engine.is_loaded}")

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

Expected output:

Engine loaded: True
Available worlds: ['base', 'mechaber', 'rema', 'gra', 'ashk_mb', 'ashk_ah', 'sefardi_yo']

Step 6: Test a Simple Query¶

Run your first halachic query to verify everything works:

from pathlib import Path
from mistaber.engine import HsrsEngine

engine = HsrsEngine(Path("mistaber/ontology"))

# Ask a simple yes/no question
print("Is 'base' a world?", engine.ask("world(base)"))
print("Is 'mechaber' a world?", engine.ask("world(mechaber)"))

# Query with pattern matching
accessible = engine.query("accessible(X, base)")
print(f"Worlds inheriting from base: {[r['X'] for r in accessible]}")

Expected output:

Is 'base' a world? True
Is 'mechaber' a world? True
Worlds inheriting from base: ['mechaber', 'rema', 'gra']

Step 7: Run the Test Suite (Optional)¶

To ensure your installation is complete, run the test suite:

pip install pytest
pytest tests/ -v --ignore=tests/integration

You should see all tests passing:

tests/engine/test_engine.py::test_engine_loads PASSED
tests/engine/test_worlds.py::test_all_worlds_exist PASSED
...

Troubleshooting¶

"ModuleNotFoundError: No module named 'clingo'"¶

Ensure clingo is installed in your active virtual environment:

pip install clingo

"ImportError: libclingo.so not found"¶

On Linux, you may need to install the system gringo package first:

sudo apt-get install gringo
pip install --force-reinstall clingo

"FileNotFoundError: mistaber/ontology"¶

Make sure you're running commands from the repository root directory:

cd /path/to/mistaber
python -c "from mistaber.engine import HsrsEngine; print('OK')"

Slow Performance¶

For large queries, ensure you have sufficient memory (2GB+ recommended). The solver can be memory-intensive for complex scenarios.

What You've Learned¶

How to clone and set up the Mistaber repository
How to install clingo and other dependencies
How to verify the installation with basic queries
How to run the test suite

Next Steps¶

Continue to Tutorial 2: Your First Query to learn how to use Mistaber for halachic reasoning.

Quick Reference¶

# Installation commands
git clone https://github.com/your-org/mistaber.git
cd mistaber
python -m venv venv
source venv/bin/activate
pip install clingo click

# Verification
python -c "from mistaber.engine import HsrsEngine; print('OK')"