aspcompose

Define, group, select, and validate ASP (Answer Set Programming) rule collections. Solver-agnostic: rule text is opaque to the library, so any ASP dialect (clingo, DLV, ...) works. Zero runtime dependencies.

Install

pip install -e .[dev]

Quickstart

A single registry exercising all three composition axes — slots, profiles, and variants — plus a plain depends_on chain:

Group identifiers, slot-filler identifiers, and rule identifiers all use colon-delimited namespaces (base, slot_x:a, consumer:variant_1:r_1) so every string says where it lives:

from aspcompose import Rule, RuleGroup, RuleRegistry, CollectionPlan

# Plain base group: no slot, no profile, no variants.
base = RuleGroup(
    identifier="base",
    rules=(Rule(identifier="base:r_1", text="p(X) :- q(X)."),),
)

# Two interchangeable fillers of slot_x. Each carries a different profile
# so a bulk `add_profile` pulls in exactly one of them.
slot_x_a = RuleGroup(
    identifier="slot_x:a",
    rules=(Rule(identifier="slot_x:a:r_1", text="q(X) :- a(X)."),),
    depends_on=frozenset({"base"}),
    slot="slot_x",
    profiles=frozenset({"profile_a"}),
)
slot_x_b = RuleGroup(
    identifier="slot_x:b",
    rules=(Rule(identifier="slot_x:b:r_1", text="q(X) :- b(X)."),),
    depends_on=frozenset({"base"}),
    slot="slot_x",
    profiles=frozenset({"profile_b"}),
)

# Polymorphic consumer: depends on slot_x (any filler will do), carries
# both profiles so it's included under either, and declares two variants
# that both derive from the shared predicate `r(X)` — so they work the
# same regardless of which slot_x filler is active.
consumer = RuleGroup(
    identifier="consumer",
    rules=(Rule(identifier="consumer:r_1", text="r(X) :- p(X)."),),
    depends_on=frozenset({"base", "slot_x"}),
    profiles=frozenset({"profile_a", "profile_b"}),
    variants={
        "variant_1": (
            Rule(identifier="consumer:variant_1:r_1", text="u(X) :- r(X)."),
        ),
        "variant_2": (
            Rule(identifier="consumer:variant_2:r_1", text="v(X) :- r(X)."),
        ),
    },
)

# Opt-in extension (plain group, no slot or profile). Two rules show the
# `r_1`/`r_2` numbering inside a single group's namespace.
extension = RuleGroup(
    identifier="extension",
    rules=(
        Rule(identifier="extension:r_1", text="t(X) :- r(X)."),
        Rule(identifier="extension:r_2", text="s(X) :- t(X)."),
    ),
    depends_on=frozenset({"consumer"}),
)

registry = RuleRegistry()
registry.register([base, slot_x_a, slot_x_b, consumer, extension])
assert registry.validate() == []

# One plan, two outputs — variants are decided at resolve() time, so the
# same selection produces different rule sets without re-planning.
plan_a = CollectionPlan(registry)
plan_a.add_profile("profile_a")      # includes: slot_x:a, consumer
plan_a.auto_include_deps()           # pulls in concrete deps: base

for rule in plan_a.resolve(variant="variant_1"):
    print(rule.text)
# p(X) :- q(X).          (base)
# q(X) :- a(X).          (slot_x:a, filling slot_x)
# r(X) :- p(X).          (consumer, shared)
# u(X) :- r(X).          (consumer, variant_1 payload)

for rule in plan_a.resolve(variant="variant_2"):
    print(rule.text)
# p(X) :- q(X).
# q(X) :- a(X).
# r(X) :- p(X).
# v(X) :- r(X).          (consumer, variant_2 payload — same plan, new flavor)

# A different profile picks a different slot_x filler, and the extension
# is pulled in explicitly. The same variant_1 still works — variants
# don't care which filler is active, because they only depend on `r(X)`.
plan_b = CollectionPlan(registry)
plan_b.add_profile("profile_b")      # includes: slot_x:b, consumer
plan_b.add_group("extension")        # opt-in, no profile carries it
plan_b.auto_include_deps()

for rule in plan_b.resolve(variant="variant_1"):
    print(rule.text)
# p(X) :- q(X).
# q(X) :- b(X).          (slot_x:b, filling slot_x)
# r(X) :- p(X).
# u(X) :- r(X).          (consumer, variant_1 payload — unchanged)
# t(X) :- r(X).          (extension, rule r_1)
# s(X) :- t(X).          (extension, rule r_2)

What each axis does in this example:

• slot_x picks which group defines q(X) — slot_x:a or slot_x:b — while consumer depends on slot_x polymorphically, without naming either filler.
• profile_a / profile_b are bulk toggles: one call to add_profile pulls in a coherent set of groups (here, a slot_x filler and the consumer). The extension group carries no profile and is added with add_group when wanted.
• variant_1 / variant_2 switch consumer's emitted rule payload at resolve() time. The variants derive from the shared r(X), so the choice is independent of both the profile and the slot filler — plan_a renders cleanly under either variant, and variant_1 works the same in plan_b.
• auto_include_deps only walks concrete depends_on edges; slot deps are left to the user (or to a profile) to resolve.

Concepts

• Rule — a single ASP rule with an identifier, source text, and optional docs.
• RuleGroup — rules that are always added/removed together. Declares depends_on (group identifiers or slot names), may fill a slot, may carry any number of profiles (tags), and may define per-flavor variants. Frozen.
• Slot — an abstract role that multiple groups can fill (e.g. "input_format", filled by format_sbml or format_kgml). A plan may include at most one filler per slot, and depends_on may name a slot instead of a concrete group — that's a polymorphic dependency on "some filler of this role".
• Profile — a free-form label carried by any number of groups (e.g. "experimental", "sbml"). plan.add_profile(name) includes every group tagged with it in a single call.
• Variant — a format/flavor key declared inside a group: variants={"key": (Rule, ...)}. plan.resolve(variant="key") emits rules plus the matching payload, so one plan can produce N programs (one per variant key).
• RuleRegistry — stores every known group. validate() catches unknown deps and cycles.
• CollectionPlan — user-curated included / excluded selection. validate() returns structured issues; resolve() returns a flat, ordered rule list or raises PlanInvalidError.

Slots vs profiles vs variants

The three are orthogonal: they act on different axes of the composition problem, and a single group can use all three at once without interference.

Use cases:

• Slot — interchangeable implementations of the same interface. An input_format slot filled by format_sbml or format_kgml; a solver_hints slot filled by clingo_hints or dlv_hints. Downstream groups write depends_on={"input_format"} and don't care which filler the user picks.
• Profile — bulk toggles for cross-cutting themes. Tag a dozen groups scattered across features with "experimental"; flip them all on at once with plan.add_profile("experimental"). Profiles never exclude anything and never conflict — they're a user-ergonomic shortcut, not a composition constraint.
• Variant — one group, multiple output flavors. A pathways group has shared logic in rules plus a few format-specific tail rules in variants={"sbml": ..., "kgml": ...}. The same plan yields two programs via resolve(variant="sbml") and resolve(variant="kgml") — no re-selection, no duplicate groups, no N×M explosion.

A single group can fill a slot, carry profiles, and define variants all at the same time.

Validation issues

Testing

pytest