causaliq-knowledge 0.1.0__tar.gz

causaliq_knowledge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CausalIQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

causaliq_knowledge-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: causaliq-knowledge
+Version: 0.1.0
+Summary: Incorporating LLM and human knowledge into causal discovery
+Author-email: CausalIQ <info@causaliq.com>
+Maintainer-email: CausalIQ <info@causaliq.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/causaliq/causaliq-knowledge
+Project-URL: Documentation, https://github.com/causaliq/causaliq-knowledge#readme
+Project-URL: Repository, https://github.com/causaliq/causaliq-knowledge
+Project-URL: Bug Tracker, https://github.com/causaliq/causaliq-knowledge/issues
+Keywords: causaliq
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: causaliq-core>=0.3.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: isort>=5.10.0; extra == "dev"
+Requires-Dist: flake8>=5.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-requests>=2.32.0; extra == "dev"
+Requires-Dist: pre-commit>=2.20.0; extra == "dev"
+Requires-Dist: build>=0.8.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: causaliq-core>=0.3.0; extra == "test"
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-mock>=3.10.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
+Requires-Dist: mkdocstrings==0.30.1; extra == "docs"
+Requires-Dist: mkdocstrings-python==1.18.2; extra == "docs"
+Dynamic: license-file
+
+# causaliq-knowledge
+
+![Python Versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
+
+The CausalIQ Knowledge project represents a novel approach to causal discovery by combining the traditional statistical structure learning algorithms with the contextual understanding and reasoning capabilities of Large Language Models. This integration enables more interpretable, domain-aware, and human-friendly causal discovery workflows. It is part of the [CausalIQ ecosystem](https://causaliq.org/) for intelligent causal discovery.
+
+## Status
+
+🚧 **Active Development** - this repository is currently in active development, which involves:
+
+- Adding new knowledge features, in particular knowledge from LLMs
+- Migrating functionality which provides knowledge based on standard reference networks from the legacy monolithic discovery repo
+- Ensuring CausalIQ development standards are met
+
+
+## Quick Start
+
+```python
+from causaliq_knowledge.llm import LLMKnowledge
+
+# Query an LLM about a potential causal relationship
+knowledge = LLMKnowledge(models=["groq/llama-3.1-8b-instant"])
+result = knowledge.query_edge("smoking", "lung_cancer")
+
+print(f"Exists: {result.exists}, Direction: {result.direction}")
+print(f"Confidence: {result.confidence}")
+print(f"Reasoning: {result.reasoning}")
+```
+
+## Features
+
+Under development:
+
+- **Release v0.1.0 - Foundation LLM**: Simple LLM queries to 1 or 2 LLMs about edge existence and orientation to support graph averaging
+
+Currently implemented releases:
+
+- None
+
+Planned:
+
+- **Release v0.2.0 - Additional LLMs**: Support for more LLM providers (OpenAI, Anthropic)
+- **Release v0.3.0 - LLM Caching**: Caching of LLM queries and responses
+- **Release v0.4.0 - LLM Context**: Variable/role/literature etc context
+- **Release v0.5.0 - Algorithm integration**: Integration into structure learning algorithms
+- **Release v0.6.0 - Legacy Reference**: Support for legacy approaches of deriving knowledge from reference networks
+
+## Implementation Approach
+
+### Technology Stack
+
+- **Vendor-Specific API Clients**: Direct integration with LLM providers using httpx
+- **[Pydantic](https://docs.pydantic.dev/)**: Structured response validation
+- **[Click](https://click.palletsprojects.com/)**: Command-line interface
+
+### Why Vendor-Specific APIs (not LiteLLM/LangChain)?
+
+We use **direct vendor-specific API clients** rather than wrapper libraries:
+
+| Aspect | Direct APIs | Wrapper Libraries |
+|--------|-------------|-------------------|
+| Reliability | ✅ Full control | ❌ Wrapper bugs |
+| Dependencies | ✅ Minimal (httpx) | ❌ Heavy (~50-100MB) |
+| Debugging | ✅ Clear traces | ❌ Abstraction layers |
+| Maintenance | ✅ We control | ❌ Wait for updates |
+
+This approach keeps the package lightweight, reliable, and easy to debug.
+
+### Supported LLM Providers
+
+| Provider | Client | Models | Free Tier |
+|----------|--------|--------|-----------|
+| **Groq** | `GroqClient` | llama-3.1-8b-instant | ✅ Generous |
+| **Google Gemini** | `GeminiClient` | gemini-2.5-flash | ✅ Generous |
+
+Additional providers (OpenAI, Anthropic) can be added in future releases.
+
+## Upcoming Key Innovations
+
+### 🧠 LLMs support Causal Discovery and Inference
+
+- Initially LLM will work with **graph averaging** to resolve uncertain edges (use entropy to decide edges with uncertain existence or direction)
+- Integration into **structure learning** algorithms to provide knowledge for "uncertain" areas of the graph
+- LLMs analyse learning process and errors to **suggest improved algorithms**
+- LLMs used to preprocess **text and visual data** so they can be used as inputs to structure learning
+
+### 🤝 Human Engagement
+
+- **Natural language constraints**: Specify domain knowledge in plain English
+- **Expert knowledge incorporation** by converting expert understanding into algorithmic constraints
+- LLMs convert **natural language questions** to causal queries
+- **Interactive causal discovery** where structure learning or LLMs identify areas of causal uncertainty and can test causal hypotheses through dialogue
+
+### 🪟 Transparency and interpretability
+
+- LLMs **interpret structure learning process** and outputs, including their uncertainties
+- LLMs **interpret causal inference** results including uncertainties
+- **Contextual graph interpretation** to explain variable meanings and relationships
+- **Uncertainty communication** with clear explanation of confidence levels and limitations
+- **Report generation** including automated research summaries and methodology descriptions
+
+### 🔒 Stability and reproducibility
+
+- **Cache queries and responses** so that experiments are stable and repeatable even if LLMs themselves are not
+- **Stable randomisation** of e.g. data sub-sampling
+
+### 💰 Efficient use of LLM resources (important as an independent researcher)
+
+- **Cache queries and results** so that knowledge can be re-used
+- Evaluation and development of **simple context-adapted LLMs**
+
+
+## Upcoming Integration with CausalIQ Ecosystem
+
+- 🔍 CausalIQ Discovery makes use of this package to learn more accurate graphs.
+- 🧪 CausalIQ Analysis uses this package to explain the learning process, intelligently combine and explain results.
+- 🔮 CausalIQ Predict uses this package to explain predictions made by learnt models.
+
+## Documentation
+
+- [User Guide](docs/userguide/introduction.md) - Getting started
+- [Architecture Overview](docs/architecture/overview.md) - Design and components
+- [LLM Integration Design](docs/architecture/llm_integration.md) - Detailed LLM design
+- [Roadmap](docs/roadmap.md) - Release planning
+
+---
+
+**Supported Python Versions**: 3.9, 3.10, 3.11, 3.12, 3.13  
+**Default Python Version**: 3.11

causaliq_knowledge-0.1.0/README.md

@@ -0,0 +1,131 @@
+# causaliq-knowledge
+
+![Python Versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
+
+The CausalIQ Knowledge project represents a novel approach to causal discovery by combining the traditional statistical structure learning algorithms with the contextual understanding and reasoning capabilities of Large Language Models. This integration enables more interpretable, domain-aware, and human-friendly causal discovery workflows. It is part of the [CausalIQ ecosystem](https://causaliq.org/) for intelligent causal discovery.
+
+## Status
+
+🚧 **Active Development** - this repository is currently in active development, which involves:
+
+- Adding new knowledge features, in particular knowledge from LLMs
+- Migrating functionality which provides knowledge based on standard reference networks from the legacy monolithic discovery repo
+- Ensuring CausalIQ development standards are met
+
+
+## Quick Start
+
+```python
+from causaliq_knowledge.llm import LLMKnowledge
+
+# Query an LLM about a potential causal relationship
+knowledge = LLMKnowledge(models=["groq/llama-3.1-8b-instant"])
+result = knowledge.query_edge("smoking", "lung_cancer")
+
+print(f"Exists: {result.exists}, Direction: {result.direction}")
+print(f"Confidence: {result.confidence}")
+print(f"Reasoning: {result.reasoning}")
+```
+
+## Features
+
+Under development:
+
+- **Release v0.1.0 - Foundation LLM**: Simple LLM queries to 1 or 2 LLMs about edge existence and orientation to support graph averaging
+
+Currently implemented releases:
+
+- None
+
+Planned:
+
+- **Release v0.2.0 - Additional LLMs**: Support for more LLM providers (OpenAI, Anthropic)
+- **Release v0.3.0 - LLM Caching**: Caching of LLM queries and responses
+- **Release v0.4.0 - LLM Context**: Variable/role/literature etc context
+- **Release v0.5.0 - Algorithm integration**: Integration into structure learning algorithms
+- **Release v0.6.0 - Legacy Reference**: Support for legacy approaches of deriving knowledge from reference networks
+
+## Implementation Approach
+
+### Technology Stack
+
+- **Vendor-Specific API Clients**: Direct integration with LLM providers using httpx
+- **[Pydantic](https://docs.pydantic.dev/)**: Structured response validation
+- **[Click](https://click.palletsprojects.com/)**: Command-line interface
+
+### Why Vendor-Specific APIs (not LiteLLM/LangChain)?
+
+We use **direct vendor-specific API clients** rather than wrapper libraries:
+
+| Aspect | Direct APIs | Wrapper Libraries |
+|--------|-------------|-------------------|
+| Reliability | ✅ Full control | ❌ Wrapper bugs |
+| Dependencies | ✅ Minimal (httpx) | ❌ Heavy (~50-100MB) |
+| Debugging | ✅ Clear traces | ❌ Abstraction layers |
+| Maintenance | ✅ We control | ❌ Wait for updates |
+
+This approach keeps the package lightweight, reliable, and easy to debug.
+
+### Supported LLM Providers
+
+| Provider | Client | Models | Free Tier |
+|----------|--------|--------|-----------|
+| **Groq** | `GroqClient` | llama-3.1-8b-instant | ✅ Generous |
+| **Google Gemini** | `GeminiClient` | gemini-2.5-flash | ✅ Generous |
+
+Additional providers (OpenAI, Anthropic) can be added in future releases.
+
+## Upcoming Key Innovations
+
+### 🧠 LLMs support Causal Discovery and Inference
+
+- Initially LLM will work with **graph averaging** to resolve uncertain edges (use entropy to decide edges with uncertain existence or direction)
+- Integration into **structure learning** algorithms to provide knowledge for "uncertain" areas of the graph
+- LLMs analyse learning process and errors to **suggest improved algorithms**
+- LLMs used to preprocess **text and visual data** so they can be used as inputs to structure learning
+
+### 🤝 Human Engagement
+
+- **Natural language constraints**: Specify domain knowledge in plain English
+- **Expert knowledge incorporation** by converting expert understanding into algorithmic constraints
+- LLMs convert **natural language questions** to causal queries
+- **Interactive causal discovery** where structure learning or LLMs identify areas of causal uncertainty and can test causal hypotheses through dialogue
+
+### 🪟 Transparency and interpretability
+
+- LLMs **interpret structure learning process** and outputs, including their uncertainties
+- LLMs **interpret causal inference** results including uncertainties
+- **Contextual graph interpretation** to explain variable meanings and relationships
+- **Uncertainty communication** with clear explanation of confidence levels and limitations
+- **Report generation** including automated research summaries and methodology descriptions
+
+### 🔒 Stability and reproducibility
+
+- **Cache queries and responses** so that experiments are stable and repeatable even if LLMs themselves are not
+- **Stable randomisation** of e.g. data sub-sampling
+
+### 💰 Efficient use of LLM resources (important as an independent researcher)
+
+- **Cache queries and results** so that knowledge can be re-used
+- Evaluation and development of **simple context-adapted LLMs**
+
+
+## Upcoming Integration with CausalIQ Ecosystem
+
+- 🔍 CausalIQ Discovery makes use of this package to learn more accurate graphs.
+- 🧪 CausalIQ Analysis uses this package to explain the learning process, intelligently combine and explain results.
+- 🔮 CausalIQ Predict uses this package to explain predictions made by learnt models.
+
+## Documentation
+
+- [User Guide](docs/userguide/introduction.md) - Getting started
+- [Architecture Overview](docs/architecture/overview.md) - Design and components
+- [LLM Integration Design](docs/architecture/llm_integration.md) - Detailed LLM design
+- [Roadmap](docs/roadmap.md) - Release planning
+
+---
+
+**Supported Python Versions**: 3.9, 3.10, 3.11, 3.12, 3.13  
+**Default Python Version**: 3.11

causaliq_knowledge-0.1.0/pyproject.toml

@@ -0,0 +1,184 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "causaliq-knowledge"
+dynamic = ["version"]
+description = "Incorporating LLM and human knowledge into causal discovery"
+readme = "README.md"
+license = "MIT"
+authors = [
+    {name = "CausalIQ", email = "info@causaliq.com"},
+]
+maintainers = [
+    {name = "CausalIQ", email = "info@causaliq.com"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+keywords = ["causaliq"]
+requires-python = ">=3.9"
+dependencies = [
+    "click>=8.0.0",
+    "httpx>=0.24.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "causaliq-core>=0.3.0",
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-mock>=3.10.0",
+    "black>=22.0.0",
+    "isort>=5.10.0",
+    "flake8>=5.0.0",
+    "mypy>=1.0.0",
+    "types-requests>=2.32.0",
+    "pre-commit>=2.20.0",
+    "build>=0.8.0",
+    "twine>=4.0.0",
+]
+test = [
+    "causaliq-core>=0.3.0",
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-mock>=3.10.0",
+]
+docs = [
+    "mkdocs>=1.5.0",
+    "mkdocs-material>=9.0.0",
+    "mkdocstrings==0.30.1",
+    "mkdocstrings-python==1.18.2"
+]
+
+[project.urls]
+Homepage = "https://github.com/causaliq/causaliq-knowledge"
+Documentation = "https://github.com/causaliq/causaliq-knowledge#readme"
+Repository = "https://github.com/causaliq/causaliq-knowledge"
+"Bug Tracker" = "https://github.com/causaliq/causaliq-knowledge/issues"
+
+[project.scripts]
+causaliq-knowledge = "causaliq_knowledge.cli:main"
+cqknow = "causaliq_knowledge.cli:main"
+
+[tool.setuptools.dynamic]
+version = {attr = "causaliq_knowledge.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.package-data]
+causaliq_knowledge = ["py.typed"]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q --strict-markers --cov=causaliq_knowledge --cov-report=term-missing --cov-report=html  -m 'not slow'"
+testpaths = [
+    "tests",
+]
+python_files = [
+    "test_*.py",
+    "*_test.py",
+]
+python_classes = [
+    "Test*",
+]
+python_functions = [
+    "test_*",
+]
+markers = [
+    "unit: Unit tests (fast, no external dependencies)",
+    "functional: Functional tests (CLI behavior, mocked external deps)",
+    "integration: Integration tests (real external dependencies)",
+    "slow: Slow tests that take significant time",
+]
+
+[tool.coverage.run]
+source = ["src/causaliq_knowledge"]
+omit = [
+    "*/tests/*",
+    "*/test_*.py",
+]
+parallel = true
+concurrency = ["thread", "multiprocessing"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]
+
+[tool.black]
+line-length = 79
+target-version = ['py39']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | build
+  | dist
+)/
+'''
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+line_length = 79
+known_first_party = ["causaliq_knowledge"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[[tool.mypy.overrides]]
+module = [
+    "scipy",
+    "scipy.*",
+    "scipy.stats", 
+    "scipy.special"
+]
+ignore_missing_imports = true

causaliq_knowledge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

causaliq_knowledge-0.1.0/src/causaliq_knowledge/__init__.py

@@ -0,0 +1,33 @@
+"""
+causaliq-knowledge: LLM and human knowledge for causal discovery.
+"""
+
+from causaliq_knowledge.base import KnowledgeProvider
+from causaliq_knowledge.models import EdgeDirection, EdgeKnowledge
+
+__version__ = "0.1.0"
+__author__ = "CausalIQ"
+__email__ = "info@causaliq.com"
+
+# Package metadata
+__title__ = "causaliq-knowledge"
+__description__ = "LLM and human knowledge for causal discovery"
+
+__url__ = "https://github.com/causaliq/causaliq-knowledge"
+__license__ = "MIT"
+
+# Version tuple for programmatic access
+VERSION = tuple(map(int, __version__.split(".")))
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__email__",
+    "VERSION",
+    # Core models
+    "EdgeKnowledge",
+    "EdgeDirection",
+    # Abstract interface
+    "KnowledgeProvider",
+    # Note: Import LLMKnowledge from causaliq_knowledge.llm
+]

causaliq_knowledge-0.1.0/src/causaliq_knowledge/base.py

@@ -0,0 +1,85 @@
+"""Abstract base class for knowledge providers."""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from causaliq_knowledge.models import EdgeKnowledge
+
+
+class KnowledgeProvider(ABC):
+    """Abstract interface for all knowledge sources.
+
+    This is the base class that all knowledge providers must implement.
+    Knowledge providers can be LLM-based, rule-based, human-input based,
+    or any other source of causal knowledge.
+
+    The primary method is `query_edge()` which asks about the causal
+    relationship between two variables.
+
+    Example:
+        >>> class MyKnowledgeProvider(KnowledgeProvider):
+        ...     def query_edge(self, node_a, node_b, context=None):
+        ...         # Implementation here
+        ...         return EdgeKnowledge(exists=True, confidence=0.8, ...)
+        ...
+        >>> provider = MyKnowledgeProvider()
+        >>> result = provider.query_edge("smoking", "cancer")
+    """
+
+    @abstractmethod
+    def query_edge(
+        self,
+        node_a: str,
+        node_b: str,
+        context: Optional[dict] = None,
+    ) -> EdgeKnowledge:
+        """Query whether a causal edge exists between two nodes.
+
+        Args:
+            node_a: Name of the first variable.
+            node_b: Name of the second variable.
+            context: Optional context dictionary that may include:
+                - domain: The domain (e.g., "medicine", "economics")
+                - descriptions: Dict mapping variable names to descriptions
+                - additional_info: Any other relevant context
+
+        Returns:
+            EdgeKnowledge with:
+                - exists: True, False, or None (uncertain)
+                - direction: "a_to_b", "b_to_a", "undirected", or None
+                - confidence: 0.0 to 1.0
+                - reasoning: Human-readable explanation
+                - model: Source identifier (optional)
+
+        Raises:
+            NotImplementedError: If not implemented by subclass.
+        """
+        pass
+
+    def query_edges(
+        self,
+        edges: list[tuple[str, str]],
+        context: Optional[dict] = None,
+    ) -> list[EdgeKnowledge]:
+        """Query multiple edges at once.
+
+        Default implementation calls query_edge for each pair.
+        Subclasses may override for batch optimization.
+
+        Args:
+            edges: List of (node_a, node_b) tuples to query.
+            context: Optional context dictionary (shared across all queries).
+
+        Returns:
+            List of EdgeKnowledge results, one per edge pair.
+        """
+        return [self.query_edge(a, b, context) for a, b in edges]
+
+    @property
+    def name(self) -> str:
+        """Return the name of this knowledge provider.
+
+        Returns:
+            Class name by default. Subclasses may override.
+        """
+        return self.__class__.__name__