{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/semantica-agi/semantica/blob/main/cookbook/introduction/15_Export.ipynb)\n",
    "\n",
    "# Export Module - Comprehensive Guide\n",
    "\n",
    "## Overview\n",
    "\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",
    "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",
    "Install Semantica from PyPI:\n",
    "\n",
    "```bash\n",
    "pip install semantica\n",
    "# Or with all optional dependencies:\n",
    "pip install semantica[all]\n",
    "```\n",
    "\n",
    "---\n",
    "\n",
    "## Step 1: JSON Export\n",
    "\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"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install semantica"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "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"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 2: CSV Export\n",
    "\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"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "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"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3: RDF Export\n",
    "\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"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from semantica.export import RDFExporter\n",
    "\n",
    "# Create RDF exporter\n",
    "rdf_exporter = RDFExporter()\n",
    "\n",
    "# Export to RDF format (Turtle by default)\n",
    "rdf_exporter.export(kg, \"output.ttl\", format=\"turtle\")"
   ]
  },
  {
   "cell_type": "code",
   "source": "# TTL alias: format=\"ttl\" is equivalent to format=\"turtle\"\nrdf_data = {\n    \"entities\": [\n        {\"id\": \"e1\", \"text\": \"Apple Inc.\", \"type\": \"ORG\", \"confidence\": 0.95},\n        {\"id\": \"e2\", \"text\": \"Steve Jobs\", \"type\": \"PERSON\", \"confidence\": 0.97},\n    ],\n    \"relationships\": [\n        {\"source_id\": \"e2\", \"target_id\": \"e1\", \"type\": \"founded_by\", \"confidence\": 0.91},\n    ],\n}\n\nrdf_exporter.export(rdf_data, \"output.ttl\", format=\"ttl\")\n\nresult = rdf_exporter.validate_rdf(rdf_data)\nprint(f\"Valid: {result['overall_valid']}\")",
   "metadata": {},
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 4: Graph Export\n",
    "\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"
   ]
  },
  {
   "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\n",
    "graph_exporter.export_knowledge_graph(kg, \"output.graphml\", format=\"graphml\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 5: OWL Export\n",
    "\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"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "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",
    "# Note: Pass data as a dictionary to generate_ontology\n",
    "ontology = generator.generate_ontology({\n",
    "    \"entities\": entities,\n",
    "    \"relationships\": relationships\n",
    "})\n",
    "\n",
    "# Export ontology to OWL\n",
    "owl_exporter.export(ontology, \"output.owl\")"
   ]
  },
  {
   "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",
    "\n",
    "## Summary\n",
    "\n",
    "You've learned how to export data using Semantica's Export Module:\n",
    "\n",
    "### **Core Exporter Classes:**\n",
    "- **JSONExporter**: Export to JSON/JSON-LD format\n",
    "- **CSVExporter**: Export to CSV format\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 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",
    "### **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"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}