Skip to content

Python API Reference

This page documents the Python API for the apyds package.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from apyds import (
    buffer_size,
    scoped_buffer_size,
    String,
    Variable,
    Item,
    List,
    Term,
    Rule,
    Search,
)

buffer_size

Gets the current buffer size, or sets a new buffer size and returns the previous value.

1
def buffer_size(size: int = 0) -> int

Parameters:

  • size (optional): The new buffer size to set. If 0 (default), returns current size without modification.

Returns: The previous buffer size value.

Example:

1
2
current_size = buffer_size()       # Get current size
old_size = buffer_size(2048)       # Set new size, returns old size

scoped_buffer_size

Context manager for temporarily changing the buffer size.

1
2
@contextmanager
def scoped_buffer_size(size: int = 0)

Parameters:

  • size: The temporary buffer size to set.

Example:

1
2
3
4
with scoped_buffer_size(4096):
    # Operations here use buffer size of 4096
    pass
# Buffer size is restored to previous value

String

Wrapper class for deductive system strings.

Constructor

1
def __init__(self, value: String | str | bytes, size: int | None = None)

Parameters:

  • value: Initial value (string, bytes, or another String)
  • size (optional): Buffer capacity for internal storage

Methods

__str__()

Convert the value to a string representation.

1
def __str__(self) -> str

data()

Get the binary representation of the value.

1
def data(self) -> bytes

size()

Get the size of the data in bytes.

1
def size(self) -> int

Example:

1
2
3
str1 = String("hello")
str2 = String(str1.data())  # From binary
print(str1)  # "hello"

Variable

Wrapper class for logical variables in the deductive system.

Constructor

1
def __init__(self, value: Variable | str | bytes, size: int | None = None)

Parameters:

  • value: Initial value (string starting with backtick, bytes, or another Variable)
  • size (optional): Buffer capacity for internal storage

Properties

name

Get the name of this variable (without the backtick prefix).

1
2
@property
def name(self) -> String

Example:

1
2
3
var1 = Variable("`X")
print(var1.name)  # "X"
print(var1)       # "`X"

Item

Wrapper class for items (constants/functors) in the deductive system.

Constructor

1
def __init__(self, value: Item | str | bytes, size: int | None = None)

Properties

name

Get the name of this item.

1
2
@property
def name(self) -> String

Example:

1
2
item = Item("atom")
print(item.name)  # "atom"

List

Wrapper class for lists in the deductive system.

Constructor

1
def __init__(self, value: List | str | bytes, size: int | None = None)

Methods

__len__()

Get the number of elements in the list.

1
def __len__(self) -> int

__getitem__()

Get an element from the list by index.

1
def __getitem__(self, index: int) -> Term

Example:

1
2
3
lst = List("(a b c)")
print(len(lst))   # 3
print(lst[0])     # "a"

Term

Wrapper class for logical terms in the deductive system. A term can be a variable, item, or list.

Constructor

1
def __init__(self, value: Term | str | bytes, size: int | None = None)

Properties

term

Extracts the underlying term and returns it as its concrete type.

1
2
@property
def term(self) -> Variable | Item | List

Methods

ground()

Ground this term using a dictionary to substitute variables with values.

1
def ground(self, other: Term, scope: str | None = None) -> Term | None

Parameters:

  • other: A term representing a dictionary (list of pairs)
  • scope (optional): Scope string for variable scoping

Returns: The grounded term, or None if grounding fails.

Example:

1
2
3
4
5
a = Term("`a")
dict = Term("((`a b))")
result = a.ground(dict)
if result is not None:
    print(result)  # "b"

__matmul__() / match

Match two terms and return the unification result as a dictionary.

1
def __matmul__(self, other: Term) -> Term | None

Parameters:

  • other: The term to match with this term

Returns: A term representing the unification dictionary (list of tuples), or None if matching fails.

Example:

1
2
3
4
5
a = Term("`a")
b = Term("b")
result = a @ b
if result is not None:
    print(result)  # "((1 2 `a b))"

rename()

Rename all variables in this term by adding prefix and suffix.

1
def rename(self, prefix_and_suffix: Term) -> Term | None

Parameters:

  • prefix_and_suffix: A term with format ((prefix) (suffix))

Returns: The renamed term, or None if renaming fails.

Example:

1
2
3
4
5
term = Term("`x")
spec = Term("((pre_) (_suf))")
result = term.rename(spec)
if result is not None:
    print(result)  # "`pre_x_suf"

Rule

Wrapper class for logical rules in the deductive system.

Constructor

1
def __init__(self, value: Rule | str | bytes, size: int | None = None)

Properties

conclusion

Get the conclusion of the rule.

1
2
@property
def conclusion(self) -> Term

Methods

__len__()

Get the number of premises in the rule.

1
def __len__(self) -> int

__getitem__()

Get a premise term by index.

1
def __getitem__(self, index: int) -> Term

ground()

Ground this rule using a dictionary.

1
def ground(self, other: Rule, scope: str | None = None) -> Rule | None

__matmul__() / match

Match this rule with another rule using unification.

1
def __matmul__(self, other: Rule) -> Rule | None

Parameters:

  • other: The rule to match against (must be a fact without premises)

Returns: The matched rule, or None if matching fails.

Example:

1
2
3
4
5
6
mp = Rule("(`p -> `q)\n`p\n`q\n")
pq = Rule("((! (! `x)) -> `x)")
result = mp @ pq
if result is not None:
    print(result)
    # "(! (! `x))\n----------\n`x\n"

rename()

Rename all variables in this rule.

1
def rename(self, prefix_and_suffix: Rule) -> Rule | None

Search engine for the deductive system.

Constructor

1
def __init__(self, limit_size: int = 1000, buffer_size: int = 10000)

Parameters:

  • limit_size (optional): Size of the buffer for storing rules/facts (default: 1000)
  • buffer_size (optional): Size of the buffer for internal operations (default: 10000)

Methods

set_limit_size()

Set the size of the buffer for storing final objects.

1
def set_limit_size(self, limit_size: int) -> None

set_buffer_size()

Set the buffer size for internal operations.

1
def set_buffer_size(self, buffer_size: int) -> None

reset()

Reset the search engine, clearing all rules and facts.

1
def reset(self) -> None

add()

Add a rule or fact to the knowledge base.

1
def add(self, text: str) -> bool

Returns: True if successfully added, False otherwise.

execute()

Execute the search engine with a callback for each inferred rule.

1
def execute(self, callback: Callable[[Rule], bool]) -> int

Parameters:

  • callback: Function called for each candidate rule. Return False to continue, True to stop.

Returns: The number of rules processed.

Example:

1
2
3
4
5
6
7
8
9
search = Search(1000, 10000)
search.add("(`P -> `Q) `P `Q")
search.add("(! (! X))")

def callback(candidate):
    print(candidate)
    return False  # Continue searching

search.execute(callback)

Complete Example

Here's a complete example demonstrating most of the API:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
import apyds

# Configure buffer size for operations
apyds.buffer_size(2048)

# Create terms
var = apyds.Variable("`X")
item = apyds.Item("hello")
lst = apyds.List("(a b c)")
term = apyds.Term("(f `x `y)")

print(f"Variable: {var}, name: {var.name}")
print(f"Item: {item}, name: {item.name}")
print(f"List: {lst}, length: {len(lst)}")
print(f"Term: {term}, type: {type(term.term)}")

# Work with rules
fact = apyds.Rule("(parent john mary)")
rule = apyds.Rule("(father `X `Y)\n----------\n(parent `X `Y)\n")

print(f"\nFact: {fact}")
print(f"Rule premises: {len(rule)}, conclusion: {rule.conclusion}")

# Grounding
term_a = apyds.Term("`a")
dictionary = apyds.Term("((`a hello))")
grounded = term_a // dictionary
print(f"\nGrounding `a with ((` hello)): {grounded}")

# Matching
mp = apyds.Rule("(`p -> `q)\n`p\n`q\n")
axiom = apyds.Rule("((A) -> B)")
matched = mp @ axiom
print(f"\nMatching modus ponens with (A -> B):\n{matched}")

# Search engine
search = apyds.Search(1000, 10000)
search.add("p q")  # p implies q
search.add("q r")  # q implies r
search.add("p")    # fact: p

print("\nRunning inference:")
for i in range(3):
    count = search.execute(lambda r: print(f"  Derived: {r}") or False)
    if count == 0:
        break

# Using context manager for buffer size
with apyds.scoped_buffer_size(4096):
    big_term = apyds.Term("(a b c d e f g h i j)")
    print(f"\nBig term: {big_term}")