graphora 0.0.0__py3-none-any.whl

graphora/__init__.py

@@ -0,0 +1,15 @@
+"""
+Graphora Client Library
+
+A Python client for interacting with the Graphora API.
+"""
+
+from importlib.metadata import version, PackageNotFoundError
+
+from graphora.client import GraphoraClient
+from graphora.models import *  # noqa: F401,F403 - re-export public models
+
+try:
+    __version__ = version("graphora")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"

graphora/cli/__init__.py

@@ -0,0 +1,8 @@
+"""Graphora CLI - Command-line interface for knowledge graph extraction."""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("graphora")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"

graphora/cli/api_manager.py

@@ -0,0 +1,380 @@
+"""API Manager - handles downloading and managing graphora-api.
+
+Automatically downloads and caches graphora-api from GitHub for embedded mode.
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Optional, Tuple
+
+import requests
+
+from graphora.cli.config import CONFIG_DIR, get_config_value, set_config_value
+
+
+# Default GitHub repo
+GITHUB_REPO = "graphora/graphora-api"
+GITHUB_API_URL = f"https://api.github.com/repos/{GITHUB_REPO}"
+DEFAULT_BRANCH = "main"
+
+# Cache directory
+API_CACHE_DIR = CONFIG_DIR / "api"
+DEPS_INSTALLED_MARKER = ".deps_installed"
+
+# Version channels
+VERSION_CHANNELS = {
+    "stable": "latest",      # Latest stable release
+    "nightly": "nightly",    # Latest nightly build
+    "main": "main",          # Main branch (development)
+}
+
+
+def get_api_path() -> Optional[Path]:
+    """Get the path to graphora-api (cached or custom).
+
+    Returns:
+        Path to graphora-api directory, or None if not available.
+    """
+    # Check for custom path override first
+    custom_path = get_config_value("embedded.api_path")
+    if custom_path:
+        custom_path = Path(os.path.expanduser(custom_path))
+        if custom_path.is_dir():
+            return custom_path
+
+    # Check cached version
+    cached_path = get_cached_api_path()
+    if cached_path and cached_path.is_dir():
+        return cached_path
+
+    return None
+
+
+def get_cached_api_path() -> Optional[Path]:
+    """Get path to the cached graphora-api."""
+    if not API_CACHE_DIR.exists():
+        return None
+
+    # Look for the extracted directory
+    for item in API_CACHE_DIR.iterdir():
+        if item.is_dir() and item.name.startswith("graphora-api"):
+            return item
+
+    return None
+
+
+def get_installed_version() -> Optional[str]:
+    """Get the currently installed version."""
+    return get_config_value("embedded.installed_version")
+
+
+def get_latest_version(channel: str = "stable") -> str:
+    """Fetch the latest version from GitHub.
+
+    Args:
+        channel: Version channel - "stable", "nightly", or "main"
+
+    Returns:
+        Version string (e.g., "v1.0.0", "nightly-20240101", or "main")
+    """
+    if channel == "main":
+        return DEFAULT_BRANCH
+
+    if channel == "nightly":
+        # Get latest nightly release
+        try:
+            response = requests.get(
+                f"{GITHUB_API_URL}/releases",
+                timeout=10,
+                headers={"Accept": "application/vnd.github.v3+json"},
+                params={"per_page": 20}
+            )
+            if response.status_code == 200:
+                releases = response.json()
+                for release in releases:
+                    tag = release.get("tag_name", "")
+                    if tag.startswith("nightly-"):
+                        return tag
+        except Exception:
+            pass
+        # Fall back to nightly tag
+        return "nightly"
+
+    # Stable channel - get latest non-prerelease
+    try:
+        response = requests.get(
+            f"{GITHUB_API_URL}/releases/latest",
+            timeout=10,
+            headers={"Accept": "application/vnd.github.v3+json"}
+        )
+        if response.status_code == 200:
+            data = response.json()
+            tag = data.get("tag_name")
+            if tag:
+                return tag
+    except Exception:
+        pass
+
+    # No releases found, use main branch
+    return DEFAULT_BRANCH
+
+
+def is_api_available() -> bool:
+    """Check if graphora-api is available and ready to use."""
+    api_path = get_api_path()
+    if not api_path:
+        return False
+
+    # Check if key files exist
+    required_files = [
+        "app/__init__.py",
+        "app/services/transform/graph_transformer.py",
+    ]
+
+    for file in required_files:
+        if not (api_path / file).exists():
+            return False
+
+    return True
+
+
+def is_deps_installed() -> bool:
+    """Check if dependencies have been installed."""
+    cached_path = get_cached_api_path()
+    if not cached_path:
+        return False
+    return (cached_path / DEPS_INSTALLED_MARKER).exists()
+
+
+def download_api(
+    version: Optional[str] = None,
+    channel: str = "main",
+    force: bool = False,
+    progress_callback=None,
+) -> Tuple[bool, str]:
+    """Download graphora-api from GitHub.
+
+    Args:
+        version: Version to download (tag or branch). Defaults to main branch.
+        channel: Version channel - "stable", "nightly", or "main". Default: main.
+        force: Force re-download even if already cached.
+        progress_callback: Optional callback for progress updates.
+
+    Returns:
+        Tuple of (success, message).
+    """
+    if progress_callback:
+        progress_callback("Checking for updates...")
+
+    # Determine version to download
+    if not version:
+        configured_channel = get_config_value("embedded.channel") or channel
+        version = get_config_value("embedded.version") or get_latest_version(configured_channel)
+
+    # Check if already installed
+    installed_version = get_installed_version()
+    if not force and installed_version == version and is_api_available():
+        return True, f"graphora-api {version} already installed"
+
+    if progress_callback:
+        progress_callback(f"Downloading graphora-api {version}...")
+
+    # Create cache directory
+    API_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Determine download URL based on version format
+    # Formats: YYYY-MM-vX.Y.Z, vX.Y.Z, nightly-YYYYMMDD, main
+    if version in ["main", "nightly", "latest"]:
+        # It's a branch or special tag - use branch URL
+        zip_url = f"https://github.com/{GITHUB_REPO}/archive/refs/heads/{version}.zip"
+    else:
+        # It's a tag (YYYY-MM-vX.Y.Z, vX.Y.Z, nightly-YYYYMMDD, etc.)
+        zip_url = f"https://github.com/{GITHUB_REPO}/archive/refs/tags/{version}.zip"
+
+    try:
+        response = requests.get(zip_url, stream=True, timeout=60)
+        response.raise_for_status()
+
+        # Save to temp file
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".zip") as tmp_file:
+            total_size = int(response.headers.get("content-length", 0))
+            downloaded = 0
+
+            for chunk in response.iter_content(chunk_size=8192):
+                tmp_file.write(chunk)
+                downloaded += len(chunk)
+                if progress_callback and total_size:
+                    pct = int(downloaded / total_size * 100)
+                    progress_callback(f"Downloading... {pct}%")
+
+            tmp_path = tmp_file.name
+
+        if progress_callback:
+            progress_callback("Extracting...")
+
+        # Remove old cached version
+        if API_CACHE_DIR.exists():
+            for item in API_CACHE_DIR.iterdir():
+                if item.is_dir() and item.name.startswith("graphora-api"):
+                    shutil.rmtree(item)
+
+        # Extract zip
+        with zipfile.ZipFile(tmp_path, "r") as zip_ref:
+            zip_ref.extractall(API_CACHE_DIR)
+
+        # Clean up temp file
+        os.unlink(tmp_path)
+
+        # Save installed version
+        set_config_value("embedded.installed_version", version)
+
+        return True, f"Successfully downloaded graphora-api {version}"
+
+    except requests.exceptions.RequestException as e:
+        return False, f"Download failed: {e}"
+    except zipfile.BadZipFile:
+        return False, "Downloaded file is not a valid zip"
+    except Exception as e:
+        return False, f"Installation failed: {e}"
+
+
+def _extract_deps_from_pyproject(pyproject_path: Path) -> list:
+    """Extract dependency list from pyproject.toml without installing the package itself.
+
+    This avoids `pip install -e .` which would register the `app` package
+    with incomplete subpackage discovery (packages=["app"]), shadowing
+    the sys.path-based imports that the CLI relies on.
+    """
+    try:
+        import tomllib
+    except ImportError:
+        try:
+            import tomli as tomllib
+        except ImportError:
+            # Fall back to basic parsing
+            return []
+
+    try:
+        with open(pyproject_path, "rb") as f:
+            data = tomllib.load(f)
+        return data.get("project", {}).get("dependencies", [])
+    except Exception:
+        return []
+
+
+def install_dependencies(progress_callback=None) -> Tuple[bool, str]:
+    """Install graphora-api dependencies.
+
+    IMPORTANT: We install only the dependencies, NOT the package itself.
+    The API's pyproject.toml uses packages=["app"] which only registers the
+    top-level app package without subpackages. This shadows the sys.path-based
+    import that the CLI uses, breaking imports like app.services.document_parser.
+
+    Args:
+        progress_callback: Optional callback for progress updates.
+
+    Returns:
+        Tuple of (success, message).
+    """
+    api_path = get_cached_api_path()
+    if not api_path:
+        return False, "graphora-api not downloaded"
+
+    requirements_file = api_path / "requirements.txt"
+    if not requirements_file.exists():
+        # Extract deps from pyproject.toml WITHOUT installing the package
+        pyproject_file = api_path / "pyproject.toml"
+        if pyproject_file.exists():
+            deps = _extract_deps_from_pyproject(pyproject_file)
+            if deps:
+                if progress_callback:
+                    progress_callback("Installing API dependencies...")
+                try:
+                    subprocess.check_call(
+                        [sys.executable, "-m", "pip", "install"] + deps + ["-q"],
+                        stdout=subprocess.DEVNULL,
+                    )
+                except subprocess.CalledProcessError:
+                    # Non-fatal: CLI extras already include key deps (aiofiles, google-genai)
+                    if progress_callback:
+                        progress_callback("Some API dependencies could not be installed (non-fatal)")
+    else:
+        if progress_callback:
+            progress_callback("Installing dependencies...")
+
+        try:
+            subprocess.check_call(
+                [sys.executable, "-m", "pip", "install", "-r", str(requirements_file), "-q"],
+                stdout=subprocess.DEVNULL,
+            )
+        except subprocess.CalledProcessError as e:
+            return False, f"Failed to install dependencies: {e}"
+
+    # Mark deps as installed
+    marker_file = api_path / DEPS_INSTALLED_MARKER
+    marker_file.touch()
+
+    return True, "Dependencies installed successfully"
+
+
+def setup_api(
+    version: Optional[str] = None,
+    channel: str = "main",
+    force: bool = False,
+    install_deps: bool = True,
+    progress_callback=None,
+) -> Tuple[bool, str]:
+    """Download and set up graphora-api.
+
+    This is the main entry point for setting up embedded mode.
+
+    Args:
+        version: Version to install (defaults to latest based on channel).
+        channel: Version channel - "stable", "nightly", or "main".
+        force: Force re-download.
+        install_deps: Whether to install Python dependencies.
+        progress_callback: Optional callback for progress updates.
+
+    Returns:
+        Tuple of (success, message).
+    """
+    # Download
+    success, message = download_api(version, channel, force, progress_callback)
+    if not success:
+        return False, message
+
+    # Install dependencies
+    if install_deps and not is_deps_installed():
+        if progress_callback:
+            progress_callback("Installing dependencies...")
+
+        success, dep_message = install_dependencies(progress_callback)
+        if not success:
+            return False, dep_message
+
+    if progress_callback:
+        progress_callback("Setup complete!")
+
+    return True, "graphora-api setup complete"
+
+
+def add_api_to_path() -> bool:
+    """Add graphora-api to Python path.
+
+    Returns:
+        True if successful, False otherwise.
+    """
+    api_path = get_api_path()
+    if not api_path:
+        return False
+
+    api_path_str = str(api_path)
+    if api_path_str not in sys.path:
+        sys.path.insert(0, api_path_str)
+
+    return True

graphora/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands."""

graphora/cli/commands/config_cmd.py

@@ -0,0 +1,225 @@
+"""Config command - manage CLI configuration."""
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich import print as rprint
+
+from graphora.cli.config import (
+    load_config,
+    get_config_value,
+    set_config_value,
+    CONFIG_FILE,
+    ensure_config_dir,
+    is_embedded_available,
+)
+from graphora.cli.api_manager import (
+    is_api_available,
+    get_installed_version,
+    setup_api,
+)
+
+app = typer.Typer(help="Manage Graphora CLI configuration")
+console = Console()
+
+
+@app.command("set")
+def config_set(
+    key: str = typer.Argument(..., help="Config key (e.g., llm.api_key)"),
+    value: str = typer.Argument(..., help="Value to set"),
+):
+    """Set a configuration value.
+
+    Examples:
+        graphora config set llm.api_key "your-api-key"
+        graphora config set llm.model "gemini-1.5-pro"
+        graphora config set defaults.mode "remote"
+        graphora config set api.url "https://api.graphora.io"
+    """
+    set_config_value(key, value)
+    rprint(f"[green]Set {key} = {_mask_sensitive(key, value)}[/green]")
+
+
+@app.command("get")
+def config_get(
+    key: str = typer.Argument(..., help="Config key to get"),
+):
+    """Get a configuration value.
+
+    Examples:
+        graphora config get llm.model
+        graphora config get defaults.mode
+    """
+    value = get_config_value(key)
+
+    if value is None:
+        rprint(f"[yellow]Key '{key}' is not set[/yellow]")
+        raise typer.Exit(1)
+
+    rprint(f"{key} = {_mask_sensitive(key, value)}")
+
+
+@app.command("show")
+def config_show():
+    """Show all configuration.
+
+    Displays all config values with sensitive data masked.
+    """
+    config = load_config()
+
+    table = Table(title="Graphora Configuration")
+    table.add_column("Key", style="cyan")
+    table.add_column("Value", style="green")
+
+    def add_rows(d: dict, prefix: str = ""):
+        for key, value in d.items():
+            full_key = f"{prefix}{key}" if prefix else key
+            if isinstance(value, dict):
+                add_rows(value, f"{full_key}.")
+            else:
+                display_value = _mask_sensitive(full_key, value)
+                table.add_row(full_key, str(display_value))
+
+    add_rows(config)
+
+    # Add embedded availability status
+    table.add_row("", "")  # Empty row separator
+    embedded_status = "[green]available[/green]" if is_embedded_available() else "[yellow]not installed[/yellow]"
+    table.add_row("[dim]embedded mode[/dim]", embedded_status)
+
+    console.print(table)
+    rprint(f"\n[dim]Config file: {CONFIG_FILE}[/dim]")
+
+
+@app.command("path")
+def config_path():
+    """Show the config file path."""
+    ensure_config_dir()
+    rprint(f"[cyan]{CONFIG_FILE}[/cyan]")
+
+
+@app.command("init")
+def config_init(
+    mode: str = typer.Option(
+        None, "--mode", "-m", help="CLI mode: 'embedded' or 'remote'"
+    ),
+    api_key: str = typer.Option(
+        None, "--api-key", "-k", help="LLM API key (for embedded mode)"
+    ),
+    api_path: str = typer.Option(
+        None, "--api-path", "-p", help="Custom path to graphora-api (optional, auto-downloads by default)"
+    ),
+    api_url: str = typer.Option(
+        None, "--api-url", "-u", help="Remote API URL (for remote mode)"
+    ),
+    auth_token: str = typer.Option(
+        None, "--auth-token", "-t", help="Auth token (for remote mode)"
+    ),
+    skip_download: bool = typer.Option(
+        False, "--skip-download", help="Skip auto-download of graphora-api"
+    ),
+):
+    """Initialize configuration interactively.
+
+    For embedded mode, graphora-api is automatically downloaded and cached.
+    You only need to provide your Gemini API key.
+
+    Examples:
+        graphora config init --api-key "your-gemini-key"
+        graphora config init --mode remote --api-url "https://api.graphora.io" --auth-token "token"
+        graphora config init --api-path "/path/to/local/graphora-api"  # Use local clone
+    """
+    import os
+
+    # Determine mode
+    if mode is None:
+        rprint("[cyan]Select execution mode:[/cyan]")
+        rprint("  [dim]embedded[/dim] - Run locally with Gemini API (recommended, auto-downloads)")
+        rprint("  [dim]remote[/dim]   - Use hosted Graphora API (requires auth token)")
+        mode = typer.prompt(
+            "\nMode (embedded/remote)",
+            default="embedded",
+        )
+        if mode not in ["embedded", "remote"]:
+            rprint(f"[red]Invalid mode: {mode}. Must be 'embedded' or 'remote'[/red]")
+            raise typer.Exit(1)
+
+    set_config_value("defaults.mode", mode)
+
+    if mode == "embedded":
+        # Handle custom api_path if provided
+        if api_path:
+            api_path = os.path.expanduser(api_path)
+            if os.path.isdir(api_path):
+                set_config_value("embedded.api_path", api_path)
+                rprint(f"[green]Using custom graphora-api path: {api_path}[/green]")
+            else:
+                rprint(f"[red]Directory not found: {api_path}[/red]")
+                raise typer.Exit(1)
+        elif not skip_download and not is_api_available():
+            # Auto-download graphora-api
+            rprint("\n[cyan]Setting up graphora-api...[/cyan]")
+
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                console=console,
+            ) as progress:
+                task = progress.add_task("Downloading graphora-api...", total=None)
+
+                def update_progress(msg):
+                    progress.update(task, description=msg)
+
+                success, message = setup_api(progress_callback=update_progress)
+
+            if success:
+                rprint(f"[green]{message}[/green]")
+            else:
+                rprint(f"[red]{message}[/red]")
+                rprint("\nYou can manually specify a path with --api-path")
+                raise typer.Exit(1)
+
+        # Get API key
+        if api_key is None:
+            rprint("")
+            api_key = typer.prompt("Enter your Gemini API key")
+        set_config_value("llm.api_key", api_key)
+
+        # Always update model to current default (fixes stale configs with deprecated models)
+        from graphora.cli.config import DEFAULT_CONFIG
+        set_config_value("llm.model", DEFAULT_CONFIG["llm"]["model"])
+        set_config_value("llm.provider", DEFAULT_CONFIG["llm"]["provider"])
+
+        rprint("\n[green]Embedded mode configuration complete![/green]")
+        version = get_installed_version()
+        if version:
+            rprint(f"  graphora-api: {version}")
+    else:
+        if api_url is None:
+            api_url = typer.prompt(
+                "Enter the Graphora API URL",
+                default="https://api.graphora.io"
+            )
+        if auth_token is None:
+            auth_token = typer.prompt("Enter your auth token")
+
+        set_config_value("api.url", api_url)
+        set_config_value("api.auth_token", auth_token)
+        rprint("\n[green]Remote mode configuration complete![/green]")
+
+    rprint("\nYou can now run:")
+    rprint("  [cyan]graphora extract document.pdf -o graph.json[/cyan]")
+
+
+def _mask_sensitive(key: str, value) -> str:
+    """Mask sensitive values like API keys."""
+    sensitive_keys = ["api_key", "password", "secret", "token"]
+
+    if any(s in key.lower() for s in sensitive_keys):
+        if value and isinstance(value, str) and len(value) > 8:
+            return f"{value[:4]}...{value[-4:]}"
+        elif value:
+            return "****"
+
+    return str(value) if value is not None else "(not set)"