Metadata-Version: 2.4
Name: ddss
Version: 0.0.26
Summary: Distributed Deductive System Sorts
Author-email: Hao Zhang <hzhangxyz@outlook.com>
License-Expression: AGPL-3.0-or-later
Project-URL: Repository, https://github.com/USTC-KnowledgeComputingLab/ddss.git
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: apyds~=0.0.11
Requires-Dist: apyds-bnf~=0.0.11
Requires-Dist: apyds-egg~=0.0.11
Requires-Dist: prompt-toolkit~=3.0.52
Requires-Dist: sqlalchemy[aiomysql,aiosqlite,postgresql-asyncpg]~=2.0.45
Requires-Dist: tyro~=1.0.3
Provides-Extra: dev
Requires-Dist: pytest~=9.0.2; extra == "dev"
Requires-Dist: pytest-asyncio~=1.3.0; extra == "dev"
Requires-Dist: pytest-cov~=7.0.0; extra == "dev"
Requires-Dist: ruff~=0.14.10; extra == "dev"
Dynamic: license-file

# Distributed Deductive System Sorts (DDSS)

DDSS is a distributed deductive system with a scalable architecture. It currently supports distributed engines including forward-chaining, E-graph, and more.

## Design Philosophy

DDSS adopts a modular architecture that decomposes the deductive system into independent but collaborative sub-systems:

1. **Separation of Concerns**: Each module focuses on a specific reasoning task
2. **Concurrent Execution**: All modules collaborate asynchronously through a shared database, fully utilizing system resources
3. **Persistent Storage**: Uses a database to store facts and ideas, ensuring data consistency

The system uses a database as the central hub, with two tables (`facts` and `ideas`) for interaction between sub-systems:

- **Eager engines** (e.g., forward-chaining): Read facts and eagerly produce new facts. They also add ideas to broadcast "I want this XXX" - indicating what new facts they need to produce more results.

- **Lazy engines** (e.g., E-graph): Could produce too many facts if eager, so they quietly accept facts without producing many. They only produce facts when they see ideas from other engines that they can (partially) fulfill.

## Modules

- **Input** (`ddss/input.py`): Interactive input interface with BNF syntax parsing
- **Output** (`ddss/output.py`): Real-time display of facts and ideas from the database
- **Load** (`ddss/load.py`): Batch import of facts from standard input
- **Dump** (`ddss/dump.py`): Export all facts and ideas to output
- **DS** (`ddss/ds.py`): Forward-chaining deductive search engine
- **Egg** (`ddss/egg.py`): E-graph based equality reasoning engine

## Installation

### Using uvx (Recommended)

The simplest way is to run with `uvx`:

```bash
uvx ddss
```

This automatically installs all dependencies and starts the DDSS system.

### Using pip

```bash
pip install ddss
ddss
```

## Usage

### Basic Usage

Run DDSS with a temporary SQLite database:

```bash
ddss
```

### Specifying a Database

DDSS supports multiple database backends using the `-a` or `--addr` option:

```bash
# SQLite (persistent)
ddss --addr sqlite:///path/to/database.db

# MySQL
ddss --addr mysql://user:password@host:port/database

# MariaDB
ddss --addr mariadb://user:password@host:port/database

# PostgreSQL
ddss --addr postgresql://user:password@host:port/database
```

### Selecting Components

By default, DDSS runs with all interactive components (`input`, `output`, `ds`, `egg`). You can select specific components using the `-c` or `--component` option:

```bash
# Run only input and output (no inference engines)
ddss --component input output

# Run with only the forward-chaining engine
ddss --component input output ds

# Run with only the E-graph engine
ddss --component input output egg
```

Available components:
- `input`: Interactive input interface
- `output`: Real-time display of facts and ideas
- `ds`: Forward-chaining deductive search engine
- `egg`: E-graph based equality reasoning engine
- `load`: Batch import facts from standard input
- `dump`: Export all facts and ideas to output

### Interactive Usage

After starting, input facts and rules at the `input:` prompt. The syntax follows the format `premise => conclusion`:

**Example 1: Simple Inference**

Input a fact stating `a` is true:
```
input: => a
```

Input a rule stating if `a` then `b`:
```
input: a => b
```

The system automatically derives and displays `=> b`:
```
fact: => b
```

**Example 2: Equality Reasoning**

Input an equality relation `a == b`:
```
input: => a == b
```

Input an idea for `b == a` by creating a rule that requires it:
```
input: b == a => target
```

The system will derive both the idea and facts:
```
idea: => b == a
fact: => b == a
fact: => target
```

## License

This project is licensed under the GNU Affero General Public License v3.0 or later. See [LICENSE.md](LICENSE.md) for details.

## Links

- GitHub: https://github.com/USTC-KnowledgeComputingLab/ddss
