{
 "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/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` and `EntityResolver`.\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",
    "**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": [
    "!pip install semantica\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.label,\n",
    "        \"name\": entity.text,\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.predicate,\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', []))}\")"
   ]
  },
  {
   "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(entities)\n",
    "\n",
    "print(f\"Original entities: {len(entities)}\")\n",
    "print(f\"Resolved entities: {len(resolved_entities)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3: 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",
    "- **Deduplication**: Use `semantica.deduplication` module for removing duplicate entities\n",
    "\n",
    "Next: Learn how to analyze graphs in the Graph_Analytics 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
}