February 7, 2026 4 min read Python fork

semantica

Abstract

Semantica🧠: Open-Source Semantic Layer & Knowledge Engineering Framework for building Explainable, Auditable, and Trustworthy AI Systems — beyond Text Similarity

Forked from semantica-agi/semantica

The Problem

Enterprise AI pipelines need more than fuzzy text similarity; they must expose why a decision was made, trace every transformation, and enforce domain constraints. Without a dedicated semantic layer, provenance is lost, conflicts go unnoticed, and audits become manual and error‑prone.

What This Does

semantica provides a reusable knowledge‑engineering stack that extracts entities, builds ontologies, and stores provenance‑rich graphs. Core code lives in semantica/ (304 files, 282 Python modules). The CLI (semantica/cli.py) and HTTP server (semantica/server.py) expose the same engine, while semantica/utils/* supply cross‑cutting services such as logging, exception types, and progress tracking. The cookbook supplies 47 notebooks that demonstrate end‑to‑end use‑cases (e.g., cookbook/advanced/09_Semantic_Layer_Construction.ipynb).

Key modules:

semantica/semantic_extract/ner_extractor.py – NER pipeline.
semantica/semantic_extract/triplet_extractor.py – relation extraction.
semantica/graph_store/graph_store.py – abstract graph‑store API (Neptune, SQLite, etc.).

How It Is Wired

Execution starts at semantica/cli.py:main (line 20). The CLI parses sub‑commands (build, run, etc.) and then invokes up to 308 functions across the codebase.

Bootstrap – __init__ of many modules immediately calls utils.logging.get_logger (used by 206 other modules) and utils.progress_tracker.get_progress_tracker (used by 115 modules). These two utilities form the hub whose stability directly affects most of the repository.

Provenance flow – run (implemented in semantica/worker.py:run) creates a track_entity call, which eventually reaches semantica/context/agent_context.py:retrieve and opens a SQLite connection (sqlite3.connect). The shortest external‑touch path is: run → track_entity → retrieve → sqlite3.connect (database write).

Server path – semantica/server.py:health builds a statistics response that calls stats → get_statistics → retrieve_all → sqlite3.connect, again a single‑hop DB read.

Graph store – semantica/graph_store/graph_store.py:execute (line 254) creates a cache key via hashlib.md5, then returns a result after 232 internal calls.

Model inference – semantic_extract/providers.py wraps calls to external transformer models (e.g., sentence‑transformers).

Blast radius – utils.logging, utils.exceptions, and utils.progress_tracker together receive > 200 import edges each; any API change ripples through most of the 671‑file repo.

Cycles – ner_extractor, triplet_extractor, and relation_extractor participate in a circular import, raising the risk of subtle import‑time failures.

External effects – 78 functions read/write files, 23 make network calls (e.g., Neptune), 34 touch a database, 9 invoke LLM inference, and 16 perform cryptographic hashes.

How To Use It

# Install the package (the README shows this)
pip install semantica

Run the CLI

python -m semantica.cli build --method ml --model en_core_web_sm "sample.txt"

cli.py will load the NER extractor, build a graph, and persist provenance in the default SQLite store.

Run the server

python -m semantica.server

The HTTP service exposes /health (calls server.py:health) and graph query endpoints that ultimately hit graph_store/graph_store.py.

Docker – the repo ships docker-compose.yml; building the stack with docker compose up reproduces the same environment, including the Neo4j/Neptune connectors defined under semantica/graph_store/.

Configuration files are not explicit; the code expects environment variables for external stores (e.g., NEPTUNE_ENDPOINT) and reads semantica/conflicts/config.py for runtime flags.

Real‑World Use

A financial‑compliance team can ingest transaction logs, run NERExtractor to tag parties, feed the results to GraphBuilder, and store the graph in Neo4j. The provenance manager records each ingestion step, allowing auditors to query “which document created this relationship?” via the server’s /graph endpoint, while the built‑in conflict detector flags contradictory entity attributes.

Code Health & Issues

Measured static findings (279 total)

High cognitive load – deep nesting (max depth 8) and oversized files (> 1 200 LOC) in utils/progress_tracker.py, semantic_extract/methods.py, semantic_extract/triplet_extractor.py.
Broad exception handling – generic except: blocks in the same modules.
Hub modules – utils/logging.py, utils/exceptions.py, utils/progress_tracker.py each imported by > 180 modules.
Import cycles – semantic_extract/ner_extractor.py, triplet_extractor.py, relation_extractor.py.
High branching density – 578 branches in semantic_extract/methods.py.

Repository‑level health audit (9 findings)

HIGH Pin GitHub Actions to commit SHAs (.github/workflows/*).
HIGH Add a lockfile (poetry.lock / requirements.txt) beside pyproject.toml.
HIGH Run the test suite in CI (no test step present).
HIGH Remove continue-on-error from correctness steps (security.yml).
MEDIUM Declare least‑privilege GITHUB_TOKEN permissions (ci.yml).
MEDIUM Split massive notebook cells (cookbook/advanced/06_Multi_Source_Data_Integration.ipynb).
MEDIUM Move large binaries (> 5 MB) to Git LFS (cookbook/use_cases/blockchain/transaction_network.html).
MEDIUM Set persist-credentials: false on actions/checkout.
LOW Add explicit timeout-minutes to workflow jobs.

The Bottom Line

semantica delivers a concrete, extensible semantic layer with built‑in provenance and conflict detection, suitable for regulated domains that need audit trails. The codebase is functional but suffers from heavy centralisation, deep nesting, and a few CI hygiene gaps; addressing the high‑impact hub modules and CI fixes will markedly improve maintainability and reliability. Engineers ready to embed traceable knowledge graphs will find it usable, provided they allocate effort to refactor the identified hot spots.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

671 files

Python421
Markdown94
Jupyter Notebook47
JSON15
YAML12
TOML2

DockerTransformersVector storepandasNeo4j

Module dependencies

The 10 most depended-upon modules of 421, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_semantica_utils_logging["logging"] n1_semantica_utils_exceptions["exceptions"] n2_ntica_utils_progress_tracker["progress_tracker"] n3_mantic_extract_ner_extractor["ner_extractor"] n4_emantica_provenance___init__["__init__"] n5_ic_extract_triplet_extractor["triplet_extractor"] n6_semantica_utils_helpers["helpers"] n7_c_extract_relation_extractor["relation_extractor"] n8_ica_semantic_extract_methods["methods"] n9_a_semantic_extract_providers["providers"] n8_ica_semantic_extract_methods --> n1_semantica_utils_exceptions n8_ica_semantic_extract_methods --> n0_semantica_utils_logging n8_ica_semantic_extract_methods --> n3_mantic_extract_ner_extractor n8_ica_semantic_extract_methods --> n9_a_semantic_extract_providers n8_ica_semantic_extract_methods --> n7_c_extract_relation_extractor n8_ica_semantic_extract_methods --> n5_ic_extract_triplet_extractor n8_ica_semantic_extract_methods --> n6_semantica_utils_helpers n3_mantic_extract_ner_extractor --> n1_semantica_utils_exceptions n3_mantic_extract_ner_extractor --> n6_semantica_utils_helpers n3_mantic_extract_ner_extractor --> n0_semantica_utils_logging n3_mantic_extract_ner_extractor --> n2_ntica_utils_progress_tracker n3_mantic_extract_ner_extractor --> n8_ica_semantic_extract_methods n9_a_semantic_extract_providers --> n1_semantica_utils_exceptions n9_a_semantic_extract_providers --> n0_semantica_utils_logging n7_c_extract_relation_extractor --> n1_semantica_utils_exceptions n7_c_extract_relation_extractor --> n0_semantica_utils_logging n7_c_extract_relation_extractor --> n2_ntica_utils_progress_tracker n7_c_extract_relation_extractor --> n3_mantic_extract_ner_extractor classDef cyc stroke:#ef4444,stroke-width:2px; class n3_mantic_extract_ner_extractor,n5_ic_extract_triplet_extractor,n7_c_extract_relation_extractor,n8_ica_semantic_extract_methods cyc;

Dependencies

19 of 40 declared dependencies are a major version behind. Resolved 40 of 40 against the registry.

Package	Declared	Latest	Behind
`structlog`	>=22.1.0	26.1.0	4 major
`sentence-transformers`	>=2.2.0	5.7.0	3 major
`pillow`	>=9.2.0	12.3.0	3 major
`rich`	>=12.5.0	15.0.0	3 major
`pandas`	>=1.3.0	3.0.5	2 major
`chardet`	>=5.1.0	7.6.0	2 major
`protobuf`	>=5.29.1,<7.0	7.35.1	2 major
`lxml`	>=4.9.0	6.1.1	2 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

Open in Code Brain → See its neighbourhood →

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high4

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

softprops/action-gh-release@v1, pypa/gh-action-pypi-publish@release/v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Make CI invoke the test suite it hashigh136 occurrences

.github/workflows

136 test files, no test command in any workflow

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Remove continue-on-error from steps that gate correctnesshigh

.github/workflows/security.yml

line 18 on a correctness step

A failing test suite reports a green check, which is precisely the path this audit exists to close.

Fix: Delete continue-on-error, or move a genuinely advisory step into a separate non-required job.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/ci.yml

2 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Split the oversized notebook cell into stepsmedium

cookbook/advanced/06_Multi_Source_Data_Integration.ipynb

largest cell 8445 characters of 45801 (3 notebooks sampled)

A failure anywhere in a 22,000-character cell means rerunning the whole pipeline from load to model, so nothing can be debugged in isolation.

Fix: Break at the load, clean, feature, model and evaluate boundaries.

Move large binaries to Git LFS or out of the repositorymedium

cookbook/use_cases/blockchain/transaction_network.html

1 blobs over 5MB: transaction_network.html 5.1MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Pin the resolution so a vulnerable version cannot installmedium178 occurrences

no lockfile, and the declared ranges reach transformers@4.20.0 CVE-2023-6730 (critical) +49 more; torch@1.12.0 CVE-2022-45907 (critical) +29 more; gitpython@3.1.30 CVE-2023-40267 (critical) +33 more; and 7 more package(s)

The range includes versions with published advisories and nothing in the repository records which one was resolved, so two installs a month apart can differ in whether they are vulnerable and neither is reproducible from what is committed.

Fix: Commit the lockfile, which fixes the resolution and makes this answerable.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/ci.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.

View on GitHub All Projects