docs: add Exported Classes blocks to all remaining reference docs

Adds ## Exported Classes (or equivalent interface block) to:
- change_management.md, conflicts.md, context.md, embeddings.md
- graph_store.md, ingest.md, normalize.md, pipeline.md
- seed.md, split.md, triplet_store.md, vector_store.md
- visualization.md

Adds ## Launch Interface to explorer.md (CLI-only module).
Adds ## Server Interface to mcp_server.md (stdio process, not importable).

All blocks sourced from module __all__ with inline usage hints.
evals.md intentionally skipped (placeholder, __all__ = []).
This commit is contained in:
KaifAhmad1
2026-05-24 14:56:11 +05:30
parent beacc88b02
commit 68fcff5b3a
15 changed files with 447 additions and 0 deletions
+23
View File
@@ -10,6 +10,29 @@ icon: "clock-rotate-left"
Compliance frameworks supported out of the box: **HIPAA**, **SOX**, **GDPR**, and **FDA 21 CFR Part 11**.
</Note>
## Exported Classes
```python
from semantica.change_management import (
# Change metadata
ChangeLogEntry, # snapshot record: version, author, message, checksum, changes
# Storage backends
VersionStorage, # abstract storage interface
InMemoryVersionStorage, # fast in-memory backend (dev/test only)
SQLiteVersionStorage, # persistent SQLite backend (production)
# Integrity utilities
compute_checksum, # SHA-256 checksum of a graph state
verify_checksum, # verify graph against a stored checksum
# Version managers
TemporalVersionManager, # KG version management: snapshot, diff, rollback
OntologyVersionManager, # ontology version management
BaseVersionManager, # base class for custom version managers
# Ontology versioning (moved from ontology module)
VersionManager, # OWL ontology version control
OntologyVersion, # ontology version metadata dataclass
)
```
## What You Get
<CardGroup cols={2}>
+35
View File
@@ -18,6 +18,41 @@ Semantica's conflict detection makes disagreements explicit and actionable:
- **Logical conflicts** — an entity simultaneously holds two mutually exclusive properties
- **Relationship conflicts** — the same relationship has inconsistent cardinality or properties across sources
## Exported Classes
```python
from semantica.conflicts import (
# Detection
ConflictDetector, # detect value, type, temporal, logical, relationship conflicts
Conflict, # {id, entity_id, attribute, values, sources, conflict_type, severity}
ConflictType, # enum: VALUE_CONFLICT, TYPE_CONFLICT, TEMPORAL_CONFLICT, ...
# Resolution
ConflictResolver, # resolve conflicts with configurable strategy
ResolutionStrategy, # enum: VOTING, CREDIBILITY_WEIGHTED, MOST_RECENT, FIRST_SEEN, ...
ResolutionResult, # outcome of a resolve_conflicts() call
# Convenience strategy aliases
voting, credibility_weighted, most_recent, first_seen, highest_confidence,
manual_review, expert_review,
# Source tracking
SourceTracker, # track which source contributed each property value
SourceReference, # {source_id, credibility, timestamp}
PropertySource, # per-property source attribution record
# Analysis
ConflictAnalyzer, # analyze patterns, severity distribution, source stats
ConflictPattern, # recurring conflict pattern detected across entities
# Investigation
InvestigationGuideGenerator, # generate step-by-step checklists for manual review
InvestigationGuide, # {title, context, steps}
InvestigationStep, # {order, description, check, priority}
# Convenience functions
detect_conflicts, # quick: detect_conflicts(entities, attribute="name")
resolve_conflicts, # quick: resolve_conflicts(conflicts, strategy=voting)
analyze_conflicts, # quick: analyze_conflicts(conflicts)
track_sources, # quick: track_sources(entities)
generate_investigation_guide,# quick: generate_investigation_guide(conflict)
)
```
## What You Get
<CardGroup cols={2}>
+41
View File
@@ -6,6 +6,47 @@ icon: "brain"
`semantica.context` is the memory and decision layer for AI agents. It stores facts with provenance, records decisions as first-class objects with full causal chains, lets agents search their own history to stay consistent across runs, and answers complex queries by traversing the knowledge graph.
## Exported Classes
```python
from semantica.context import (
# High-level interfaces
AgentContext, # primary entry point: store, retrieve, record_decision, find_precedents
DecisionContext, # decision-focused facade (wraps AgentContext + DecisionRecorder)
# Graph primitives
ContextGraph, # in-memory graph: add/get entities, record decisions, find precedents
ContextNode, # {id, label, node_type, properties, embedding, confidence}
ContextEdge, # {source, target, edge_type, weight, properties}
# Memory
AgentMemory, # RAG memory: store(text), retrieve(query, max_results)
MemoryItem, # {id, content, timestamp, conversation_id, embedding, metadata}
# Retrieval
ContextRetriever, # retrieve(query, max_results, use_graph, min_score)
RetrievedContext, # {content, score, source, metadata}
TemporalGraphRetriever, # retrieval with temporal decay weighting
# Entity linking
EntityLinker, # link_entity(text, entity_type) -> LinkedEntity with URI
EntityLink, # {entity_id, uri, source_text, confidence}
LinkedEntity, # {canonical_id, uri, aliases, type, properties}
# Decision tracking models
Decision, # {id, category, scenario, reasoning, outcome, confidence, timestamp}
Policy, # {id, name, conditions, action, priority}
PolicyException, # {policy_id, decision_id, reason, override_authority}
Precedent, # {decision_id, scenario, outcome, similarity, timestamp}
ApprovalChain, # ordered list of approvers for escalation
# Decision tracking classes
DecisionRecorder, # record and persist decisions with embeddings
DecisionQuery, # query decisions: by_category, by_outcome, by_date_range
CausalChainAnalyzer, # trace causality: get_causal_chain, analyze_impact
PolicyEngine, # check_compliance, get_applicable_policies, enforce_policy
# Convenience functions
record_decision, # record_decision(category, scenario, reasoning, outcome, confidence)
find_precedents, # find_precedents(scenario, category, limit)
analyze_decision_impact, # analyze_decision_impact(decision_id)
check_decision_compliance, # check_decision_compliance(decision, policies)
)
```
## What You Get
<CardGroup cols={2}>
+31
View File
@@ -19,6 +19,37 @@ Semantica uses embeddings for:
- **Distance Intelligence** — N×N semantic distance matrices across entity sets
- **Semantic chunking** — detect topic shift boundaries in `TextSplitter(method="semantic_transformer")`
## Exported Classes
```python
from semantica.embeddings import (
# Core generators
EmbeddingGenerator, # main handler: generate_embeddings(text, data_type="text")
TextEmbedder, # text embedding: embed(text), embed_batch(texts)
GraphEmbeddingManager, # embed KG nodes/subgraphs for GraphRAG
VectorEmbeddingManager, # embedding management for vector databases
# Provider stores
OpenAIStore, # OpenAI text-embedding-* API
BGEStore, # BAAI/bge-* via sentence-transformers
FastEmbedStore, # ONNX-accelerated, no CUDA required
LlamaStore, # Ollama local embedding models
ProviderStoreFactory, # create(provider="bge", model="...") factory
# Pooling strategies
MeanPooling, # default — best for retrieval and clustering
MaxPooling, # captures presence of any feature
CLSPooling, # CLS token (BERT-style classification models)
AttentionPooling, # softmax-weighted sum
HierarchicalPooling, # for long documents exceeding context length
PoolingStrategyFactory, # create(strategy="mean") factory
# Convenience functions
embed_text, # embed_text(text, method="sentence_transformers")
generate_embeddings, # generate_embeddings(texts, method="openai")
calculate_similarity, # calculate_similarity(a, b, method="cosine")
pool_embeddings, # pool_embeddings(token_embeddings, strategy="mean")
check_available_providers, # returns {"sentence_transformers": True, ...}
)
```
## What You Get
<CardGroup cols={2}>
+17
View File
@@ -6,6 +6,23 @@ icon: "map"
`semantica.explorer` is a browser-based dashboard for exploring knowledge graphs, managing ontologies, and running visual analyses — no code required after launch.
## Launch Interface
```bash
# Install and launch
pip install semantica[explorer]
# Start the Explorer dashboard
semantica-explorer --graph my_graph.json --port 8000
# Or via Python module
python -m semantica.explorer --graph my_graph.json --port 8000 --host 0.0.0.0
```
<Tip>
`semantica.explorer` is a **server process**, not a Python library. It exposes no importable classes. Use the CLI or `python -m semantica.explorer` to launch.
</Tip>
## What You Get
<CardGroup cols={2}>
+32
View File
@@ -6,6 +6,38 @@ icon: "server"
`semantica.graph_store` provides a single API for persisting and querying knowledge graphs in production graph databases. Swap backends with a one-line change — no application code changes needed.
## Exported Classes
```python
from semantica.graph_store import (
# Core interface
GraphStore, # unified interface: add_node, add_edge, query, find_paths
GraphManager, # store management and operations
NodeManager, # node CRUD operations
RelationshipManager, # relationship CRUD operations
QueryEngine, # Cypher query execution with caching
GraphAnalytics, # centrality, community detection, shortest path
# Backend stores
Neo4jStore, # Neo4j via Bolt — production workloads
ApacheAgeStore, # PostgreSQL + AGE extension
AmazonNeptuneStore, # AWS Neptune — SPARQL/Gremlin/openCypher
FalkorDBStore, # Redis-based — ultra-low latency
# Convenience functions
create_node, # create_node(labels, properties)
create_nodes, # bulk: create_nodes(entities)
create_relationship, # create_relationship(start_id, end_id, rel_type)
create_relationships, # bulk: create_relationships(rels)
get_nodes, # get_nodes(labels, filters)
get_relationships, # get_relationships(start_id, rel_type)
get_neighbors, # get_neighbors(node_id, direction="both")
update_node, # update_node(node_id, properties)
delete_node, # delete_node(node_id)
execute_query, # execute_query(cypher, parameters)
shortest_path, # shortest_path(source, target)
run_analytics, # run_analytics(graph, algorithm)
)
```
## What You Get
<CardGroup cols={2}>
+41
View File
@@ -6,6 +6,47 @@ icon: "database"
`semantica.ingest` is the entry point for loading data into Semantica. Every ingestor returns a list of `DataSource` objects with normalized content and metadata, regardless of the original format.
## Exported Classes
```python
from semantica.ingest import (
# File ingestion (always available)
FileIngestor, # local files and directories: ingest(path, recursive=True)
CloudStorageIngestor, # AWS S3, Google Cloud Storage, Azure Blob Storage
FileObject, # {content, source_id, source_type, metadata, raw_bytes}
FileTypeDetector, # auto-detect file type from extension and magic bytes
ParquetIngestor, # Apache Parquet files and partitioned datasets
XMLIngestor, # XXE-safe lxml XML parsing with optional XSD validation
# Web ingestion (requires beautifulsoup4)
WebIngestor, # web scraping: ingest_url(url), crawl(url, max_pages)
FeedIngestor, # RSS/Atom feeds: ingest_feed(url), monitor_feeds(...)
FeedMonitor, # live feed monitoring with callback on new items
# Stream ingestion
StreamIngestor, # real-time: ingest_kafka/rabbitmq/kinesis/pulsar
KafkaProcessor, # Kafka consumer group processor
RabbitMQProcessor, # AMQP queue processor
KinesisProcessor, # AWS Kinesis stream processor
PulsarProcessor, # Apache Pulsar consumer
# Repository ingestion (requires gitpython)
RepoIngestor, # Git repos: ingest(url_or_path), include_commits=True
# Email ingestion
EmailIngestor, # IMAP/POP3: ingest() with attachment extraction
# Database ingestion
DBIngestor, # SQL: ingest_database(connection_string, include_tables)
SnowflakeIngestor, # Snowflake: ingest_query(sql), ingest_table(name)
OntologyIngestor, # OWL/RDF ontology files: ingest_ontology(path)
# Convenience functions
ingest, # ingest(source, source_type="file") — unified dispatcher
ingest_file, # ingest_file(path, method="directory")
ingest_web, # ingest_web(url, method="url")
ingest_feed, # ingest_feed(url)
ingest_stream, # ingest_stream(topic, ...)
ingest_database, # ingest_database(connection_string, ...)
ingest_parquet, # ingest_parquet(path, columns=[...])
ingest_xml, # ingest_xml(path, validate_xsd=None)
)
```
## What You Get
<CardGroup cols={2}>
+24
View File
@@ -10,6 +10,30 @@ Once configured, any connected AI assistant can extract entities, record decisio
Compatible with **Claude Desktop**, **Windsurf**, **Cline**, **Continue**, **VS Code**, **Roo Code**, **Cursor**, and any MCP-aware client.
## Server Interface
```json
// Configure in your MCP client (Claude Desktop, Windsurf, Cursor, VS Code, etc.)
{
"mcpServers": {
"semantica": {
"command": "semantica-mcp"
}
}
}
```
```bash
# Or run directly
semantica-mcp
# or
python -m semantica.mcp_server
```
<Tip>
`semantica.mcp_server` is a **stdio server process**, not a Python library. It exposes no importable classes — all interaction happens through MCP tool calls from a connected AI client.
</Tip>
## What You Get
<CardGroup cols={2}>
+44
View File
@@ -17,6 +17,50 @@ Unstructured data is inconsistent by nature. Without normalization, the same rea
Normalization collapses these variants before any extractor, deduplicator, or graph builder sees the data — producing cleaner entities, fewer false duplicates, and more reliable downstream results.
## Exported Classes
```python
from semantica.normalize import (
# Text normalization
TextNormalizer, # coordinator: strip_html, normalize_unicode, fix_encoding
UnicodeNormalizer, # NFC/NFD/NFKC/NFKD normalization
WhitespaceNormalizer, # collapse spaces, normalize line endings
SpecialCharacterProcessor, # smart quotes, dashes, diacritics
TextCleaner, # general text cleaning utilities
# Entity normalization
EntityNormalizer, # coordinator: normalize_entity(text, entity_type)
AliasResolver, # resolve "ML" -> "Machine Learning" via dictionary
EntityDisambiguator, # disambiguate("Apple", context=...) with confidence
NameVariantHandler, # normalize("Dr. JOHN P. SMITH Jr.") -> "John P. Smith"
# Date/time normalization
DateNormalizer, # normalize_date(str) -> ISO 8601
TimeZoneNormalizer, # normalize to UTC or target timezone
RelativeDateProcessor, # "3 days ago" -> datetime
TemporalExpressionParser, # "Q2 2023" -> {start, end, type}
# Number normalization
NumberNormalizer, # normalize_number("$1.2B") -> 1200000000.0
UnitConverter, # convert(100, from_unit="km/h", to_unit="m/s")
CurrencyNormalizer, # normalize("$42.50") -> {amount, currency, raw}
ScientificNotationHandler, # parse scientific notation strings
# Data cleaning
DataCleaner, # remove_duplicates, fill_missing
DataValidator, # validate(records, schema={"name": str, "age": int})
DuplicateDetector, # detect duplicate records by similarity threshold
MissingValueHandler, # fill missing values: mean/median/mode/constant
# Language & encoding
LanguageDetector, # detect(text) -> {language, confidence}
EncodingHandler, # detect_encoding, to_utf8, remove_bom
# Convenience functions
normalize_text, # normalize_text(text, method="default")
normalize_entity, # normalize_entity(name, entity_type="Person")
normalize_date, # normalize_date("Jan 1st, 2020")
normalize_number, # normalize_number("$1,234.56")
clean_text, # clean_text(text)
detect_language, # detect_language(text)
resolve_aliases, # resolve_aliases(text, aliases_dict)
)
```
## What You Get
<CardGroup cols={2}>
+36
View File
@@ -6,6 +6,42 @@ icon: "gear"
`semantica.pipeline` lets you chain Semantica components into reproducible, fault-tolerant workflows with parallel execution and configurable error handling. Pipelines are serializable — save them to YAML and reload in any environment.
## Exported Classes
```python
from semantica.pipeline import (
# Pipeline construction
PipelineBuilder, # DSL: add_step, connect_steps, build
Pipeline, # pipeline definition dataclass
PipelineStep, # step definition: name, step_type, handler, dependencies
StepStatus, # enum: PENDING, RUNNING, COMPLETED, FAILED, SKIPPED
PipelineSerializer, # serialize/deserialize pipeline to JSON/YAML
# Execution
ExecutionEngine, # execute_pipeline(pipeline, data) -> ExecutionResult
ExecutionResult, # {success, output, metadata, metrics, errors}
PipelineStatus, # enum: RUNNING, PAUSED, STOPPED
ProgressTracker, # get_progress(pipeline_id) -> {completed, total, pct}
# Failure handling
FailureHandler, # configure strategy: skip/retry/abort
RetryHandler, # retry with exponential backoff
FallbackHandler, # fall back to alternative step on failure
RetryPolicy, # {max_retries, backoff, jitter}
RetryStrategy, # enum: FIXED, EXPONENTIAL, LINEAR
ErrorSeverity, # enum: LOW, MEDIUM, HIGH, CRITICAL
# Parallelism
ParallelismManager, # execute_parallel(tasks, timeout) — thread or process pool
ParallelExecutionResult, # {success, result, error, task_id}
# Resource management
ResourceScheduler, # allocate_resources / release_resources
ResourceType, # enum: CPU, MEMORY, GPU, NETWORK, DISK
# Validation
PipelineValidator, # validate_pipeline(pipeline) -> ValidationResult
# Templates
PipelineTemplateManager, # get_template("full-qa") -> pre-wired Pipeline
PipelineTemplate, # template metadata dataclass
)
```
## Why Use a Pipeline?
You could wire Semantica modules together with plain Python code. Pipelines add:
+10
View File
@@ -6,6 +6,16 @@ icon: "database"
`semantica.seed` gives your knowledge graph a reliable starting point. Rather than building from an empty graph and hoping extraction produces consistent reference data, you load verified, structured sources first — ISO codes, employee rosters, product catalogs, domain taxonomies — then merge freshly extracted data on top.
## Exported Classes
```python
from semantica.seed import (
SeedDataManager, # coordinator: register_source, create_foundation_graph, integrate_with_extracted
SeedDataSource, # {name, source_type, path, config} — dataclass for a registered source
SeedData, # {entities, relationships, metadata} — loaded seed data container
)
```
## What You Get
<CardGroup cols={2}>
+31
View File
@@ -16,6 +16,37 @@ Most LLMs and embedding models have fixed context windows. Documents larger than
Semantica's chunking methods are designed to avoid these failure modes.
## Exported Classes
```python
from semantica.split import (
# Unified splitter (start here)
TextSplitter, # method=: recursive, sentence, token, semantic_transformer,
# entity_aware, relation_aware, code, structural, markdown
Splitter, # alias for TextSplitter (backward compat)
# Data type
Chunk, # {text, start_char, end_char, token_count, metadata, entities, relationships}
# Specialized chunkers
SemanticChunker, # embedding-based semantic boundary detection
StructuralChunker, # heading/section-based splits from ParsedDocument
SlidingWindowChunker, # fixed-size sliding window with overlap
TableChunker, # table-specific chunking
EntityAwareChunker, # KG: preserves named entities across chunk boundaries
RelationAwareChunker, # KG: keeps subject-predicate-object triplets intact
GraphBasedChunker, # splits based on graph community structure
OntologyAwareChunker, # splits respecting ontology concept boundaries
HierarchicalChunker, # multi-level hierarchical chunking
ProvenanceTracker, # track chunk provenance back to source document
# Convenience split functions
split_recursive, # split_recursive(text, chunk_size, chunk_overlap)
split_by_sentences, # split_by_sentences(text)
split_by_tokens, # split_by_tokens(text, chunk_size, tokenizer)
split_semantic_transformer, # split_semantic_transformer(text, threshold)
split_entity_aware, # split_entity_aware(text, entities)
split_relation_aware, # split_relation_aware(text, relationships)
)
```
## What You Get
<CardGroup cols={2}>
+24
View File
@@ -6,6 +6,30 @@ icon: "table"
`semantica.triplet_store` provides W3C-standard RDF storage with full SPARQL query support. Use it when you need semantic web compatibility, OWL reasoning, SPARQL-based queries, or standards-compliant RDF serialization.
## Exported Classes
```python
from semantica.triplet_store import (
# Core interface
TripletStore, # unified: add_triplet, get_triplets, execute_query, bulk_load
QueryEngine, # SPARQL execution: execute_query, optimize_query, plan_query
BulkLoader, # high-volume loading with progress tracking and transaction support
# Backend stores
BlazegraphStore, # Blazegraph REST API (HTTP/HTTPS, Named Graphs, SPARQL 1.1)
JenaStore, # Apache Jena Fuseki (SPARQL 1.1, TDB2, GeoSPARQL)
RDF4JStore, # Eclipse RDF4J (SailRepository, in-memory or native)
# Convenience functions
add_triplet, # add_triplet(subject, predicate, obj)
add_triplets, # bulk: add_triplets(triplets)
get_triplets, # get_triplets(subject=None, predicate=None, obj=None)
delete_triplet, # delete_triplet(subject, predicate, obj)
execute_query, # execute_query(sparql, result_format="json")
optimize_query, # optimize_query(sparql) -> optimized SPARQL string
bulk_load, # bulk_load(file_path, format="turtle")
validate_triplets,# validate_triplets(triplets) -> ValidationResult
)
```
## What You Get
<CardGroup cols={2}>
+36
View File
@@ -6,6 +6,42 @@ icon: "database"
`semantica.vector_store` provides a unified API for storing and searching vector embeddings across all major backends. Swap backends with a one-line change — no application code changes needed.
## Exported Classes
```python
from semantica.vector_store import (
# Core interface
VectorStore, # unified: store_vectors, search_vectors, update_vectors, delete_vectors
VectorIndexer, # build/rebuild FAISS/ANN indices
VectorRetriever, # kNN and hybrid search
VectorManager, # store management and CRUD operations
# Backend stores
FAISSStore, # local disk / in-memory (Flat, IVF, HNSW, PQ index types)
WeaviateStore, # cloud/self-hosted, schema-aware, GraphQL queries
QdrantStore, # cloud/self-hosted, payload filtering
MilvusStore, # highly scalable, partitioning and complex queries
PineconeStore, # managed cloud vector database
PgVectorStore, # PostgreSQL with pgvector extension
# Hybrid & metadata search
HybridSearch, # fuse vector + metadata results (RRF or weighted average)
MetadataFilter, # MetadataFilter().eq("category", "science").gt("year", 2020)
SearchRanker, # configurable re-ranking after fusion
MetadataStore, # inverted index for fast metadata filtering
NamespaceManager, # multi-tenant namespace isolation
# Decision-specific helpers
DecisionEmbeddingPipeline, # end-to-end: record + embed + store + retrieve
quick_decision, # quick_decision(text, entities, outcome) — shorthand record
find_precedents, # find_precedents(scenario, k=5) — similarity search
# Convenience functions
store_vectors, # store_vectors(vectors, metadata)
search_vectors, # search_vectors(query_vector, k=10)
hybrid_search, # hybrid_search(query_vector, filter=...)
update_vectors, # update_vectors(ids, new_vectors)
delete_vectors, # delete_vectors(ids)
create_index, # create_index(index_type="hnsw", dimension=768)
)
```
## What You Get
<CardGroup cols={2}>
+22
View File
@@ -6,6 +6,28 @@ icon: "chart-bar"
`semantica.visualization` renders knowledge graphs, ontologies, embedding spaces, and temporal data as interactive HTML or static images — without launching the full Explorer server.
## Exported Classes
```python
from semantica.visualization import (
# Visualizers
KGVisualizer, # visualize_network(graph), visualize_communities(graph, communities)
OntologyVisualizer, # visualize_hierarchy(ontology), visualize_structure(ontology)
EmbeddingVisualizer, # visualize_2d_projection(embeddings, labels, method="umap")
SemanticNetworkVisualizer, # visualize_network(semantic_network)
AnalyticsVisualizer, # visualize_centrality(analytics), visualize_communities(analytics)
TemporalVisualizer, # visualize_timeline(events), visualize_evolution(snapshots)
# D3Visualizer is listed in __all__ but loaded lazily (requires d3js dependency)
# Convenience functions
visualize_kg, # visualize_kg(graph, output="interactive", method="default")
visualize_ontology, # visualize_ontology(ontology, output="interactive")
visualize_embeddings, # visualize_embeddings(embeddings, labels, method="umap")
visualize_semantic_network, # visualize_semantic_network(network)
visualize_analytics, # visualize_analytics(analytics_result)
visualize_temporal, # visualize_temporal(temporal_data)
)
```
## What You Get
<CardGroup cols={2}>