Add type stub file for _ds C++ extension module

[Copilot]

Add _ds.pyi stub file to provide type hints for the pybind11 C++ extension module.

Changes

• Type stubs for all extension classes: String, Variable, Item, List, Term, Rule, Search
• Static method signatures: ground(), match(), rename() for Term and Rule classes
• Enum definitions: Term.Type with Variable, Item, List, Null values
• Special methods: len, getitem, init with proper type annotations

Benefits

• IDE autocomplete and type checking support for the C++ extension
• Static analysis with mypy and other type checkers
• Improved developer experience with inline documentation

Example

from apyds import _ds

# Type checker now understands the extension module interface
term: _ds.Term = _ds.Term.from_string("(f `x a)", 1000)
result: _ds.Term | None = _ds.Term.ground(term, dictionary, "scope", 1000)

The stub file follows PEP 561 conventions and complements the existing py.typed marker in the package.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Write a _ds.pyi in /apyds</issue_title>
<issue_description></issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Write a _ds.pyi in /apyds #136

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This PR adds a comprehensive type stub file (_ds.pyi) for the C++ extension module built with pybind11, enabling IDE autocomplete, static type checking with mypy, and improved developer experience.

Key Changes

• Complete type annotations for all 7 C++ extension classes (String, Variable, Item, List, Term, Rule, Search)
• Static method signatures for serialization, deserialization, and operations like ground(), match(), and rename()
• Nested Term.Type enum definition with proper values

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The documentation states the prefix_and_suffix parameter is "A rule with two inner lists for prefix and suffix" but the type signature shows it as Rule. Based on the usage in rule_t.py (line 120), this should be more clearly documented as "A Rule object whose conclusion is a list containing two inner lists".

Suggested change

	prefix_and_suffix: A rule with two inner lists for prefix and suffix.
	prefix_and_suffix: A Rule object whose conclusion is a list containing two inner lists (prefix and suffix).

[Copilot]

The documentation describes the prefix_and_suffix parameter as "A term with two inner lists for prefix and suffix", but based on the usage in term_t.py (line 106), this should be more precisely documented as "A Term representing a list containing two inner lists, where each inner list contains 0 or 1 item for the prefix and suffix respectively".

Suggested change

	prefix_and_suffix: A term with two inner lists for prefix and suffix.
	prefix_and_suffix: A Term representing a list containing two inner lists, where each inner list
	contains 0 or 1 item for the prefix and suffix respectively.

[Copilot]

The scope_1 and scope_2 parameters lack clear documentation about their purpose. Based on the usage in term_t.py (line 96), these are scope identifiers used to distinguish variables from different terms during unification. Consider adding more detail about how these scopes work.

[Copilot]

The documentation describes the dictionary parameter as "A term representing a dictionary (list of pairs)" but doesn't clarify the structure. Based on the usage in term_t.py (lines 57-58), this should be more clearly documented as "A Term representing a list of pairs, where each pair contains a variable and its substitution value".

Suggested change

	dictionary: A term representing a dictionary (list of pairs).
	dictionary: A Term representing a list of pairs, where each pair
	contains a variable and its substitution value.

[Copilot]

The documentation states the dictionary parameter is "A rule representing a dictionary (list of pairs)" but the type signature shows it as Rule. However, examining the usage examples in rule_t.py (lines 65 and 73), dictionaries are actually Rules with only conclusions. The documentation should clarify that this is a Rule object whose conclusion is a list of pairs, not a "rule representing a dictionary".

Suggested change

	dictionary: A rule representing a dictionary (list of pairs).
	dictionary: A Rule whose conclusion is a list of pairs used as a substitution dictionary.