causaliq-knowledge 0.1.0__py3-none-any.whl

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/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__

causaliq_knowledge/cli.py

@@ -0,0 +1,207 @@
+"""Command-line interface for causaliq-knowledge."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Optional
+
+import click
+
+from causaliq_knowledge import __version__
+
+
+@click.group()
+@click.version_option(version=__version__)
+def cli() -> None:
+    """CausalIQ Knowledge - LLM knowledge for causal discovery.
+
+    Query LLMs about causal relationships between variables.
+    """
+    pass
+
+
+@cli.command("query")
+@click.argument("node_a")
+@click.argument("node_b")
+@click.option(
+    "--model",
+    "-m",
+    multiple=True,
+    default=["groq/llama-3.1-8b-instant"],
+    help="LLM model(s) to query. Can be specified multiple times.",
+)
+@click.option(
+    "--domain",
+    "-d",
+    default=None,
+    help="Domain context (e.g., 'medicine', 'economics').",
+)
+@click.option(
+    "--strategy",
+    "-s",
+    type=click.Choice(["weighted_vote", "highest_confidence"]),
+    default="weighted_vote",
+    help="Consensus strategy for multi-model queries.",
+)
+@click.option(
+    "--json",
+    "output_json",
+    is_flag=True,
+    help="Output result as JSON.",
+)
+@click.option(
+    "--temperature",
+    "-t",
+    type=float,
+    default=0.1,
+    help="LLM temperature (0.0-1.0).",
+)
+def query_edge(
+    node_a: str,
+    node_b: str,
+    model: tuple[str, ...],
+    domain: Optional[str],
+    strategy: str,
+    output_json: bool,
+    temperature: float,
+) -> None:
+    """Query LLMs about a causal relationship between two variables.
+
+    NODE_A and NODE_B are the variable names to query about.
+
+    Examples:
+
+        cqknow query smoking lung_cancer
+
+        cqknow query smoking lung_cancer --domain medicine
+
+        cqknow query X Y --model groq/llama-3.1-8b-instant \
+                         --model gemini/gemini-2.5-flash
+    """
+    # Import here to avoid slow startup for --help
+    from causaliq_knowledge.llm import LLMKnowledge
+
+    # Build context
+    context = None
+    if domain:
+        context = {"domain": domain}
+
+    # Create provider
+    try:
+        provider = LLMKnowledge(
+            models=list(model),
+            consensus_strategy=strategy,
+            temperature=temperature,
+        )
+    except Exception as e:
+        click.echo(f"Error creating provider: {e}", err=True)
+        sys.exit(1)
+
+    # Query
+    click.echo(
+        f"Querying {len(model)} model(s) about: {node_a} -> {node_b}",
+        err=True,
+    )
+
+    try:
+        result = provider.query_edge(node_a, node_b, context=context)
+    except Exception as e:
+        click.echo(f"Error querying LLM: {e}", err=True)
+        sys.exit(1)
+
+    # Output
+    if output_json:
+        output = {
+            "node_a": node_a,
+            "node_b": node_b,
+            "exists": result.exists,
+            "direction": result.direction.value if result.direction else None,
+            "confidence": result.confidence,
+            "reasoning": result.reasoning,
+            "model": result.model,
+        }
+        click.echo(json.dumps(output, indent=2))
+    else:
+        # Human-readable output
+        exists_map = {True: "Yes", False: "No", None: "Uncertain"}
+        exists_str = exists_map[result.exists]
+        direction_str = result.direction.value if result.direction else "N/A"
+
+        click.echo(f"\n{'='*60}")
+        click.echo(f"Query: Does '{node_a}' cause '{node_b}'?")
+        click.echo("=" * 60)
+        click.echo(f"Exists:     {exists_str}")
+        click.echo(f"Direction:  {direction_str}")
+        click.echo(f"Confidence: {result.confidence:.2f}")
+        click.echo(f"Model(s):   {result.model or 'unknown'}")
+        click.echo(f"{'='*60}")
+        click.echo(f"Reasoning:  {result.reasoning}")
+        click.echo()
+
+    # Show stats
+    stats = provider.get_stats()
+    if stats["total_cost"] > 0:
+        click.echo(
+            f"Cost: ${stats['total_cost']:.6f} "
+            f"({stats['total_calls']} call(s))",
+            err=True,
+        )
+
+
+@cli.command("models")
+def list_models() -> None:
+    """List supported LLM models.
+
+    These are model identifiers that work with our direct API clients.
+    Only models with direct API support are listed.
+    """
+    models = [
+        (
+            "Groq (Fast, Free Tier Available)",
+            [
+                "groq/llama-3.1-8b-instant",
+                "groq/llama-3.1-70b-versatile",
+                "groq/llama-3.2-1b-preview",
+                "groq/llama-3.2-3b-preview",
+                "groq/mixtral-8x7b-32768",
+                "groq/gemma-7b-it",
+                "groq/gemma2-9b-it",
+            ],
+        ),
+        (
+            "Google Gemini (Free Tier Available)",
+            [
+                "gemini/gemini-2.5-flash",
+                "gemini/gemini-1.5-pro",
+                "gemini/gemini-1.5-flash",
+                "gemini/gemini-1.5-flash-8b",
+            ],
+        ),
+    ]
+
+    click.echo("\nSupported LLM Models (Direct API Access):\n")
+    for provider, model_list in models:
+        click.echo(f"  {provider}:")
+        for m in model_list:
+            click.echo(f"    - {m}")
+    click.echo()
+    click.echo("Required API Keys:")
+    click.echo(
+        "  GROQ_API_KEY      - Get free API key at https://console.groq.com"
+    )
+    click.echo(
+        "  GEMINI_API_KEY    - Get free API key at https://aistudio.google.com"
+    )
+    click.echo()
+    click.echo("Default model: groq/llama-3.1-8b-instant")
+    click.echo()
+
+
+def main() -> None:
+    """Entry point for the CLI."""
+    cli()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

causaliq_knowledge/llm/__init__.py

@@ -0,0 +1,34 @@
+"""LLM integration module for causaliq-knowledge."""
+
+from causaliq_knowledge.llm.gemini_client import (
+    GeminiClient,
+    GeminiConfig,
+    GeminiResponse,
+)
+from causaliq_knowledge.llm.groq_client import (
+    GroqClient,
+    GroqConfig,
+    GroqResponse,
+)
+from causaliq_knowledge.llm.prompts import EdgeQueryPrompt, parse_edge_response
+from causaliq_knowledge.llm.provider import (
+    CONSENSUS_STRATEGIES,
+    LLMKnowledge,
+    highest_confidence,
+    weighted_vote,
+)
+
+__all__ = [
+    "CONSENSUS_STRATEGIES",
+    "EdgeQueryPrompt",
+    "GeminiClient",
+    "GeminiConfig",
+    "GeminiResponse",
+    "GroqClient",
+    "GroqConfig",
+    "GroqResponse",
+    "LLMKnowledge",
+    "highest_confidence",
+    "parse_edge_response",
+    "weighted_vote",
+]

causaliq_knowledge/llm/gemini_client.py

@@ -0,0 +1,203 @@
+"""Direct Google Gemini API client - clean and reliable."""
+
+import json
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class GeminiConfig:
+    """Configuration for Gemini API client."""
+
+    model: str = "gemini-2.5-flash"
+    temperature: float = 0.1
+    max_tokens: int = 500
+    timeout: float = 30.0
+    api_key: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        """Set API key from environment if not provided."""
+        if self.api_key is None:
+            self.api_key = os.getenv("GEMINI_API_KEY")
+        if not self.api_key:
+            raise ValueError("GEMINI_API_KEY environment variable is required")
+
+
+@dataclass
+class GeminiResponse:
+    """Response from Gemini API."""
+
+    content: str
+    model: str
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cost: float = 0.0  # Gemini free tier
+    raw_response: Optional[Dict] = None
+
+    def parse_json(self) -> Optional[Dict[str, Any]]:
+        """Parse content as JSON, handling common formatting issues."""
+        try:
+            # Clean up potential markdown code blocks
+            text = self.content.strip()
+            if text.startswith("```json"):
+                text = text[7:]
+            elif text.startswith("```"):
+                text = text[3:]
+            if text.endswith("```"):
+                text = text[:-3]
+
+            return json.loads(text.strip())  # type: ignore[no-any-return]
+        except json.JSONDecodeError:
+            return None
+
+
+class GeminiClient:
+    """Direct Gemini API client."""
+
+    BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models"
+
+    def __init__(self, config: Optional[GeminiConfig] = None):
+        """Initialize Gemini client."""
+        self.config = config or GeminiConfig()
+        self._total_calls = 0
+
+    def completion(
+        self, messages: List[Dict[str, str]], **kwargs: Any
+    ) -> GeminiResponse:
+        """Make a chat completion request to Gemini."""
+
+        # Convert OpenAI-style messages to Gemini format
+        contents = []
+        system_instruction = None
+
+        for msg in messages:
+            if msg["role"] == "system":
+                # Gemini handles system prompts differently
+                system_instruction = {"parts": [{"text": msg["content"]}]}
+            elif msg["role"] == "user":
+                contents.append(
+                    {"role": "user", "parts": [{"text": msg["content"]}]}
+                )
+            elif msg["role"] == "assistant":
+                contents.append(
+                    {"role": "model", "parts": [{"text": msg["content"]}]}
+                )
+
+        # Build request payload in Gemini's format
+        payload = {
+            "contents": contents,
+            "generationConfig": {
+                "temperature": kwargs.get(
+                    "temperature", self.config.temperature
+                ),
+                "maxOutputTokens": kwargs.get(
+                    "max_tokens", self.config.max_tokens
+                ),
+                "responseMimeType": "text/plain",
+            },
+        }
+
+        # Add system instruction if present
+        if system_instruction:
+            payload["systemInstruction"] = system_instruction
+
+        # API endpoint with model and key
+        url = f"{self.BASE_URL}/{self.config.model}:generateContent"
+        params = {"key": self.config.api_key}
+
+        headers = {"Content-Type": "application/json"}
+
+        logger.debug(f"Calling Gemini API with model: {self.config.model}")
+
+        try:
+            with httpx.Client(timeout=self.config.timeout) as client:
+                response = client.post(
+                    url, json=payload, headers=headers, params=params
+                )
+                response.raise_for_status()
+
+                data = response.json()
+
+                # Handle Gemini API errors
+                if "error" in data:
+                    error_msg = data["error"].get("message", "Unknown error")
+                    raise ValueError(f"Gemini API error: {error_msg}")
+
+                # Extract response data from Gemini format
+                candidates = data.get("candidates", [])
+                if not candidates:
+                    raise ValueError("No candidates returned by Gemini API")
+
+                candidate = candidates[0]
+                if candidate.get("finishReason") == "SAFETY":
+                    raise ValueError(
+                        "Content was blocked by Gemini safety filters"
+                    )
+
+                # Extract text content
+                parts = candidate.get("content", {}).get("parts", [])
+                content = ""
+                for part in parts:
+                    if "text" in part:
+                        content += part["text"]
+
+                # Extract usage info
+                usage = data.get("usageMetadata", {})
+                input_tokens = usage.get("promptTokenCount", 0)
+                output_tokens = usage.get("candidatesTokenCount", 0)
+
+                self._total_calls += 1
+
+                logger.debug(
+                    f"Gemini response: {input_tokens} in, {output_tokens} out"
+                )
+
+                return GeminiResponse(
+                    content=content,
+                    model=self.config.model,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    cost=0.0,  # Free tier
+                    raw_response=data,
+                )
+
+        except httpx.HTTPStatusError as e:
+            try:
+                error_data = e.response.json()
+                error_msg = error_data.get("error", {}).get(
+                    "message", e.response.text
+                )
+            except Exception:
+                error_msg = e.response.text
+
+            logger.error(
+                f"Gemini API HTTP error: {e.response.status_code} - "
+                f"{error_msg}"
+            )
+            raise ValueError(
+                f"Gemini API error: {e.response.status_code} - {error_msg}"
+            )
+        except httpx.TimeoutException:
+            raise ValueError("Gemini API request timed out")
+        except Exception as e:
+            logger.error(f"Gemini API unexpected error: {e}")
+            raise ValueError(f"Gemini API error: {str(e)}")
+
+    def complete_json(
+        self, messages: List[Dict[str, str]], **kwargs: Any
+    ) -> tuple[Optional[Dict[str, Any]], GeminiResponse]:
+        """Make a completion request and parse response as JSON."""
+        response = self.completion(messages, **kwargs)
+        parsed = response.parse_json()
+        return parsed, response
+
+    @property
+    def call_count(self) -> int:
+        """Number of API calls made."""
+        return self._total_calls