{
 "cells": [
  {
   "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/08_Building_Knowledge_Graphs.ipynb)\n",
    "\n",
    "# Building Knowledge Graphs\n",
    "\n",
    "## Overview\n",
    "\n",
    "This notebook demonstrates how to build knowledge graphs from entities and relationships using Semantica's graph building modules. You'll learn to use `GraphBuilder`, `EntityResolver`, and `GraphValidator`.\n",
    "\n",
    "**Documentation**: [API Reference](https://semantica.readthedocs.io/reference/kg/)\n",
    "\n",
    "### Learning Objectives\n",
    "\n",
    "- Use `GraphBuilder` to construct knowledge graphs\n",
    "- Use `EntityResolver` to resolve entity conflicts\n",
    "- Use `GraphValidator` to validate graph structure\n",
    "**Note**: For deduplication, use the `semantica.deduplication` module.\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: Build Knowledge Graph\n",
    "\n",
    "Construct a knowledge graph from entities and relationships.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from semantica.kg import GraphBuilder\n",
    "from semantica.semantic_extract import NERExtractor, RelationExtractor\n",
    "\n",
    "builder = GraphBuilder()\n",
    "ner_extractor = NERExtractor()\n",
    "relation_extractor = RelationExtractor()\n",
    "\n",
    "text = \"Apple Inc. is a technology company. Tim Cook is the CEO of Apple Inc. Apple Inc. is headquartered in Cupertino, California.\"\n",
    "\n",
    "entities_list = ner_extractor.extract(text)\n",
    "relationships_list = relation_extractor.extract(text, entities_list)\n",
    "\n",
    "entities = []\n",
    "for i, entity in enumerate(entities_list[:5], 1):\n",
    "    entities.append({\n",
    "        \"id\": f\"e{i}\",\n",
    "        \"type\": entity.get(\"type\", \"Entity\"),\n",
    "        \"name\": entity.get(\"text\", entity.get(\"entity\", \"\")),\n",
    "        \"properties\": {}\n",
    "    })\n",
    "\n",
    "relationships = []\n",
    "for i, rel in enumerate(relationships_list[:3], 1):\n",
    "    relationships.append({\n",
    "        \"source\": f\"e{1}\",\n",
    "        \"target\": f\"e{i+1}\",\n",
    "        \"type\": rel.get(\"type\", \"related_to\"),\n",
    "        \"properties\": {}\n",
    "    })\n",
    "\n",
    "knowledge_graph = builder.build(entities, relationships)\n",
    "\n",
    "print(f\"Built knowledge graph with {len(knowledge_graph.get('entities', []))} entities\")\n",
    "print(f\"Relationships: {len(knowledge_graph.get('relationships', []))}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 2: Entity Resolution\n",
    "\n",
    "Resolve entity conflicts and duplicates.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from semantica.kg import EntityResolver\n",
    "\n",
    "entity_resolver = EntityResolver()\n",
    "\n",
    "resolved_entities = entity_resolver.resolve(entities)\n",
    "\n",
    "print(f\"Original entities: {len(entities)}\")\n",
    "print(f\"Resolved entities: {len(resolved_entities)}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3: Graph Validation\n",
    "\n",
    "Validate the knowledge graph structure.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from semantica.kg import GraphValidator\n",
    "\n",
    "graph_validator = GraphValidator()\n",
    "\n",
    "validation_result = graph_validator.validate(knowledge_graph)\n",
    "\n",
    "print(f\"Graph validation: {validation_result.get('valid', False)}\")\n",
    "print(f\"Issues: {len(validation_result.get('issues', []))}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 4: Deduplication\n",
    "\n",
    "Remove duplicate entities from the graph.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from semantica.deduplication import DuplicateDetector, EntityMerger, MergeStrategy\n",
    "\n",
    "# Detect duplicates\n",
    "detector = DuplicateDetector(similarity_threshold=0.8)\n",
    "duplicate_groups = detector.detect_duplicate_groups(knowledge_graph.get('entities', []))\n",
    "\n",
    "# Merge duplicates\n",
    "merger = EntityMerger()\n",
    "merge_operations = merger.merge_duplicates(\n",
    "    knowledge_graph.get('entities', []),\n",
    "    strategy=MergeStrategy.KEEP_MOST_COMPLETE\n",
    ")\n",
    "\n",
    "deduplicated_entities = [op.merged_entity for op in merge_operations]\n",
    "\n",
    "print(f\"Original entities: {len(knowledge_graph.get('entities', []))}\")\n",
    "print(f\"Deduplicated entities: {len(deduplicated_entities)}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "You've learned how to build knowledge graphs:\n",
    "\n",
    "- **GraphBuilder**: Construct knowledge graphs from entities and relationships\n",
    "- **EntityResolver**: Resolve entity conflicts and duplicates\n",
    "- **GraphValidator**: Validate graph structure and quality\n",
    "- **Deduplication**: Use `semantica.deduplication` module for removing duplicate entities\n",
    "\n",
    "Next: Learn how to analyze graphs in the Graph_Analytics notebook.\n"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
