cognee 0.2.3.dev1__py3-none-any.whl → 0.3.0__py3-none-any.whl

cognee/cli/_cognee.py

@@ -0,0 +1,273 @@
+import sys
+import os
+import argparse
+import signal
+import subprocess
+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.")
+
+
+class UiAction(argparse.Action):
+    def __init__(
+        self,
+        option_strings: Sequence[str],
+        dest: Any = argparse.SUPPRESS,
+        default: Any = argparse.SUPPRESS,
+        help: str = None,
+    ) -> None:
+        super(UiAction, 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:
+        # Set a flag to indicate UI should be started
+        global ACTION_EXECUTED
+        ACTION_EXECUTED = True
+        namespace.start_ui = True
+
+
+# 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",
+    )
+    parser.add_argument(
+        "-ui",
+        action=UiAction,
+        help="Start the cognee web UI interface",
+    )
+
+    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()
+
+    # Handle UI flag
+    if hasattr(args, "start_ui") and args.start_ui:
+        server_process = None
+
+        def signal_handler(signum, frame):
+            """Handle Ctrl+C and other termination signals"""
+            nonlocal server_process
+            fmt.echo("\nShutting down UI server...")
+            if server_process:
+                try:
+                    # Try graceful termination first
+                    server_process.terminate()
+                    try:
+                        server_process.wait(timeout=5)
+                        fmt.success("UI server stopped gracefully.")
+                    except subprocess.TimeoutExpired:
+                        # If graceful termination fails, force kill
+                        fmt.echo("Force stopping UI server...")
+                        server_process.kill()
+                        server_process.wait()
+                        fmt.success("UI server stopped.")
+                except Exception as e:
+                    fmt.warning(f"Error stopping server: {e}")
+            sys.exit(0)
+
+        # Set up signal handlers
+        signal.signal(signal.SIGINT, signal_handler)  # Ctrl+C
+        signal.signal(signal.SIGTERM, signal_handler)  # Termination request
+
+        try:
+            from cognee import start_ui
+
+            fmt.echo("Starting cognee UI...")
+            server_process = start_ui(host="localhost", port=3001, open_browser=True)
+
+            if server_process:
+                fmt.success("UI server started successfully!")
+                fmt.echo("The interface is available at: http://localhost:3001")
+                fmt.note("Press Ctrl+C to stop the server...")
+
+                try:
+                    # Keep the server running
+                    import time
+
+                    while server_process.poll() is None:  # While process is still running
+                        time.sleep(1)
+                except KeyboardInterrupt:
+                    # This shouldn't happen now due to signal handler, but kept for safety
+                    signal_handler(signal.SIGINT, None)
+
+                return 0
+            else:
+                fmt.error("Failed to start UI server. Check the logs above for details.")
+                return 1
+
+        except Exception as ex:
+            fmt.error(f"Error starting UI: {str(ex)}")
+            if debug.is_debug_enabled():
+                raise ex
+            return 1
+
+    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)