cognee 0.2.3.dev0__py3-none-any.whl → 0.2.4__py3-none-any.whl

cognee/cli/_cognee.py

@@ -0,0 +1,180 @@
+import sys
+import os
+import argparse
+from typing import Any, Sequence, Dict, Type, cast, List
+import click
+
+try:
+    import rich_argparse
+    from rich.markdown import Markdown
+
+    HAS_RICH = True
+except ImportError:
+    HAS_RICH = False
+
+from cognee.cli import SupportsCliCommand, DEFAULT_DOCS_URL
+from cognee.cli.config import CLI_DESCRIPTION
+from cognee.cli import debug
+import cognee.cli.echo as fmt
+from cognee.cli.exceptions import CliCommandException
+
+
+ACTION_EXECUTED = False
+
+
+def print_help(parser: argparse.ArgumentParser) -> None:
+    if not ACTION_EXECUTED:
+        parser.print_help()
+
+
+class DebugAction(argparse.Action):
+    def __init__(
+        self,
+        option_strings: Sequence[str],
+        dest: Any = argparse.SUPPRESS,
+        default: Any = argparse.SUPPRESS,
+        help: str = None,
+    ) -> None:
+        super(DebugAction, self).__init__(
+            option_strings=option_strings, dest=dest, default=default, nargs=0, help=help
+        )
+
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: Any,
+        option_string: str = None,
+    ) -> None:
+        # Enable debug mode for stack traces
+        debug.enable_debug()
+        fmt.note("Debug mode enabled. Full stack traces will be shown.")
+
+
+# Debug functionality is now in cognee.cli.debug module
+
+
+def _discover_commands() -> List[Type[SupportsCliCommand]]:
+    """Discover all available CLI commands"""
+    # Import commands dynamically to avoid early cognee initialization
+    commands = []
+
+    command_modules = [
+        ("cognee.cli.commands.add_command", "AddCommand"),
+        ("cognee.cli.commands.search_command", "SearchCommand"),
+        ("cognee.cli.commands.cognify_command", "CognifyCommand"),
+        ("cognee.cli.commands.delete_command", "DeleteCommand"),
+        ("cognee.cli.commands.config_command", "ConfigCommand"),
+    ]
+
+    for module_path, class_name in command_modules:
+        try:
+            module = __import__(module_path, fromlist=[class_name])
+            command_class = getattr(module, class_name)
+            commands.append(command_class)
+        except (ImportError, AttributeError) as e:
+            fmt.warning(f"Failed to load command {class_name}: {e}")
+
+    return commands
+
+
+def _create_parser() -> tuple[argparse.ArgumentParser, Dict[str, SupportsCliCommand]]:
+    parser = argparse.ArgumentParser(
+        description=f"{CLI_DESCRIPTION} Further help is available at {DEFAULT_DOCS_URL}."
+    )
+
+    # Get version dynamically
+    try:
+        from cognee.version import get_cognee_version
+
+        version = get_cognee_version()
+    except ImportError:
+        version = "unknown"
+
+    parser.add_argument("--version", action="version", version=f"cognee {version}")
+    parser.add_argument(
+        "--debug",
+        action=DebugAction,
+        help="Enable debug mode to show full stack traces on exceptions",
+    )
+
+    subparsers = parser.add_subparsers(title="Available commands", dest="command")
+
+    # Discover and install commands
+    command_classes = _discover_commands()
+    installed_commands: Dict[str, SupportsCliCommand] = {}
+
+    for command_class in command_classes:
+        command = command_class()
+        if command.command_string in installed_commands:
+            continue
+
+        command_parser = subparsers.add_parser(
+            command.command_string,
+            help=command.help_string,
+            description=command.description if hasattr(command, "description") else None,
+        )
+        command.configure_parser(command_parser)
+        installed_commands[command.command_string] = command
+
+    # Add rich formatting if available
+    if HAS_RICH:
+
+        def add_formatter_class(parser: argparse.ArgumentParser) -> None:
+            parser.formatter_class = rich_argparse.RichHelpFormatter
+
+            if parser.description:
+                parser.description = Markdown(parser.description, style="argparse.text")
+            for action in parser._actions:
+                if isinstance(action, argparse._SubParsersAction):
+                    for _subcmd, subparser in action.choices.items():
+                        add_formatter_class(subparser)
+
+        add_formatter_class(parser)
+
+    return parser, installed_commands
+
+
+def main() -> int:
+    """Main CLI entry point"""
+    parser, installed_commands = _create_parser()
+    args = parser.parse_args()
+
+    if cmd := installed_commands.get(args.command):
+        try:
+            cmd.execute(args)
+        except Exception as ex:
+            docs_url = cmd.docs_url if hasattr(cmd, "docs_url") else DEFAULT_DOCS_URL
+            error_code = -1
+            raiseable_exception = ex
+
+            # Handle CLI-specific exceptions
+            if isinstance(ex, CliCommandException):
+                error_code = ex.error_code
+                docs_url = ex.docs_url or docs_url
+                raiseable_exception = ex.raiseable_exception
+
+            # Print exception
+            if raiseable_exception:
+                fmt.error(str(ex))
+
+            fmt.note(f"Please refer to our docs at '{docs_url}' for further assistance.")
+
+            if debug.is_debug_enabled() and raiseable_exception:
+                raise raiseable_exception
+
+            return error_code
+    else:
+        print_help(parser)
+        return -1
+
+    return 0
+
+
+def _main() -> None:
+    """Script entry point"""
+    sys.exit(main())
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cognee/cli/commands/__init__.py

@@ -0,0 +1 @@
+# CLI Commands package

cognee/cli/commands/add_command.py

@@ -0,0 +1,80 @@
+import argparse
+import asyncio
+from typing import Optional
+
+from cognee.cli.reference import SupportsCliCommand
+from cognee.cli import DEFAULT_DOCS_URL
+import cognee.cli.echo as fmt
+from cognee.cli.exceptions import CliCommandException, CliCommandInnerException
+
+
+class AddCommand(SupportsCliCommand):
+    command_string = "add"
+    help_string = "Add data to Cognee for knowledge graph processing"
+    docs_url = DEFAULT_DOCS_URL
+    description = """
+Add data to Cognee for knowledge graph processing.
+
+This is the first step in the Cognee workflow - it ingests raw data and prepares it
+for processing. The function accepts various data formats including text, files, and
+binary streams, then stores them in a specified dataset for further processing.
+
+Supported Input Types:
+- **Text strings**: Direct text content
+- **File paths**: Local file paths (absolute paths starting with "/")  
+- **File URLs**: "file:///absolute/path" or "file://relative/path"
+- **S3 paths**: "s3://bucket-name/path/to/file"
+- **Lists**: Multiple files or text strings in a single call
+
+Supported File Formats:
+- Text files (.txt, .md, .csv)
+- PDFs (.pdf)
+- Images (.png, .jpg, .jpeg) - extracted via OCR/vision models
+- Audio files (.mp3, .wav) - transcribed to text
+- Code files (.py, .js, .ts, etc.) - parsed for structure and content
+- Office documents (.docx, .pptx)
+
+After adding data, use `cognee cognify` to process it into knowledge graphs.
+    """
+
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "data",
+            nargs="+",
+            help="Data to add: text content, file paths (/path/to/file), file URLs (file://path), S3 paths (s3://bucket/file), or mix of these",
+        )
+        parser.add_argument(
+            "--dataset-name",
+            "-d",
+            default="main_dataset",
+            help="Dataset name to organize your data (default: main_dataset)",
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        try:
+            # Import cognee here to avoid circular imports
+            import cognee
+
+            fmt.echo(f"Adding {len(args.data)} item(s) to dataset '{args.dataset_name}'...")
+
+            # Run the async add function
+            async def run_add():
+                try:
+                    # Pass all data items as a list to cognee.add if multiple items
+                    if len(args.data) == 1:
+                        data_to_add = args.data[0]
+                    else:
+                        data_to_add = args.data
+
+                    fmt.echo("Processing data...")
+                    await cognee.add(data=data_to_add, dataset_name=args.dataset_name)
+                    fmt.success(f"Successfully added data to dataset '{args.dataset_name}'")
+                except Exception as e:
+                    raise CliCommandInnerException(f"Failed to add data: {str(e)}")
+
+            asyncio.run(run_add())
+
+        except Exception as e:
+            if isinstance(e, CliCommandInnerException):
+                raise CliCommandException(str(e), error_code=1)
+            raise CliCommandException(f"Error adding data: {str(e)}", error_code=1)

cognee/cli/commands/cognify_command.py

@@ -0,0 +1,128 @@
+import argparse
+import asyncio
+from typing import Optional
+
+from cognee.cli.reference import SupportsCliCommand
+from cognee.cli import DEFAULT_DOCS_URL
+from cognee.cli.config import CHUNKER_CHOICES
+import cognee.cli.echo as fmt
+from cognee.cli.exceptions import CliCommandException, CliCommandInnerException
+
+
+class CognifyCommand(SupportsCliCommand):
+    command_string = "cognify"
+    help_string = "Transform ingested data into a structured knowledge graph"
+    docs_url = DEFAULT_DOCS_URL
+    description = """
+Transform ingested data into a structured knowledge graph.
+
+This is the core processing step in Cognee that converts raw text and documents
+into an intelligent knowledge graph. It analyzes content, extracts entities and
+relationships, and creates semantic connections for enhanced search and reasoning.
+
+Processing Pipeline:
+1. **Document Classification**: Identifies document types and structures
+2. **Permission Validation**: Ensures user has processing rights  
+3. **Text Chunking**: Breaks content into semantically meaningful segments
+4. **Entity Extraction**: Identifies key concepts, people, places, organizations
+5. **Relationship Detection**: Discovers connections between entities
+6. **Graph Construction**: Builds semantic knowledge graph with embeddings
+7. **Content Summarization**: Creates hierarchical summaries for navigation
+
+After successful cognify processing, use `cognee search` to query the knowledge graph.
+    """
+
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--datasets",
+            "-d",
+            nargs="*",
+            help="Dataset name(s) to process. Processes all available data if not specified. Can be multiple: --datasets dataset1 dataset2",
+        )
+        parser.add_argument(
+            "--chunk-size",
+            type=int,
+            help="Maximum tokens per chunk. Auto-calculated based on LLM if not specified (~512-8192 tokens)",
+        )
+        parser.add_argument(
+            "--ontology-file", help="Path to RDF/OWL ontology file for domain-specific entity types"
+        )
+        parser.add_argument(
+            "--chunker",
+            choices=CHUNKER_CHOICES,
+            default="TextChunker",
+            help="Text chunking strategy (default: TextChunker)",
+        )
+        parser.add_argument(
+            "--background",
+            "-b",
+            action="store_true",
+            help="Run processing in background and return immediately (recommended for large datasets)",
+        )
+        parser.add_argument(
+            "--verbose", "-v", action="store_true", help="Show detailed progress information"
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        try:
+            # Import cognee here to avoid circular imports
+            import cognee
+
+            # Prepare datasets parameter
+            datasets = args.datasets if args.datasets else None
+            dataset_msg = f" for datasets {datasets}" if datasets else " for all available data"
+            fmt.echo(f"Starting cognification{dataset_msg}...")
+
+            if args.verbose:
+                fmt.note("This process will analyze your data and build knowledge graphs.")
+                fmt.note("Depending on data size, this may take several minutes.")
+                if args.background:
+                    fmt.note(
+                        "Running in background mode - the process will continue after this command exits."
+                    )
+
+            # Prepare chunker parameter - will be handled in the async function
+
+            # Run the async cognify function
+            async def run_cognify():
+                try:
+                    # Import chunker classes here
+                    from cognee.modules.chunking.TextChunker import TextChunker
+
+                    chunker_class = TextChunker  # Default
+                    if args.chunker == "LangchainChunker":
+                        try:
+                            from cognee.modules.chunking.LangchainChunker import LangchainChunker
+
+                            chunker_class = LangchainChunker
+                        except ImportError:
+                            fmt.warning("LangchainChunker not available, using TextChunker")
+
+                    result = await cognee.cognify(
+                        datasets=datasets,
+                        chunker=chunker_class,
+                        chunk_size=args.chunk_size,
+                        ontology_file_path=args.ontology_file,
+                        run_in_background=args.background,
+                    )
+                    return result
+                except Exception as e:
+                    raise CliCommandInnerException(f"Failed to cognify: {str(e)}")
+
+            result = asyncio.run(run_cognify())
+
+            if args.background:
+                fmt.success("Cognification started in background!")
+                if args.verbose and result:
+                    fmt.echo(
+                        "Background processing initiated. Use pipeline monitoring to track progress."
+                    )
+            else:
+                fmt.success("Cognification completed successfully!")
+                if args.verbose and result:
+                    fmt.echo(f"Processing results: {result}")
+
+        except Exception as e:
+            if isinstance(e, CliCommandInnerException):
+                raise CliCommandException(str(e), error_code=1)
+            raise CliCommandException(f"Error during cognification: {str(e)}", error_code=1)

cognee/cli/commands/config_command.py

@@ -0,0 +1,225 @@
+import argparse
+import json
+from typing import Optional, Any
+
+from cognee.cli.reference import SupportsCliCommand
+from cognee.cli import DEFAULT_DOCS_URL
+import cognee.cli.echo as fmt
+from cognee.cli.exceptions import CliCommandException, CliCommandInnerException
+
+
+class ConfigCommand(SupportsCliCommand):
+    command_string = "config"
+    help_string = "Manage cognee configuration settings"
+    docs_url = DEFAULT_DOCS_URL
+    description = """
+The `cognee config` command allows you to view and modify configuration settings.
+
+You can:
+- View all current configuration settings
+- Get specific configuration values  
+- Set configuration values
+- Unset (reset to default) specific configuration values
+- Reset all configuration to defaults
+
+Configuration changes will affect how cognee processes and stores data.
+    """
+
+    def configure_parser(self, parser: argparse.ArgumentParser) -> None:
+        subparsers = parser.add_subparsers(dest="config_action", help="Configuration actions")
+
+        # Get command
+        get_parser = subparsers.add_parser("get", help="Get configuration value(s)")
+        get_parser.add_argument(
+            "key", nargs="?", help="Configuration key to retrieve (shows all if not specified)"
+        )
+
+        # Set command
+        set_parser = subparsers.add_parser("set", help="Set configuration value")
+        set_parser.add_argument("key", help="Configuration key to set")
+        set_parser.add_argument("value", help="Configuration value to set")
+
+        # List command
+        subparsers.add_parser("list", help="List all configuration keys")
+
+        # Unset command
+        unset_parser = subparsers.add_parser("unset", help="Remove/unset a configuration value")
+        unset_parser.add_argument("key", help="Configuration key to unset")
+        unset_parser.add_argument(
+            "--force", "-f", action="store_true", help="Skip confirmation prompt"
+        )
+
+        # Reset command
+        reset_parser = subparsers.add_parser("reset", help="Reset configuration to defaults")
+        reset_parser.add_argument(
+            "--force", "-f", action="store_true", help="Skip confirmation prompt"
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        try:
+            # Import cognee here to avoid circular imports
+            import cognee
+
+            if not hasattr(args, "config_action") or args.config_action is None:
+                fmt.error("Please specify a config action: get, set, unset, list, or reset")
+                return
+
+            if args.config_action == "get":
+                self._handle_get(args)
+            elif args.config_action == "set":
+                self._handle_set(args)
+            elif args.config_action == "unset":
+                self._handle_unset(args)
+            elif args.config_action == "list":
+                self._handle_list(args)
+            elif args.config_action == "reset":
+                self._handle_reset(args)
+            else:
+                fmt.error(f"Unknown config action: {args.config_action}")
+
+        except Exception as e:
+            if isinstance(e, CliCommandInnerException):
+                raise CliCommandException(str(e), error_code=1)
+            raise CliCommandException(f"Error managing configuration: {str(e)}", error_code=1)
+
+    def _handle_get(self, args: argparse.Namespace) -> None:
+        try:
+            import cognee
+
+            if args.key:
+                # Get specific key
+                try:
+                    if hasattr(cognee.config, "get"):
+                        value = cognee.config.get(args.key)
+                        fmt.echo(f"{args.key}: {value}")
+                    else:
+                        fmt.error("Configuration retrieval not implemented yet")
+                        fmt.note(
+                            "The config system currently only supports setting values, not retrieving them"
+                        )
+                        fmt.note(f"To set this value: 'cognee config set {args.key} <value>'")
+                except Exception:
+                    fmt.error(f"Configuration key '{args.key}' not found or retrieval failed")
+            else:
+                # Get all configuration
+                try:
+                    if hasattr(cognee.config, "get_all"):
+                        config_dict = cognee.config.get_all()
+                        if config_dict:
+                            fmt.echo("Current configuration:")
+                            for key, value in config_dict.items():
+                                fmt.echo(f"  {key}: {value}")
+                        else:
+                            fmt.echo("No configuration settings found")
+                    else:
+                        fmt.error("Configuration viewing not implemented yet")
+                        fmt.note(
+                            "The config system currently only supports setting values, not retrieving them"
+                        )
+                        fmt.note("Available commands: 'cognee config set <key> <value>'")
+                except Exception:
+                    fmt.error("Failed to retrieve configuration")
+                    fmt.note("Configuration viewing not fully implemented yet")
+
+        except Exception as e:
+            raise CliCommandInnerException(f"Failed to get configuration: {str(e)}")
+
+    def _handle_set(self, args: argparse.Namespace) -> None:
+        try:
+            import cognee
+
+            # Try to parse value as JSON, otherwise treat as string
+            try:
+                value = json.loads(args.value)
+            except json.JSONDecodeError:
+                value = args.value
+
+            try:
+                cognee.config.set(args.key, value)
+                fmt.success(f"Set {args.key} = {value}")
+            except Exception:
+                fmt.error(f"Failed to set configuration key '{args.key}'")
+
+        except Exception as e:
+            raise CliCommandInnerException(f"Failed to set configuration: {str(e)}")
+
+    def _handle_unset(self, args: argparse.Namespace) -> None:
+        try:
+            import cognee
+
+            # Confirm unset unless forced
+            if not args.force:
+                if not fmt.confirm(f"Unset configuration key '{args.key}'?"):
+                    fmt.echo("Unset cancelled.")
+                    return
+
+            # Since the config system doesn't have explicit unset methods,
+            # we need to map config keys to their reset/default behaviors
+            config_key_mappings = {
+                # LLM configuration
+                "llm_provider": ("set_llm_provider", "openai"),
+                "llm_model": ("set_llm_model", "gpt-5-mini"),
+                "llm_api_key": ("set_llm_api_key", ""),
+                "llm_endpoint": ("set_llm_endpoint", ""),
+                # Database configuration
+                "graph_database_provider": ("set_graph_database_provider", "kuzu"),
+                "vector_db_provider": ("set_vector_db_provider", "lancedb"),
+                "vector_db_url": ("set_vector_db_url", ""),
+                "vector_db_key": ("set_vector_db_key", ""),
+                # Chunking configuration
+                "chunk_size": ("set_chunk_size", 1500),
+                "chunk_overlap": ("set_chunk_overlap", 10),
+            }
+
+            if args.key in config_key_mappings:
+                method_name, default_value = config_key_mappings[args.key]
+
+                try:
+                    # Get the method and call it with the default value
+                    method = getattr(cognee.config, method_name)
+                    method(default_value)
+                    fmt.success(f"Unset {args.key} (reset to default: {default_value})")
+                except AttributeError:
+                    fmt.error(f"Configuration method '{method_name}' not found")
+                except Exception as e:
+                    fmt.error(f"Failed to unset '{args.key}': {str(e)}")
+            else:
+                fmt.error(f"Unknown configuration key '{args.key}'")
+                fmt.note("Available keys: " + ", ".join(config_key_mappings.keys()))
+                fmt.note("Use 'cognee config list' to see all available configuration options")
+
+        except Exception as e:
+            raise CliCommandInnerException(f"Failed to unset configuration: {str(e)}")
+
+    def _handle_list(self, args: argparse.Namespace) -> None:
+        try:
+            import cognee
+
+            # This would need to be implemented in cognee.config
+            fmt.note("Available configuration keys:")
+            fmt.echo("  llm_provider, llm_model, llm_api_key, llm_endpoint")
+            fmt.echo("  graph_database_provider, vector_db_provider")
+            fmt.echo("  vector_db_url, vector_db_key")
+            fmt.echo("  chunk_size, chunk_overlap")
+            fmt.echo("")
+            fmt.echo("Commands:")
+            fmt.echo("  cognee config get [key]     - View configuration")
+            fmt.echo("  cognee config set <key> <value> - Set configuration")
+            fmt.echo("  cognee config unset <key>   - Reset key to default")
+            fmt.echo("  cognee config reset         - Reset all to defaults")
+
+        except Exception as e:
+            raise CliCommandInnerException(f"Failed to list configuration: {str(e)}")
+
+    def _handle_reset(self, args: argparse.Namespace) -> None:
+        try:
+            if not args.force:
+                if not fmt.confirm("Reset all configuration to defaults?"):
+                    fmt.echo("Reset cancelled.")
+                    return
+
+            fmt.note("Configuration reset not fully implemented yet")
+            fmt.echo("This would reset all settings to their default values")
+
+        except Exception as e:
+            raise CliCommandInnerException(f"Failed to reset configuration: {str(e)}")