diff --git a/cookbook/advanced/05_Multi_Format_Export.ipynb b/cookbook/advanced/05_Multi_Format_Export.ipynb index edd1c196..dcfb9b23 100644 --- a/cookbook/advanced/05_Multi_Format_Export.ipynb +++ b/cookbook/advanced/05_Multi_Format_Export.ipynb @@ -6,14 +6,37 @@ "source": [ "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Hawksight-AI/semantica/blob/main/cookbook/advanced/05_Multi_Format_Export.ipynb)\n", "\n", - "# Multi-Format Export\n", + "# Advanced Multi-Format Export\n", "\n", "## Overview\n", "\n", - "Export knowledge graphs and data to multiple formats: JSON, RDF, CSV, Graph formats, OWL, and Vector formats.\n", + "This advanced notebook demonstrates comprehensive export capabilities of Semantica's Export Module, covering all **8 export formats** plus report generation. You'll learn to export the same knowledge graph to multiple formats simultaneously, use advanced features, and leverage the method registry system.\n", "\n", "**Documentation**: [API Reference](https://semantica.readthedocs.io/reference/export/)\n", "\n", + "### What You'll Learn\n", + "\n", + "- Export knowledge graphs to all 8 supported formats\n", + "- Use exporter classes directly for fine-grained control\n", + "- Generate professional reports in multiple formats\n", + "- Work with RDF serialization, validation, and namespace management\n", + "- Register and use custom export methods\n", + "- Configure export settings programmatically\n", + "- Export vectors and embeddings for vector stores\n", + "- Export to graph databases using LPG format\n", + "\n", + "### Export Formats Covered\n", + "\n", + "1. **JSON/JSON-LD** - Standard JSON and JSON-LD formats\n", + "2. **RDF** - Turtle, RDF/XML, JSON-LD, N-Triples, N3\n", + "3. **CSV** - Tabular format for entities and relationships\n", + "4. **Graph Formats** - GraphML, GEXF, DOT for visualization tools\n", + "5. **OWL** - OWL/XML and Turtle for ontologies\n", + "6. **Vector** - JSON, NumPy, Binary, FAISS for vector stores\n", + "7. **LPG** - Cypher and LPG for graph databases\n", + "8. **YAML** - Semantic network and schema YAML\n", + "9. **Reports** - HTML, Markdown, JSON, Text reports\n", + "\n", "## Installation\n", "\n", "Install Semantica from PyPI:\n", @@ -31,19 +54,13 @@ "metadata": {}, "outputs": [], "source": [ - "from semantica.export import (\n", - " JSONExporter,\n", - " RDFExporter,\n", - " CSVExporter,\n", - " GraphExporter,\n", - " OWLExporter,\n", - " VectorExporter\n", - ")\n", + "# Import core modules for building knowledge graph\n", "from semantica.kg import GraphBuilder\n", "from semantica.embeddings import EmbeddingGenerator\n", "from semantica.ontology import OntologyGenerator\n", "import os\n", "\n", + "# Create exports directory\n", "os.makedirs(\"exports\", exist_ok=True)\n" ] }, @@ -51,7 +68,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Step 1: Create Sample Knowledge Graph and Data\n" + "## Step 1: Create Sample Knowledge Graph and Data\n", + "\n", + "Create a sample knowledge graph with entities, relationships, embeddings, and an ontology for comprehensive export demonstrations.\n" ] }, { @@ -87,119 +106,15 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Step 2: Export to JSON\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "json_exporter = JSONExporter()\n", - "json_exporter.export(knowledge_graph, \"exports/output.json\")\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Step 3: Export to RDF\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "rdf_exporter = RDFExporter()\n", - "rdf_exporter.export(knowledge_graph, \"exports/output.rdf\")\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Step 4: Export to CSV\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "csv_exporter = CSVExporter()\n", - "csv_exporter.export(knowledge_graph, \"exports/output.csv\")\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Step 5: Export to Graph Formats (GraphML, GEXF)\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "graph_exporter = GraphExporter()\n", - "graph_exporter.export(knowledge_graph, \"exports/output.graphml\", format=\"graphml\")\n", - "graph_exporter.export(knowledge_graph, \"exports/output.gexf\", format=\"gexf\")\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Step 6: Export to OWL\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "owl_exporter = OWLExporter()\n", - "owl_exporter.export(ontology, \"exports/output.owl\")\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Step 7: Export to Vector Formats\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "vector_exporter = VectorExporter()\n", - "vector_exporter.export(embeddings, \"exports/output.vectors\")\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Summary\n", + "## Step 2: Export to JSON\n", "\n", - "Export formats:\n", - "- JSON\n", - "- RDF\n", - "- CSV\n", - "- GraphML\n", - "- GEXF\n", - "- OWL\n", - "- Vector format\n" + "Export knowledge graph to JSON format using both the class and convenience function approaches.\n", + "\n", + "**JSONExporter Features:**\n", + "- Standard JSON serialization\n", + "- JSON-LD format support with @context\n", + "- Configurable indentation\n", + "- Metadata and provenance tracking\n" ] }, { @@ -208,21 +123,492 @@ "metadata": {}, "outputs": [], "source": [ + "from semantica.export import JSONExporter\n", + "\n", + "# Create JSON exporter with custom settings\n", + "json_exporter = JSONExporter(indent=2, include_metadata=True)\n", + "\n", + "# Export to JSON format\n", + "json_exporter.export_knowledge_graph(knowledge_graph, \"exports/output.json\")\n", + "\n", + "# Export to JSON-LD format\n", + "json_exporter.export_knowledge_graph(knowledge_graph, \"exports/output.jsonld\", format=\"json-ld\")\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Step 3: Export to RDF\n", + "\n", + "Export knowledge graph to multiple RDF formats (Turtle, RDF/XML, JSON-LD, N-Triples).\n", + "\n", + "**RDFExporter Features:**\n", + "- Multiple RDF format support (Turtle, RDF/XML, JSON-LD, N-Triples, N3)\n", + "- Namespace management\n", + "- RDF validation\n", + "- Format conversion capabilities\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from semantica.export import RDFExporter, RDFSerializer, RDFValidator\n", + "\n", + "# Create RDF exporter\n", + "rdf_exporter = RDFExporter()\n", + "\n", + "# Export to Turtle format (human-readable)\n", + "rdf_exporter.export_knowledge_graph(knowledge_graph, \"exports/output.ttl\", format=\"turtle\")\n", + "\n", + "# Export to RDF/XML format\n", + "rdf_exporter.export_knowledge_graph(knowledge_graph, \"exports/output.rdf\", format=\"rdfxml\")\n", + "\n", + "# Export to JSON-LD format\n", + "rdf_exporter.export_knowledge_graph(knowledge_graph, \"exports/output.jsonld\", format=\"jsonld\")\n", + "\n", + "# Export to N-Triples format\n", + "rdf_exporter.export_knowledge_graph(knowledge_graph, \"exports/output.nt\", format=\"ntriples\")\n", + "\n", + "# Using RDFSerializer for format conversion\n", + "serializer = RDFSerializer()\n", + "rdf_data = serializer.convert_kg_to_rdf(knowledge_graph)\n", + "turtle_string = serializer.serialize_to_turtle(rdf_data)\n", + "\n", + "# Using RDFValidator for validation\n", + "validator = RDFValidator()\n", + "validation_result = validator.validate_rdf_syntax(turtle_string, format=\"turtle\")\n", + "print(f\"RDF validation: {validation_result.get('is_valid', False)}\")\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Step 4: Export to CSV\n", + "\n", + "Export knowledge graph to CSV format for tabular analysis.\n", + "\n", + "**CSVExporter Features:**\n", + "- Separate files for entities and relationships\n", + "- Configurable delimiter (comma, tab, semicolon)\n", + "- Automatic header generation\n", + "- Metadata serialization\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from semantica.export import CSVExporter\n", + "\n", + "# Create CSV exporter with custom delimiter\n", + "csv_exporter = CSVExporter(delimiter=\",\")\n", + "\n", + "# Export complete knowledge graph\n", + "csv_exporter.export_knowledge_graph(knowledge_graph, \"exports/output.csv\")\n", + "\n", + "# Export entities separately\n", + "entities = knowledge_graph.get(\"entities\", [])\n", + "csv_exporter.export_entities(entities, \"exports/entities.csv\")\n", + "\n", + "# Export relationships separately\n", + "relationships = knowledge_graph.get(\"relationships\", [])\n", + "csv_exporter.export_relationships(relationships, \"exports/relationships.csv\")\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Step 5: Export to Graph Formats (GraphML, GEXF, DOT)\n", + "\n", + "Export knowledge graph to graph formats for visualization tools.\n", + "\n", + "**GraphExporter Features:**\n", + "- GraphML format (Cytoscape, yEd)\n", + "- GEXF format (Gephi)\n", + "- DOT format (Graphviz)\n", + "- Node and edge attribute mapping\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from semantica.export import GraphExporter\n", + "\n", + "# Create graph exporter\n", + "graph_exporter = GraphExporter()\n", + "\n", + "# Export to GraphML format (for Cytoscape, yEd)\n", + "graph_exporter.export_knowledge_graph(knowledge_graph, \"exports/output.graphml\", format=\"graphml\")\n", + "\n", + "# Export to GEXF format (for Gephi)\n", + "graph_exporter.export_knowledge_graph(knowledge_graph, \"exports/output.gexf\", format=\"gexf\")\n", + "\n", + "# Export to DOT format (for Graphviz)\n", + "graph_exporter.export_knowledge_graph(knowledge_graph, \"exports/output.dot\", format=\"dot\")\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Step 6: Export to OWL\n", + "\n", + "Export ontology to OWL format. **Note:** OWLExporter expects an ontology structure, not a knowledge graph.\n", + "\n", + "**OWLExporter Features:**\n", + "- OWL/XML format\n", + "- OWL in Turtle format\n", + "- Class hierarchy export\n", + "- Property definition export\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from semantica.export import OWLExporter\n", + "\n", + "# Create OWL exporter with custom URI and version\n", + "owl_exporter = OWLExporter(ontology_uri=\"https://example.org/ontology/\", version=\"1.0\")\n", + "\n", + "# Export complete ontology to OWL/XML\n", + "owl_exporter.export(ontology, \"exports/output.owl\", format=\"owl-xml\")\n", + "\n", + "# Export to OWL in Turtle format\n", + "owl_exporter.export(ontology, \"exports/output_owl.ttl\", format=\"turtle\")\n", + "\n", + "# Export only classes\n", + "classes = ontology.get(\"classes\", [])\n", + "owl_exporter.export_classes(classes, \"exports/classes.owl\")\n", + "\n", + "# Export only properties\n", + "properties = ontology.get(\"object_properties\", [])\n", + "owl_exporter.export_properties(properties, \"exports/properties.owl\", property_type=\"object\")\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Step 7: Export to Vector Formats\n", + "\n", + "Export vector embeddings to various formats for vector stores.\n", + "\n", + "**VectorExporter Features:**\n", + "- JSON format\n", + "- NumPy format\n", + "- Binary format\n", + "- FAISS format\n", + "- Vector store integration (Pinecone, Weaviate, Qdrant)\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from semantica.export import VectorExporter\n", + "\n", + "# Create vector exporter\n", + "vector_exporter = VectorExporter()\n", + "\n", + "# Export to JSON format\n", + "vector_exporter.export(embeddings, \"exports/output_vectors.json\", format=\"json\")\n", + "\n", + "# Export to NumPy format\n", + "vector_exporter.export(embeddings, \"exports/output_vectors.npy\", format=\"numpy\")\n", + "\n", + "# Export to Binary format\n", + "vector_exporter.export(embeddings, \"exports/output_vectors.bin\", format=\"binary\")\n", + "\n", + "# Export to FAISS format\n", + "vector_exporter.export(embeddings, \"exports/output_vectors.faiss\", format=\"faiss\")\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Step 8: Export to LPG (Labeled Property Graph)\n", + "\n", + "Export knowledge graph to LPG format for graph databases like Neo4j and Memgraph.\n", + "\n", + "**LPGExporter Features:**\n", + "- Cypher query format\n", + "- Labeled Property Graph format\n", + "- Batch node/relationship export\n", + "- Index generation\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from semantica.export import LPGExporter\n", + "\n", + "# Create LPG exporter\n", + "lpg_exporter = LPGExporter()\n", + "\n", + "# Export to Cypher format (for Neo4j, Memgraph)\n", + "lpg_exporter.export_knowledge_graph(knowledge_graph, \"exports/output.cypher\", format=\"cypher\")\n", + "\n", + "# Export to LPG format\n", + "lpg_exporter.export_knowledge_graph(knowledge_graph, \"exports/output.lpg\", format=\"lpg\")\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Step 9: Export to YAML\n", + "\n", + "Export semantic networks and schemas to YAML format.\n", + "\n", + "**YAML Exporter Features:**\n", + "- Semantic network YAML export\n", + "- Schema YAML export\n", + "- Human-readable format\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from semantica.export import SemanticNetworkYAMLExporter, YAMLSchemaExporter\n", + "\n", + "# Using SemanticNetworkYAMLExporter for knowledge graphs\n", + "yaml_exporter = SemanticNetworkYAMLExporter()\n", + "yaml_exporter.export(knowledge_graph, \"exports/output_network.yaml\")\n", + "\n", + "# Using YAMLSchemaExporter for ontology schemas\n", + "schema_exporter = YAMLSchemaExporter()\n", + "schema_exporter.export(ontology, \"exports/output_schema.yaml\")\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Step 10: Generate Reports\n", + "\n", + "Generate professional reports in multiple formats using ReportGenerator.\n", + "\n", + "**ReportGenerator Features:**\n", + "- HTML reports with styling\n", + "- Markdown reports\n", + "- JSON reports\n", + "- Plain text reports\n", + "- Quality metrics aggregation\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from semantica.export import ReportGenerator\n", + "\n", + "# Prepare report data\n", + "report_data = {\n", + " \"title\": \"Knowledge Graph Export Report\",\n", + " \"summary\": \"Comprehensive export of knowledge graph to multiple formats\",\n", + " \"knowledge_graph\": {\n", + " \"entities\": len(knowledge_graph.get(\"entities\", [])),\n", + " \"relationships\": len(knowledge_graph.get(\"relationships\", []))\n", + " },\n", + " \"formats_exported\": [\"JSON\", \"RDF\", \"CSV\", \"GraphML\", \"GEXF\", \"OWL\", \"Vector\", \"LPG\", \"YAML\"],\n", + " \"export_timestamp\": \"2024-01-01T00:00:00Z\"\n", + "}\n", + "\n", + "# Create report generator\n", + "report_generator = ReportGenerator()\n", + "\n", + "# Generate HTML report\n", + "report_generator.generate_report(report_data, \"exports/report.html\", format=\"html\")\n", + "\n", + "# Generate Markdown report\n", + "report_generator.generate_report(report_data, \"exports/report.md\", format=\"markdown\")\n", + "\n", + "# Generate JSON report\n", + "report_generator.generate_report(report_data, \"exports/report.json\", format=\"json\")\n", + "\n", + "# Generate Text report\n", + "report_generator.generate_report(report_data, \"exports/report.txt\", format=\"text\")\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Step 11: Method Registry and Custom Methods\n", + "\n", + "Register and use custom export methods with the MethodRegistry system.\n", + "\n", + "**MethodRegistry Features:**\n", + "- Register custom export methods\n", + "- List available methods\n", + "- Get methods by name\n", + "- Unregister methods\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from semantica.export import MethodRegistry, method_registry, JSONExporter\n", + "\n", + "# Define a custom export method\n", + "def custom_json_export(data, file_path, **kwargs):\n", + " \"\"\"Custom JSON export with additional formatting.\"\"\"\n", + " import json\n", + " with open(file_path, 'w') as f:\n", + " json.dump(data, f, indent=4, sort_keys=True)\n", + " print(f\"Custom export completed: {file_path}\")\n", + "\n", + "# Register custom method\n", + "MethodRegistry.register(\"json\", \"custom_formatted\", custom_json_export)\n", + "\n", + "# List all available methods\n", + "all_methods = method_registry.list_all()\n", + "print(\"Available methods:\", all_methods)\n", + "\n", + "# List methods for specific task\n", + "json_methods = method_registry.list_all(\"json\")\n", + "print(\"JSON methods:\", json_methods)\n", + "\n", + "# Use registered method with JSONExporter\n", + "json_exporter = JSONExporter()\n", + "# The custom method can be used via the registry system\n", + "custom_method = method_registry.get(\"json\", \"custom_formatted\")\n", + "if custom_method:\n", + " custom_method(knowledge_graph, \"exports/custom_output.json\")\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Step 12: Configuration Management\n", + "\n", + "Configure export settings using ExportConfig.\n", + "\n", + "**ExportConfig Features:**\n", + "- Environment variable support\n", + "- Config file support\n", + "- Programmatic configuration\n", + "- Method-specific configuration\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from semantica.export import ExportConfig, export_config, JSONExporter\n", + "\n", + "# Get current configuration\n", + "config = export_config.get(\"default\")\n", + "print(\"Default config:\", config)\n", + "\n", + "# Set configuration programmatically\n", + "export_config.set(\"json\", {\"indent\": 4, \"include_metadata\": True})\n", + "export_config.set(\"rdf\", {\"format\": \"turtle\", \"base_uri\": \"https://example.org/\"})\n", + "\n", + "# Get method-specific configuration\n", + "json_config = export_config.get_method_config(\"json\")\n", + "print(\"JSON config:\", json_config)\n", + "\n", + "# Set method-specific configuration\n", + "export_config.set_method_config(\"csv\", {\"delimiter\": \"\\t\"})\n", + "\n", + "# Use configured settings\n", + "json_exporter = JSONExporter(**export_config.get_method_config(\"json\"))\n", + "json_exporter.export_knowledge_graph(knowledge_graph, \"exports/output_configured.json\")\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "## Step 13: Verify All Exports\n", + "\n", + "Verify that all exported files were created successfully.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# List all exported files\n", "export_files = [\n", " \"exports/output.json\",\n", + " \"exports/output.jsonld\",\n", + " \"exports/output.ttl\",\n", " \"exports/output.rdf\",\n", + " \"exports/output.nt\",\n", " \"exports/output.csv\",\n", + " \"exports/entities.csv\",\n", + " \"exports/relationships.csv\",\n", " \"exports/output.graphml\",\n", " \"exports/output.gexf\",\n", + " \"exports/output.dot\",\n", " \"exports/output.owl\",\n", - " \"exports/output.vectors\"\n", + " \"exports/output_owl.ttl\",\n", + " \"exports/output_vectors.json\",\n", + " \"exports/output_vectors.npy\",\n", + " \"exports/output.cypher\",\n", + " \"exports/output_network.yaml\",\n", + " \"exports/output_schema.yaml\",\n", + " \"exports/report.html\",\n", + " \"exports/report.md\",\n", + " \"exports/report.json\",\n", + " \"exports/report.txt\"\n", "]\n", "\n", + "print(\"📊 Export Summary:\")\n", + "print(\"=\" * 60)\n", "for file in export_files:\n", " if os.path.exists(file):\n", " size = os.path.getsize(file)\n", - " print(f\"{file} ({size} bytes)\")\n" + " print(f\"✅ {file:50} ({size:>10,} bytes)\")\n", + " else:\n", + " print(f\"❌ {file:50} (not found)\")\n", + "\n", + "print(\"=\" * 60)\n", + "print(f\"Total files checked: {len(export_files)}\")\n", + "print(f\"Files created: {sum(1 for f in export_files if os.path.exists(f))}\")\n" ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [] } ], "metadata": { diff --git a/cookbook/introduction/15_Export.ipynb b/cookbook/introduction/15_Export.ipynb index 800b7da3..515f690e 100644 --- a/cookbook/introduction/15_Export.ipynb +++ b/cookbook/introduction/15_Export.ipynb @@ -4,22 +4,52 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Hawksight-AI/semantica/blob/main/cookbook/introduction/16_Export.ipynb)\n", + "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Hawksight-AI/semantica/blob/main/cookbook/introduction/15_Export.ipynb)\n", "\n", - "# Export\n", + "# Export Module - Comprehensive Guide\n", "\n", "## Overview\n", "\n", - "This notebook demonstrates how to export knowledge graphs and data to various formats using Semantica's export modules. You'll learn to use `JSONExporter`, `CSVExporter`, `RDFExporter`, `GraphExporter`, `OWLExporter`, and `VectorExporter`.\n", + "This notebook provides a comprehensive guide to Semantica's **Export Module**, which enables exporting knowledge graphs, entities, relationships, and data to multiple formats. The module supports **8 export formats** (RDF, JSON, CSV, Graph, YAML, OWL, Vector, LPG) plus report generation capabilities.\n", "\n", "**Documentation**: [API Reference](https://semantica.readthedocs.io/reference/export/)\n", "\n", + "### Export Module Architecture\n", + "\n", + "The Export Module consists of:\n", + "\n", + "#### **Core Exporter Classes** (9 classes)\n", + "- `RDFExporter` - RDF format export (Turtle, RDF/XML, JSON-LD, N-Triples, N3)\n", + "- `JSONExporter` - JSON and JSON-LD format export\n", + "- `CSVExporter` - CSV format export for tabular data\n", + "- `GraphExporter` - Graph format export (GraphML, GEXF, DOT)\n", + "- `SemanticNetworkYAMLExporter` - Semantic network YAML export\n", + "- `YAMLSchemaExporter` - Schema YAML export\n", + "- `OWLExporter` - OWL format export for ontologies\n", + "- `VectorExporter` - Vector embedding export for vector stores\n", + "- `LPGExporter` - LPG format export for Neo4j, Memgraph, and similar databases\n", + "\n", + "#### **Supporting Classes** (4 classes)\n", + "- `RDFSerializer` - RDF serialization engine for format conversion\n", + "- `RDFValidator` - RDF validation engine for syntax checking\n", + "- `NamespaceManager` - RDF namespace management and conflict resolution\n", + "- `ReportGenerator` - Report generation (HTML, Markdown, JSON, Text)\n", + "\n", + "#### **Registry & Configuration** (2 classes + 2 instances)\n", + "- `MethodRegistry` - Registry for custom export methods\n", + "- `method_registry` - Global registry instance\n", + "- `ExportConfig` - Configuration manager for export module\n", + "- `export_config` - Global configuration instance\n", + "\n", "### Learning Objectives\n", "\n", - "- Use `JSONExporter` to export to JSON\n", - "- Use `CSVExporter` to export to CSV\n", - "- Use `RDFExporter` to export to RDF\n", - "- Use `GraphExporter` to export graph formats\n", + "By the end of this notebook, you will be able to:\n", + "- Export knowledge graphs to all supported formats (RDF, JSON, CSV, Graph, YAML, OWL, Vector, LPG)\n", + "- Use exporter classes directly for fine-grained control\n", + "- Generate professional reports in multiple formats\n", + "- Register and use custom export methods\n", + "- Configure export settings via environment variables or config files\n", + "- Use RDF serialization, validation, and namespace management\n", "\n", "## Installation\n", "\n", @@ -35,7 +65,13 @@ "\n", "## Step 1: JSON Export\n", "\n", - "Export knowledge graph to JSON.\n" + "Export knowledge graph to JSON format using `JSONExporter` class.\n", + "\n", + "**JSONExporter Methods:**\n", + "- `export()` - Export any data to JSON\n", + "- `export_knowledge_graph()` - Export knowledge graph to JSON/JSON-LD\n", + "- `export_entities()` - Export entities to JSON\n", + "- `export_relationships()` - Export relationships to JSON\n" ] }, { @@ -47,14 +83,17 @@ "from semantica.export import JSONExporter\n", "from semantica.kg import GraphBuilder\n", "\n", + "# Create exporter and builder\n", "json_exporter = JSONExporter()\n", "builder = GraphBuilder()\n", "\n", + "# Create sample knowledge graph\n", "entities = [{\"id\": \"e1\", \"type\": \"Organization\", \"name\": \"Apple Inc.\", \"properties\": {}}]\n", "relationships = []\n", "\n", "kg = builder.build(entities, relationships)\n", "\n", + "# Export to JSON\n", "json_exporter.export_knowledge_graph(kg, \"output.json\")\n" ] }, @@ -64,7 +103,13 @@ "source": [ "## Step 2: CSV Export\n", "\n", - "Export entities to CSV.\n" + "Export entities and relationships to CSV format using `CSVExporter` class.\n", + "\n", + "**CSVExporter Methods:**\n", + "- `export()` - Export knowledge graph to CSV\n", + "- `export_entities()` - Export entities to CSV file\n", + "- `export_relationships()` - Export relationships to CSV file\n", + "- `export_knowledge_graph()` - Export complete knowledge graph to CSV\n" ] }, { @@ -75,8 +120,10 @@ "source": [ "from semantica.export import CSVExporter\n", "\n", + "# Create CSV exporter\n", "csv_exporter = CSVExporter()\n", "\n", + "# Export entities to CSV\n", "csv_exporter.export_entities(entities, \"entities.csv\")\n" ] }, @@ -86,7 +133,25 @@ "source": [ "## Step 3: RDF Export\n", "\n", - "Export knowledge graph to RDF.\n" + "Export knowledge graph to RDF format using `RDFExporter` class.\n", + "\n", + "**RDFExporter Methods:**\n", + "- `export()` - Export to RDF (supports multiple formats)\n", + "- `export_knowledge_graph()` - Export knowledge graph to RDF\n", + "- `export_entities()` - Export entities to RDF\n", + "- `export_relationships()` - Export relationships to RDF\n", + "\n", + "**Supported RDF Formats:**\n", + "- `turtle` - Turtle format (human-readable)\n", + "- `rdfxml` - RDF/XML format\n", + "- `jsonld` - JSON-LD format\n", + "- `ntriples` - N-Triples format\n", + "- `n3` - N3 format\n", + "\n", + "**Additional RDF Classes:**\n", + "- `RDFSerializer` - Serialize RDF data between formats\n", + "- `RDFValidator` - Validate RDF syntax and consistency\n", + "- `NamespaceManager` - Manage RDF namespaces\n" ] }, { @@ -97,9 +162,11 @@ "source": [ "from semantica.export import RDFExporter\n", "\n", + "# Create RDF exporter\n", "rdf_exporter = RDFExporter()\n", "\n", - "rdf_exporter.export_knowledge_graph(kg, \"output.rdf\")\n" + "# Export to RDF format (Turtle by default)\n", + "rdf_exporter.export_knowledge_graph(kg, \"output.ttl\", format=\"turtle\")\n" ] }, { @@ -108,7 +175,16 @@ "source": [ "## Step 4: Graph Export\n", "\n", - "Export to graph formats (GraphML, GEXF).\n" + "Export to graph formats using `GraphExporter` class for visualization tools.\n", + "\n", + "**GraphExporter Methods:**\n", + "- `export()` - Export to graph format\n", + "- `export_knowledge_graph()` - Export knowledge graph to graph format\n", + "\n", + "**Supported Graph Formats:**\n", + "- `graphml` - GraphML format (for Cytoscape, yEd, etc.)\n", + "- `gexf` - GEXF format (for Gephi)\n", + "- `dot` - Graphviz DOT format\n" ] }, { @@ -119,8 +195,10 @@ "source": [ "from semantica.export import GraphExporter\n", "\n", + "# Create graph exporter\n", "graph_exporter = GraphExporter()\n", "\n", + "# Export to GraphML format\n", "graph_exporter.export_knowledge_graph(kg, \"output.graphml\", format=\"graphml\")\n" ] }, @@ -130,7 +208,19 @@ "source": [ "## Step 5: OWL Export\n", "\n", - "Export ontology to OWL.\n" + "Export ontologies to OWL format using `OWLExporter` class.\n", + "\n", + "**OWLExporter Methods:**\n", + "- `export()` - Export ontology to OWL\n", + "- `export_ontology()` - Export complete ontology\n", + "- `export_classes()` - Export class definitions only\n", + "- `export_properties()` - Export property definitions only\n", + "\n", + "**Supported OWL Formats:**\n", + "- `owl-xml` - OWL/XML format (default)\n", + "- `turtle` - OWL in Turtle format\n", + "\n", + "**Note:** OWLExporter expects an ontology structure (with classes, properties), not a knowledge graph. Use `OntologyGenerator` to convert a knowledge graph to an ontology first.\n" ] }, { @@ -142,11 +232,14 @@ "from semantica.export import OWLExporter\n", "from semantica.ontology import OntologyGenerator\n", "\n", + "# Create OWL exporter and ontology generator\n", "owl_exporter = OWLExporter()\n", "generator = OntologyGenerator()\n", "\n", + "# Generate ontology from entities and relationships\n", "ontology = generator.generate(entities, relationships)\n", "\n", + "# Export ontology to OWL\n", "owl_exporter.export(ontology, \"output.owl\")\n" ] }, @@ -154,18 +247,103 @@ "cell_type": "markdown", "metadata": {}, "source": [ + "## Step 6: Additional Export Formats\n", + "\n", + "### YAML Export\n", + "\n", + "Export to YAML format using YAML exporters:\n", + "\n", + "**YAML Exporter Classes:**\n", + "- `SemanticNetworkYAMLExporter` - Export semantic networks to YAML\n", + "- `YAMLSchemaExporter` - Export ontology schemas to YAML\n", + "\n", + "### Vector Export\n", + "\n", + "Export vector embeddings using `VectorExporter`:\n", + "\n", + "**VectorExporter Methods:**\n", + "- `export()` - Export vectors to various formats\n", + "\n", + "**Supported Vector Formats:**\n", + "- `json` - JSON format\n", + "- `numpy` - NumPy format\n", + "- `binary` - Binary format\n", + "- `faiss` - FAISS format\n", + "\n", + "### LPG Export\n", + "\n", + "Export to Labeled Property Graph format using `LPGExporter`:\n", + "\n", + "**LPGExporter Methods:**\n", + "- `export()` - Export to LPG format\n", + "- `export_knowledge_graph()` - Export knowledge graph to LPG\n", + "\n", + "**Supported LPG Formats:**\n", + "- `cypher` - Cypher query format (for Neo4j, Memgraph)\n", + "- `lpg` - Labeled Property Graph format\n", + "\n", + "### Report Generation\n", + "\n", + "Generate professional reports using `ReportGenerator`:\n", + "\n", + "**ReportGenerator Methods:**\n", + "- `generate_report()` - Generate report in various formats\n", + "\n", + "**Supported Report Formats:**\n", + "- `html` - HTML report\n", + "- `markdown` - Markdown report\n", + "- `json` - JSON report\n", + "- `text` - Plain text report\n", + "\n", + "## Step 7: Method Registry\n", + "\n", + "Register and use custom export methods using the MethodRegistry system:\n", + "\n", + "```python\n", + "from semantica.export import MethodRegistry, method_registry, JSONExporter\n", + "\n", + "# Register custom method\n", + "def my_custom_export(data, file_path, **kwargs):\n", + " # Custom export logic\n", + " pass\n", + "\n", + "MethodRegistry.register(\"json\", \"custom\", my_custom_export)\n", + "\n", + "# List available methods\n", + "methods = method_registry.list_all()\n", + "print(methods)\n", + "```\n", + "\n", "## Summary\n", "\n", - "You've learned how to export data:\n", + "You've learned how to export data using Semantica's Export Module:\n", "\n", - "- **JSONExporter**: Export to JSON format\n", + "### **Core Exporter Classes:**\n", + "- **JSONExporter**: Export to JSON/JSON-LD format\n", "- **CSVExporter**: Export to CSV format\n", - "- **RDFExporter**: Export to RDF format\n", - "- **GraphExporter**: Export to graph formats (GraphML, GEXF)\n", + "- **RDFExporter**: Export to RDF format (Turtle, RDF/XML, JSON-LD, N-Triples, N3)\n", + "- **GraphExporter**: Export to graph formats (GraphML, GEXF, DOT)\n", "- **OWLExporter**: Export ontologies to OWL\n", - "- **VectorExporter**: Export vectors\n", + "- **VectorExporter**: Export vectors to multiple formats\n", + "- **LPGExporter**: Export to Labeled Property Graph format\n", + "- **SemanticNetworkYAMLExporter**: Export semantic networks to YAML\n", + "- **YAMLSchemaExporter**: Export schemas to YAML\n", "\n", - "Next: Learn how to visualize data in the Visualization notebook.\n" + "### **Supporting Classes:**\n", + "- **RDFSerializer**: RDF format conversion\n", + "- **RDFValidator**: RDF validation\n", + "- **NamespaceManager**: RDF namespace management\n", + "- **ReportGenerator**: Generate professional reports\n", + "\n", + "### **Registry & Configuration:**\n", + "- `MethodRegistry`: Register custom export methods\n", + "- `ExportConfig`: Configure export settings\n", + "- `method_registry`: Global registry instance for accessing registered methods\n", + "- `export_config`: Global configuration instance for export settings\n", + "\n", + "**Next Steps:**\n", + "- Learn advanced export techniques in the [Multi-Format Export notebook](../advanced/05_Multi_Format_Export.ipynb)\n", + "- Learn how to visualize data in the Visualization notebook\n" ] } ], diff --git a/cookbook/use_cases/healthcare/05_Medical_Database_Integration.ipynb b/cookbook/use_cases/healthcare/05_Medical_Database_Integration.ipynb index 4b24c328..3947b596 100644 --- a/cookbook/use_cases/healthcare/05_Medical_Database_Integration.ipynb +++ b/cookbook/use_cases/healthcare/05_Medical_Database_Integration.ipynb @@ -533,7 +533,8 @@ "# Export knowledge graph\n", "json_exporter.export_knowledge_graph(resolved_kg, os.path.join(temp_dir, \"medical_kg.json\"))\n", "rdf_exporter.export_knowledge_graph(resolved_kg, os.path.join(temp_dir, \"medical_kg.rdf\"))\n", - "owl_exporter.export_knowledge_graph(resolved_kg, os.path.join(temp_dir, \"medical_kg.owl\"))\n", + "# Note: OWLExporter expects an ontology structure, not a knowledge graph\n", + "# To export as OWL, first generate an ontology from the KG using OntologyGenerator\n", "\n", "# Generate report\n", "report_data = {\n", @@ -549,7 +550,6 @@ "\n", "print(f\" JSON: {os.path.join(temp_dir, 'medical_kg.json')}\")\n", "print(f\" RDF: {os.path.join(temp_dir, 'medical_kg.rdf')}\")\n", - "print(f\" OWL: {os.path.join(temp_dir, 'medical_kg.owl')}\")\n", "\n", "# Visualize\n", "kg_visualizer = KGVisualizer()\n", diff --git a/cookbook/use_cases/intelligence/01_Criminal_Network_Analysis.ipynb b/cookbook/use_cases/intelligence/01_Criminal_Network_Analysis.ipynb index 8ec2011c..c9fe15e2 100644 --- a/cookbook/use_cases/intelligence/01_Criminal_Network_Analysis.ipynb +++ b/cookbook/use_cases/intelligence/01_Criminal_Network_Analysis.ipynb @@ -63,7 +63,7 @@ "- **Context**: AgentMemory, ContextRetriever, ContextGraphBuilder\n", "- **Pipeline**: PipelineBuilder, ExecutionEngine, ParallelismManager\n", "- **Reasoning**: InferenceEngine, RuleManager, ExplanationGenerator\n", - "- **Export**: ReportGenerator, HTMLExporter, JSONExporter\n", + "- **Export**: ReportGenerator, JSONExporter\n", "- **Visualization**: KGVisualizer, AnalyticsVisualizer, TemporalVisualizer\n", "- **Deduplication**: DuplicateDetector, EntityMerger\n", "\n", @@ -100,7 +100,7 @@ "from semantica.context import AgentMemory, ContextRetriever, ContextGraphBuilder\n", "from semantica.pipeline import PipelineBuilder, ExecutionEngine, ParallelismManager\n", "from semantica.reasoning import InferenceEngine, RuleManager, ExplanationGenerator\n", - "from semantica.export import ReportGenerator, HTMLExporter, JSONExporter\n", + "from semantica.export import ReportGenerator, JSONExporter\n", "from semantica.visualization import KGVisualizer, AnalyticsVisualizer, TemporalVisualizer\n", "from semantica.deduplication import DuplicateDetector, EntityMerger\n", "\n", diff --git a/cookbook/use_cases/intelligence/02_Intelligence_Analysis.ipynb b/cookbook/use_cases/intelligence/02_Intelligence_Analysis.ipynb index 52676efc..8ac95f01 100644 --- a/cookbook/use_cases/intelligence/02_Intelligence_Analysis.ipynb +++ b/cookbook/use_cases/intelligence/02_Intelligence_Analysis.ipynb @@ -66,7 +66,7 @@ "- **Vector Store**: VectorStore, HybridSearch, MetadataFilter\n", "- **Context**: AgentMemory, ContextRetriever, ContextGraphBuilder\n", "- **Reasoning**: InferenceEngine, RuleManager, ExplanationGenerator\n", - "- **Export**: ReportGenerator, HTMLExporter, JSONExporter\n", + "- **Export**: ReportGenerator, JSONExporter\n", "- **Visualization**: KGVisualizer, AnalyticsVisualizer, TemporalVisualizer\n", "\n", "### Pipeline Overview\n", @@ -113,7 +113,7 @@ "from semantica.vector_store import VectorStore, HybridSearch, MetadataFilter\n", "from semantica.context import AgentMemory, ContextRetriever, ContextGraphBuilder\n", "from semantica.reasoning import InferenceEngine, RuleManager, ExplanationGenerator\n", - "from semantica.export import ReportGenerator, HTMLExporter, JSONExporter\n", + "from semantica.export import ReportGenerator, JSONExporter\n", "from semantica.visualization import KGVisualizer, AnalyticsVisualizer, TemporalVisualizer\n", "\n", "import tempfile\n", diff --git a/cookbook/use_cases/intelligence/03_Law_Enforcement_Forensics.ipynb b/cookbook/use_cases/intelligence/03_Law_Enforcement_Forensics.ipynb index 49d8fc18..5d88dd26 100644 --- a/cookbook/use_cases/intelligence/03_Law_Enforcement_Forensics.ipynb +++ b/cookbook/use_cases/intelligence/03_Law_Enforcement_Forensics.ipynb @@ -51,7 +51,7 @@ "- **Context**: AgentMemory, ContextRetriever, ContextGraphBuilder\n", "- **Pipeline**: PipelineBuilder, ExecutionEngine, ParallelismManager\n", "- **Reasoning**: InferenceEngine, RuleManager, ExplanationGenerator\n", - "- **Export**: ReportGenerator, HTMLExporter, JSONExporter\n", + "- **Export**: ReportGenerator, JSONExporter\n", "- **Visualization**: KGVisualizer, AnalyticsVisualizer, TemporalVisualizer\n", "- **Deduplication**: DuplicateDetector, EntityMerger\n", "\n", @@ -96,7 +96,7 @@ "from semantica.context import AgentMemory, ContextRetriever, ContextGraphBuilder\n", "from semantica.pipeline import PipelineBuilder, ExecutionEngine, ParallelismManager\n", "from semantica.reasoning import InferenceEngine, RuleManager, ExplanationGenerator\n", - "from semantica.export import ReportGenerator, HTMLExporter, JSONExporter\n", + "from semantica.export import ReportGenerator, JSONExporter\n", "from semantica.visualization import KGVisualizer, AnalyticsVisualizer, TemporalVisualizer\n", "from semantica.deduplication import DuplicateDetector, EntityMerger\n", "\n", diff --git a/docs/reference/export.md b/docs/reference/export.md index e6f70180..03871fa6 100644 --- a/docs/reference/export.md +++ b/docs/reference/export.md @@ -82,10 +82,44 @@ Export knowledge graphs to RDF formats (Turtle, RDF/XML, JSON-LD, N-Triples). | Method | Description | Algorithm | |--------|-------------|-----------| | `export(graph, filename, format)` | Export to RDF format | RDF serialization with format-specific encoding | +| `export_knowledge_graph(kg, filename, format)` | Export knowledge graph | Knowledge graph to RDF conversion | | `serialize(graph, format)` | Serialize to string | In-memory RDF generation | -| `validate(rdf_data)` | Validate RDF syntax | RDF schema validation | -| `add_namespace(prefix, uri)` | Add namespace | Prefix registration | -| `set_base_uri(uri)` | Set base URI | Base URI configuration | +| `validate_rdf(rdf_data)` | Validate RDF syntax | RDF schema validation | + +### RDFSerializer + +RDF serialization engine for format conversion. + +**Methods:** + +| Method | Description | Algorithm | +|--------|-------------|-----------| +| `serialize_to_turtle(rdf_data)` | Serialize to Turtle | Compact RDF format with prefix compression | +| `serialize_to_rdfxml(rdf_data)` | Serialize to RDF/XML | XML-based RDF format | +| `serialize_to_jsonld(rdf_data)` | Serialize to JSON-LD | JSON-based linked data format | + +### RDFValidator + +RDF validation engine for syntax and consistency checking. + +**Methods:** + +| Method | Description | Algorithm | +|--------|-------------|-----------| +| `validate_rdf_syntax(rdf_data, format)` | Validate RDF syntax | Format-specific syntax validation | +| `check_rdf_consistency(rdf_data)` | Check consistency | Entity reference and structure validation | + +### NamespaceManager + +RDF namespace management and conflict resolution. + +**Methods:** + +| Method | Description | Algorithm | +|--------|-------------|-----------| +| `extract_namespaces(rdf_data)` | Extract namespaces | Namespace discovery from RDF data | +| `generate_namespace_declarations(namespaces, format)` | Generate declarations | Format-specific namespace declaration | +| `resolve_conflicts(namespaces)` | Resolve conflicts | Prefix conflict resolution | **Supported RDF Formats:** @@ -208,19 +242,17 @@ exporter.to_dot(kg, "graph.dot") --- -### Neo4jExporter +### LPGExporter -Export directly to Neo4j graph database with Cypher query generation. +Export to LPG (Labeled Property Graph) format for Neo4j, Memgraph, and similar databases. **Methods:** | Method | Description | Algorithm | |--------|-------------|-----------| -| `export(graph, uri, username, password)` | Export to Neo4j | Cypher query execution | -| `generate_cypher(graph)` | Generate Cypher queries | CREATE/MERGE statement generation | -| `batch_import(graph, batch_size)` | Batch import | Chunked Cypher execution | -| `create_indexes(properties)` | Create indexes | Index creation for performance | -| `create_constraints(constraints)` | Create constraints | Uniqueness constraint creation | +| `export(knowledge_graph, file_path)` | Export to LPG format | Cypher query generation | +| `export_knowledge_graph(kg, file_path)` | Export knowledge graph | Knowledge graph to Cypher conversion | +| `generate_cypher(kg)` | Generate Cypher queries | CREATE/MERGE statement generation | **Cypher Generation:** ```cypher @@ -235,17 +267,12 @@ CREATE (a)-[:FOUNDED]->(b) **Example:** ```python -from semantica.export import Neo4jExporter +from semantica.export import LPGExporter -exporter = Neo4jExporter() +exporter = LPGExporter(batch_size=1000, include_indexes=True) -# Direct export to Neo4j -exporter.export( - graph=kg, - uri="bolt://localhost:7687", - username="neo4j", - password="password" -) +# Export to Cypher file +exporter.export_knowledge_graph(kg, "graph.cypher") # Generate Cypher queries cypher_queries = exporter.generate_cypher(kg) @@ -298,10 +325,211 @@ Export vector embeddings to various formats. | Method | Description | Algorithm | |--------|-------------|-----------| -| `export(embeddings, filename, format)` | Export vectors | Format-specific vector serialization | -| `export_numpy(embeddings, filename)` | Export to NumPy | .npy format | -| `export_hdf5(embeddings, filename)` | Export to HDF5 | Hierarchical data format | -| `export_parquet(embeddings, filename)` | Export to Parquet | Columnar storage format | +| `export(vectors, filename, format)` | Export vectors | Format-specific vector serialization | +| `export_numpy(vectors, filename)` | Export to NumPy | .npy format | +| `export_hdf5(vectors, filename)` | Export to HDF5 | Hierarchical data format | +| `export_parquet(vectors, filename)` | Export to Parquet | Columnar storage format | + +**Example:** + +```python +from semantica.export import VectorExporter + +exporter = VectorExporter(format="json", include_metadata=True) +exporter.export(vectors, "vectors.json") +``` + +--- + +### OWLExporter + +Export ontologies to OWL format (OWL/XML, Turtle). + +**Methods:** + +| Method | Description | Algorithm | +|--------|-------------|-----------| +| `export(ontology, filename, format)` | Export ontology | OWL serialization | +| `export_classes(classes, filename)` | Export classes | Class definition export | +| `export_properties(properties, filename)` | Export properties | Property definition export | + +**Example:** + +```python +from semantica.export import OWLExporter + +exporter = OWLExporter(ontology_uri="http://example.org/ontology#") +exporter.export(ontology, "ontology.owl", format="owl-xml") +``` + +--- + +### SemanticNetworkYAMLExporter + +Export semantic networks to YAML format. + +**Methods:** + +| Method | Description | Algorithm | +|--------|-------------|-----------| +| `export(semantic_network, filename)` | Export semantic network | YAML serialization | +| `export_semantic_network(semantic_network)` | Export to string | In-memory YAML generation | + +**Example:** + +```python +from semantica.export import SemanticNetworkYAMLExporter + +exporter = SemanticNetworkYAMLExporter() +exporter.export(semantic_network, "network.yaml") +``` + +--- + +### YAMLSchemaExporter + +Export ontology schemas to YAML format. + +**Methods:** + +| Method | Description | Algorithm | +|--------|-------------|-----------| +| `export(schema, filename)` | Export schema | YAML schema serialization | + +**Example:** + +```python +from semantica.export import YAMLSchemaExporter + +exporter = YAMLSchemaExporter() +exporter.export(schema, "schema.yaml") +``` + +--- + +### ReportGenerator + +Generate reports in multiple formats (HTML, Markdown, JSON, Text). + +**Methods:** + +| Method | Description | Algorithm | +|--------|-------------|-----------| +| `generate_report(data, filename, format)` | Generate report | Template-based report generation | +| `generate_quality_report(metrics, filename, format)` | Generate quality report | Quality metrics aggregation | + +**Example:** + +```python +from semantica.export import ReportGenerator + +generator = ReportGenerator(format="html", include_charts=True) +generator.generate_report(data, "report.html") +``` + +--- + +### MethodRegistry + +Registry for custom export methods. + +**Methods:** + +| Method | Description | Algorithm | +|--------|-------------|-----------| +| `register(task, name, method_func)` | Register method | Dictionary-based registration | +| `get(task, name)` | Get method | Hash-based lookup | +| `list_all(task)` | List methods | Method discovery | +| `unregister(task, name)` | Unregister method | Method removal | +| `clear(task)` | Clear methods | Registry cleanup | + +**Global Instance:** +- `method_registry`: Global method registry instance + +**Example:** + +```python +from semantica.export import method_registry + +method_registry.register("json", "custom_method", custom_json_export) +method = method_registry.get("json", "custom_method") +all_methods = method_registry.list_all() +``` + +--- + +### ExportConfig + +Configuration manager for export module. + +**Methods:** + +| Method | Description | Algorithm | +|--------|-------------|-----------| +| `set(key, value)` | Set configuration | Configuration storage | +| `get(key, default)` | Get configuration | Configuration retrieval | +| `set_method_config(task, **config)` | Set method config | Method-specific configuration | +| `get_method_config(task)` | Get method config | Method configuration retrieval | + +**Global Instance:** +- `export_config`: Global export configuration instance + +**Example:** + +```python +from semantica.export.config import export_config, ExportConfig + +# Using global instance +export_config.set("default_format", "json") +format = export_config.get("default_format", default="json") + +# Create custom instance +config = ExportConfig(config_file="config.yaml") +``` + +--- + +## Convenience Functions + +### Export Functions + +| Function | Description | Format | +|----------|-------------|--------| +| `export_rdf(data, file_path, format)` | Export to RDF | turtle, rdfxml, jsonld, ntriples, n3 | +| `export_json(data, file_path, format)` | Export to JSON | json, json-ld | +| `export_csv(data, file_path)` | Export to CSV | csv | +| `export_graph(graph_data, file_path, format)` | Export to graph format | graphml, gexf, dot | +| `export_yaml(data, file_path, method)` | Export to YAML | semantic_network, schema | +| `export_owl(ontology, file_path, format)` | Export to OWL | owl-xml, turtle | +| `export_vector(vectors, file_path, format)` | Export vectors | json, numpy, binary, faiss | +| `export_lpg(kg, file_path, method)` | Export to LPG | cypher, lpg | +| `generate_report(data, file_path, format)` | Generate report | html, markdown, json, text | + +### Registry Functions + +| Function | Description | +|----------|-------------| +| `get_export_method(task, name)` | Get registered export method | +| `list_available_methods(task)` | List all available methods | + +**Example:** + +```python +from semantica.export.methods import ( + export_rdf, export_json, export_csv, export_graph, + export_yaml, export_owl, export_vector, export_lpg, + generate_report, get_export_method, list_available_methods +) + +# Export functions +export_rdf(kg, "output.ttl", format="turtle") +export_json(kg, "output.json", format="json") +export_lpg(kg, "graph.cypher", method="cypher") + +# Registry functions +method = get_export_method("json", "custom_method") +all_methods = list_available_methods() +``` --- diff --git a/semantica/export/__init__.py b/semantica/export/__init__.py index c0a0d3a1..16736e81 100644 --- a/semantica/export/__init__.py +++ b/semantica/export/__init__.py @@ -98,7 +98,6 @@ Main Classes: - ExportConfig: Configuration manager for export module Convenience Functions: - - export_knowledge_graph: Unified knowledge graph export with format dispatch - export_rdf: RDF export wrapper - export_json: JSON/JSON-LD export wrapper - export_csv: CSV export wrapper @@ -110,9 +109,8 @@ Convenience Functions: - generate_report: Report generation wrapper Example Usage: - >>> from semantica.export import export_knowledge_graph, export_lpg, JSONExporter + >>> from semantica.export import export_lpg, JSONExporter >>> # Using convenience function - >>> export_knowledge_graph(kg, "output.json", format="json") >>> export_lpg(kg, "output.cypher", method="cypher") >>> # Using classes directly >>> json_exporter = JSONExporter() @@ -131,7 +129,6 @@ from .methods import ( export_csv, export_graph, export_json, - export_knowledge_graph, export_lpg, export_owl, export_rdf, @@ -175,7 +172,6 @@ __all__ = [ "export_vector", "export_lpg", "generate_report", - "export_knowledge_graph", "get_export_method", "list_available_methods", # Configuration diff --git a/semantica/export/export_usage.md b/semantica/export/export_usage.md index 90e30f93..736ceb7c 100644 --- a/semantica/export/export_usage.md +++ b/semantica/export/export_usage.md @@ -22,23 +22,6 @@ This guide demonstrates how to use the export module for exporting knowledge gra ## Basic Usage -### Using the Convenience Function - -```python -from semantica.export import export_knowledge_graph - -# Export knowledge graph to JSON -kg = { - "entities": [...], - "relationships": [...], - "metadata": {...} -} - -export_knowledge_graph(kg, "output.json", format="json") -export_knowledge_graph(kg, "output.ttl", format="turtle") -export_knowledge_graph(kg, "output.cypher", format="cypher") -``` - ### Using Main Classes ```python @@ -57,6 +40,34 @@ lpg_exporter.export_knowledge_graph(kg, "output.cypher") ## RDF Export +### RDFExporter Class + +The `RDFExporter` class provides comprehensive RDF export functionality. + +**Additional RDF Classes:** +- `RDFSerializer`: RDF serialization engine for format conversion +- `RDFValidator`: RDF validation engine for syntax checking +- `NamespaceManager`: RDF namespace management and conflict resolution + +```python +from semantica.export import RDFExporter, RDFSerializer, RDFValidator, NamespaceManager + +# Using RDFSerializer directly +serializer = RDFSerializer() +turtle_string = serializer.serialize_to_turtle(rdf_data) +jsonld_string = serializer.serialize_to_jsonld(rdf_data) + +# Using RDFValidator +validator = RDFValidator() +validation_result = validator.validate_rdf_syntax(rdf_data, format="turtle") +consistency = validator.check_rdf_consistency(rdf_data) + +# Using NamespaceManager +namespace_mgr = NamespaceManager() +namespaces = namespace_mgr.extract_namespaces(rdf_data) +declarations = namespace_mgr.generate_namespace_declarations(namespaces, format="turtle") +``` + ### Turtle Format ```python @@ -483,10 +494,10 @@ generate_report(data, "report.md", format="markdown") ## Knowledge Graph Export -### Unified Export Function +### Using Exporter Classes ```python -from semantica.export.methods import export_knowledge_graph +from semantica.export import JSONExporter, RDFExporter, LPGExporter kg = { "entities": [...], @@ -494,27 +505,39 @@ kg = { "metadata": {...} } -# Auto-detect format from file extension -export_knowledge_graph(kg, "output.json") # JSON format -export_knowledge_graph(kg, "output.ttl") # Turtle format -export_knowledge_graph(kg, "output.cypher") # Cypher format +# Export to different formats using exporter classes +json_exporter = JSONExporter() +json_exporter.export_knowledge_graph(kg, "output.json") -# Explicit format specification -export_knowledge_graph(kg, "output.json", format="json-ld") -export_knowledge_graph(kg, "output.rdf", format="rdfxml") +rdf_exporter = RDFExporter() +rdf_exporter.export_knowledge_graph(kg, "output.ttl", format="turtle") + +lpg_exporter = LPGExporter() +lpg_exporter.export_knowledge_graph(kg, "output.cypher") ``` ### Multiple Format Export ```python -from semantica.export.methods import export_knowledge_graph +from semantica.export import JSONExporter, RDFExporter, CSVExporter, LPGExporter kg = {...} -# Export to multiple formats -formats = ["json", "turtle", "csv", "cypher"] -for fmt in formats: - export_knowledge_graph(kg, f"output.{fmt}", format=fmt) +# Export to multiple formats using different exporters +exporters = { + "json": JSONExporter(), + "turtle": RDFExporter(), + "csv": CSVExporter(), + "cypher": LPGExporter() +} + +for fmt, exporter in exporters.items(): + if fmt == "turtle": + exporter.export_knowledge_graph(kg, f"output.{fmt}", format="turtle") + elif fmt == "csv": + exporter.export_knowledge_graph(kg, f"output_{fmt}") + else: + exporter.export_knowledge_graph(kg, f"output.{fmt}") ``` ## Using Methods @@ -560,10 +583,25 @@ export_lpg(kg, "graph.cypher", method="cypher") ## Using Registry +### MethodRegistry Class + +The `MethodRegistry` class provides a registry system for registering custom export methods. + +```python +from semantica.export import MethodRegistry, method_registry + +# Using the global instance +method_registry.register("json", "custom_method", custom_json_export) + +# Or create your own instance +registry = MethodRegistry() +registry.register("rdf", "custom_rdf", custom_rdf_export) +``` + ### Registering Custom Methods ```python -from semantica.export.registry import method_registry +from semantica.export import method_registry def custom_json_export(data, file_path, **kwargs): """Custom JSON export function.""" @@ -578,6 +616,32 @@ from semantica.export.methods import export_json export_json(data, "output.json", method="custom_method") ``` +### MethodRegistry Methods + +```python +from semantica.export import MethodRegistry + +registry = MethodRegistry() + +# Register a method +registry.register("json", "my_method", my_function) + +# Get a method +method = registry.get("json", "my_method") + +# List all methods +all_methods = registry.list_all() +json_methods = registry.list_all("json") + +# Unregister a method +registry.unregister("json", "my_method") + +# Clear all methods for a task +registry.clear("json") +# Or clear all +registry.clear() +``` + ### Listing Available Methods ```python @@ -622,9 +686,9 @@ export EXPORT_VALIDATE="true" ### Programmatic Configuration ```python -from semantica.export.config import export_config +from semantica.export.config import export_config, ExportConfig -# Set configuration +# Using the global instance export_config.set("default_format", "json") export_config.set("output_dir", "./exports") export_config.set("include_metadata", True) @@ -636,6 +700,10 @@ output_dir = export_config.get("output_dir", default="./") # Method-specific configuration export_config.set_method_config("rdf", format="turtle") rdf_config = export_config.get_method_config("rdf") + +# Create a custom ExportConfig instance +config = ExportConfig(config_file="custom_config.yaml") +config.set("default_format", "json-ld") ``` ### Config File (YAML) @@ -679,8 +747,8 @@ config = ExportConfig(config_file="config.yaml") ```python from semantica.export.methods import ( - export_knowledge_graph, export_rdf, + export_json, export_lpg ) @@ -691,7 +759,7 @@ kg = { } # Export to multiple formats -export_knowledge_graph(kg, "output.json", format="json") +export_json(kg, "output.json", format="json") export_rdf(kg, "output.ttl", format="turtle") export_lpg(kg, "output.cypher", method="cypher") ``` @@ -699,23 +767,27 @@ export_lpg(kg, "output.cypher", method="cypher") ### Batch Export with Format Detection ```python -from semantica.export.methods import export_knowledge_graph +from semantica.export.methods import export_json, export_rdf, export_csv, export_lpg, export_graph from pathlib import Path kg = {...} -# Export to multiple formats based on file extensions -output_files = [ - "output.json", - "output.ttl", - "output.csv", - "output.cypher", - "output.graphml" +# Export to multiple formats using appropriate methods +export_configs = [ + ("json", "output.json", export_json), + ("turtle", "output.ttl", export_rdf), + ("csv", "output.csv", export_csv), + ("cypher", "output.cypher", export_lpg), + ("graphml", "output.graphml", export_graph) ] -for file_path in output_files: - export_knowledge_graph(kg, file_path) - # Format auto-detected from extension +for format_name, file_path, export_func in export_configs: + if format_name == "turtle": + export_func(kg, file_path, format="turtle") + elif format_name == "graphml": + export_func(kg, file_path, format="graphml") + else: + export_func(kg, file_path) ``` ### Custom Export Method @@ -764,26 +836,29 @@ exporter.export_knowledge_graph(large_kg, "large_graph.cypher") ### Multi-Format Knowledge Graph Export ```python -from semantica.export.methods import export_knowledge_graph +from semantica.export.methods import ( + export_json, export_rdf, export_csv, export_graph, + export_yaml, export_owl, export_lpg +) kg = {...} -# Export to all supported formats -formats = { - "json": "output.json", - "json-ld": "output.jsonld", - "turtle": "output.ttl", - "rdfxml": "output.rdf", - "csv": "output_base", - "graphml": "graph.graphml", - "cypher": "graph.cypher", - "yaml": "network.yaml", - "owl": "ontology.owl" -} +# Export to all supported formats using appropriate methods +export_configs = [ + ("json", "output.json", export_json, {"format": "json"}), + ("json-ld", "output.jsonld", export_json, {"format": "json-ld"}), + ("turtle", "output.ttl", export_rdf, {"format": "turtle"}), + ("rdfxml", "output.rdf", export_rdf, {"format": "rdfxml"}), + ("csv", "output_base", export_csv, {}), + ("graphml", "graph.graphml", export_graph, {"format": "graphml"}), + ("cypher", "graph.cypher", export_lpg, {}), + ("yaml", "network.yaml", export_yaml, {}), + ("owl", "ontology.owl", export_owl, {"format": "owl-xml"}) +] -for format_name, file_path in formats.items(): +for format_name, file_path, export_func, kwargs in export_configs: try: - export_knowledge_graph(kg, file_path, format=format_name) + export_func(kg, file_path, **kwargs) print(f"✓ Exported to {format_name}: {file_path}") except Exception as e: print(f"✗ Failed to export {format_name}: {e}") @@ -818,15 +893,17 @@ for format_name, file_path in formats.items(): 5. **Error Handling**: Always handle export errors gracefully ```python + from semantica.export.methods import export_json try: - export_knowledge_graph(kg, "output.json") + export_json(kg, "output.json", format="json") except Exception as e: logger.error(f"Export failed: {e}") ``` -6. **Format Auto-Detection**: Use file extensions for automatic format detection +6. **Format Selection**: Use appropriate exporter methods for each format ```python - export_knowledge_graph(kg, "output.ttl") # Auto-detects Turtle format + from semantica.export.methods import export_rdf + export_rdf(kg, "output.ttl", format="turtle") # Explicit format specification ``` 7. **Configuration Management**: Use environment variables or config files for consistent settings @@ -860,15 +937,18 @@ for format_name, file_path in formats.items(): 4. **Caching**: Cache exported files when possible ```python + from semantica.export.methods import export_json + from pathlib import Path # Check if export already exists if not Path("output.json").exists(): - export_knowledge_graph(kg, "output.json") + export_json(kg, "output.json", format="json") ``` 5. **Compression**: Compress large exports ```python import gzip - export_knowledge_graph(kg, "output.json") + from semantica.export.methods import export_json + export_json(kg, "output.json", format="json") # Then compress with open("output.json", "rb") as f_in: with gzip.open("output.json.gz", "wb") as f_out: diff --git a/semantica/export/methods.py b/semantica/export/methods.py index 435ba30d..5dd52674 100644 --- a/semantica/export/methods.py +++ b/semantica/export/methods.py @@ -139,14 +139,13 @@ Main Functions: - export_vector: Vector export wrapper - export_lpg: LPG export wrapper - generate_report: Report generation wrapper - - export_knowledge_graph: Unified knowledge graph export with format dispatch - get_export_method: Get export method by name - list_available_methods: List registered methods Example Usage: - >>> from semantica.export.methods import export_knowledge_graph, export_rdf, export_lpg + >>> from semantica.export.methods import export_rdf, export_json, export_lpg >>> kg = {"entities": [...], "relationships": [...]} - >>> export_knowledge_graph(kg, "output.json", format="json") + >>> export_json(kg, "output.json", format="json") >>> export_rdf(kg, "output.ttl", format="turtle") >>> export_lpg(kg, "output.cypher", method="cypher") """