semantica/docs/quickstart.md

Quickstart

Get started with Semantica in 5 minutes. This guide will walk you through building your first knowledge graph.

Overview

flowchart LR
    A[Install] --> B[Initialize]
    B --> C[Load Data]
    C --> D[Extract]
    D --> E[Build Graph]
    E --> F[Visualize]
    
    style A fill:#e3f2fd
    style F fill:#c8e6c9

Step 1: Installation

If you haven't installed Semantica yet:

pip install semantica

See the Installation Guide for detailed instructions.

Step 2: Your First Knowledge Graph

Let's build a knowledge graph from a document:

from semantica import Semantica

# Initialize Semantica
semantica = Semantica()

# Build knowledge graph from a document
result = semantica.build_knowledge_base(
    sources=["document.pdf"],
    embeddings=True,
    graph=True
)

# Access results
kg = result["knowledge_graph"]
embeddings = result["embeddings"]
statistics = result["statistics"]

print(f"Extracted {len(kg['entities'])} entities")
print(f"Created {len(kg['relationships'])} relationships")
print(f"Generated {len(embeddings)} embeddings")

Expected Output:

Extracted 45 entities
Created 32 relationships
Generated 45 embeddings

Step 3: Extract Entities and Relationships

Extract structured information from text:

from semantica import Semantica

semantica = Semantica()

# Sample text
text = """
Apple Inc. was founded by Steve Jobs in Cupertino, California in 1976.
The company designs and manufactures consumer electronics and software.
Tim Cook is the current CEO of Apple.
"""

# Extract entities
entities_result = semantica.semantic_extract.extract_entities(text)
entities = entities_result["entities"]

print("Extracted Entities:")
for entity in entities:
    print(f"  - {entity['text']} ({entity['type']})")

# Extract relationships
relationships_result = semantica.semantic_extract.extract_relationships(text)
relationships = relationships_result["relationships"]

print("\nExtracted Relationships:")
for rel in relationships:
    print(f"  - {rel['subject']} --[{rel['predicate']}]--> {rel['object']}")

Expected Output:

Extracted Entities:
  - Apple Inc. (ORGANIZATION)
  - Steve Jobs (PERSON)
  - Cupertino (LOCATION)
  - California (LOCATION)
  - Tim Cook (PERSON)

Extracted Relationships:
  - Apple Inc. --[founded_by]--> Steve Jobs
  - Apple Inc. --[located_in]--> Cupertino
  - Apple Inc. --[has_ceo]--> Tim Cook

Step 4: Build Knowledge Graph from Multiple Sources

Combine data from multiple sources:

from semantica import Semantica

semantica = Semantica()

# Multiple data sources
sources = [
    "documents/research_paper.pdf",
    "documents/company_report.docx",
    "https://example.com/news-article"
]

# Build unified knowledge graph
result = semantica.build_knowledge_base(
    sources=sources,
    embeddings=True,
    graph=True,
    normalize=True
)

kg = result["knowledge_graph"]

# Analyze the graph
print(f"Total entities: {len(kg['entities'])}")
print(f"Total relationships: {len(kg['relationships'])}")
print(f"Sources processed: {len(result['metadata']['sources'])}")

Step 5: Visualize Your Knowledge Graph

Visualize the knowledge graph you created:

from semantica import Semantica

semantica = Semantica()

# Build graph
result = semantica.build_knowledge_base(["document.pdf"])
kg = result["knowledge_graph"]

# Visualize
semantica.kg.visualize(kg, output_path="graph.html")
print("Graph visualization saved to graph.html")

Open graph.html in your browser to see an interactive visualization.

Step 6: Export Your Knowledge Graph

Export your knowledge graph in various formats:

from semantica import Semantica

semantica = Semantica()

# Build graph
result = semantica.build_knowledge_base(["data.pdf"])
kg = result["knowledge_graph"]

# Export to different formats
semantica.export.to_rdf(kg, "output.rdf")      # RDF/XML format
semantica.export.to_json(kg, "output.json")    # JSON format
semantica.export.to_csv(kg, "output.csv")      # CSV format
semantica.export.to_owl(kg, "output.owl")       # OWL ontology format

print("Exported knowledge graph to multiple formats")

Common Patterns

Pattern 1: Process Text Directly

from semantica import Semantica

semantica = Semantica()

text = "Your text content here..."
result = semantica.process_document(text)

Pattern 2: Custom Configuration

from semantica import Semantica, Config

# Create custom configuration
config = Config(
    embeddings=True,
    graph=True,
    normalize=True,
    conflict_resolution="voting"
)

semantica = Semantica(config=config)
result = semantica.build_knowledge_base(["document.pdf"])

Pattern 3: Incremental Building

from semantica import Semantica

semantica = Semantica()

# Build incrementally
kg1 = semantica.kg.build_graph(["source1.pdf"])
kg2 = semantica.kg.build_graph(["source2.pdf"])

# Merge knowledge graphs
merged_kg = semantica.kg.merge([kg1, kg2])

Next Steps

Now that you've built your first knowledge graph:

1. Explore Examples - See more advanced use cases
2. API Reference - Learn about all available methods
3. Cookbook - Interactive Jupyter notebooks
4. Full Documentation - Comprehensive guide

Troubleshooting

Common Issues

Issue: No entities extracted

• Solution: Check that your document contains text content. PDFs with images only won't work without OCR.

Issue: Slow processing

• Solution: For large documents, consider processing in chunks or using GPU acceleration.

Issue: Memory errors

• Solution: Process documents one at a time or reduce batch sizes.

Need help? Check the Installation Troubleshooting or GitHub Issues.