Adds a consistent scope note to README and docs (concepts, FAQ, index)
stating Semantica does not expose or reconstruct an LLM's internal
reasoning/chain-of-thought. It explains and audits the AI system
around the model: context, provenance, policies, decisions, and
execution history.
* docs: add Changelog tab and clean up overview page
- Remove v0.5.0 release banner and stats grid from docs/index.md
- Add Changelog navigation tab to docs/docs.json after FAQ
- Create docs/changelog.md sourced from CHANGELOG.md with full Mintlify
formatting: one accordion per release (Unreleased → v0.0.1), icons,
pip install snippets, Added/Fixed/Security sub-sections, and a change
type legend
* docs: fix broken index#whats-new link in quickstart — point to changelog
- Fix What's new → link in Info banner (now a proper <a> tag, always clickable)
- Replace 4-stat CardGroup on index with inline premium stats row
- Convert every <CardGroup>/<Card> block site-wide to markdown bullet lists:
content sections → bold-title bullets with sub-bullets, nav cards → [Title](href) — description
- Add cursor-animated list item hover effects to custom.css:
green inset left border, subtle background tint, marker color change on hover
- Affects index, getting-started, quickstart, concepts, modules, faq, architecture,
installation, cookbook, glossary, learning-more, explorer-setup, cli-setup,
community, contributing-guide, governance, citation, project-license,
all integrations pages, and all 20+ reference module pages
* fix: replace invalid Mintlify theme 'venus' with 'mint'
* docs: replace em dashes with colons across all docs files
* fix: strip UTF-8 BOM from all docs files (broke frontmatter detection)
- llms.md: replace non-exported Anthropic/Ollama imports with LiteLLM provider-prefix pattern; replace ReasoningEngine with Reasoner; replace create_provider with LiteLLM in YAML config example and tip
- concepts.md: replace ReasoningEngine with Reasoner/ReteEngine/GraphReasoner; fix DatalogReasoner.reason() to evaluate()/query(); replace TemporalKnowledgeGraph with TemporalGraphQuery; replace DistanceCalculator with SimilarityCalculator; replace EntityDeduplicator with DuplicateDetector/EntityMerger
- kg.md: replace non-exported build_knowledge_graph with method_registry.execute()
- semantic_extract.md: replace Anthropic import with LiteLLM
- index.md: replace Anthropic/Ollama imports with LiteLLM
- modules.md: fix TemporalKnowledgeGraph, DistanceCalculator, OntologyManager, ReasoningEngine, DatalogEngine, start_explorer, create_provider across code examples and module index table
- triplet_store.md: replace non-exported NamespacePrefixManager with semantica.ontology.NamespaceManager
Diagrams (docs/assets/img/diagrams/):
- architecture-overview.svg: 4-column layered architecture
- pipeline-flow.svg: 8-step numbered pipeline flow
- kg-structure.svg: entity/relation graph with typed nodes and labeled edges
- graphrag-flow.svg: dual-path retrieval (vector + graph) to LLM to grounded answer
- extraction-pipeline.svg: NER/Relation/Coreference fan-out to Triplet Generator
- agent-context-flow.svg: AgentContext hub with VectorStore and ContextGraph
- reasoning-chain.svg: forward-chaining inference with explanation path
Wordmark logo (light + dark SVG variants):
- Green rounded-square S icon + Semantica text in green
- docs.json updated to use wordmark SVGs for light and dark modes
Pages updated with diagrams:
- index.md, architecture.md, quickstart.md, concepts.md
- reference/kg.md, reference/pipeline.md, reference/semantic_extract.md
- reference/context.md, reference/reasoning.md
- installation.md: revert card title back to "Getting Started" to match
the Tip text that already links to it by that name
- getting-started.md: restore pip install semantica[all] code block that
was removed in the original PR; users need the copy-paste snippet even
when the Installation guide is the canonical reference; also standardize
link text to "Installation" (was "Installation guide")
- index.md: add Installation card as first entry in "Start Here" CardGroup
so the prose ("install first, then open Quickstart") is backed by an
actual card to click
- quickstart.md: standardize link text to "Installation" (was "Installation guide")
Bug 1 — Broken snapshot example:
- Replace graph.add_decision(category=...) with graph.record_decision()
which accepts keyword args (add_decision expects a Decision object)
- Define context = AgentContext(...) before calling context.checkpoint()
and context.diff_checkpoints() — these APIs live on AgentContext, not ContextGraph
Bug 2 — Invalid KG example imports:
- Remove KnowledgeGraph, Entity, Relationship, CentralityAnalyzer — not exported
- Replace with GraphBuilder.build() (dict-based API) and CentralityCalculator
which are the actual public exports from semantica.kg
- Fix pipeline example: KnowledgeGraph() → GraphBuilder()
Bug 3 — Nonexistent SHACL APIs:
- Remove export_shacl() and validate_graph() calls — not on OntologyEngine
- Rewrite SHACL section to use real APIs: from_data(), export_owl(),
validate(), from_text(), to_owl()
- Remove semantica[shacl] install instructions (extra not in pyproject.toml)
Bug 4 — Stale docs version badge:
- docs/index.md: bump version badge and release tag link from v0.3.0 → v0.4.0
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Fixes#433
- ContextGraph.add_decision() now accepts keyword arguments (category,
scenario, reasoning, outcome, confidence, entities, decision_maker)
in addition to a Decision object, matching documented behaviour.
Both call forms return the decision ID string.
- Quickstart snippets in README, getting-started.md, and index.md
changed from VectorStore(backend="faiss") to VectorStore(backend="inmemory")
so they work without faiss-cpu installed.
- docs/reference/context.md methods table updated to reflect the dual
signature of add_decision().
- docs/bugs/quickstart_api_mismatch.md added to track the issue.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Rewrote index.md to match README (tagline, badges, Problem/Solution text)
- Improved getting-started, concepts, quickstart, installation, faq, use-cases, contributing, glossary, learning-more, examples, modules, architecture, cookbook, deep-dive pages: tighter prose, fixed headings/bullets, removed inconsistencies and duplicate sections
- Removed overuse of emojis from headings in integration pages (docling, snowflake)
- Fixed change_management reference page: closed unclosed JSON code block that broke the right TOC, demoted noisy sub-headings to bold text
- CSS layout: widened content area (max-width 1440px grid, left sidebar 11rem, right TOC narrowed to 11rem for broader content), tightened TOC spacing and font size, fixed word-wrap/overflow on TOC links
- Added mkdocs_local.yml for local serving without mkdocs-jupyter plugin
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
- Rewrote index.md to match README (tagline, badges, Problem/Solution text)
- Improved getting-started, concepts, quickstart, installation, faq, use-cases, contributing, glossary, learning-more, examples, modules, architecture, cookbook, deep-dive pages: tighter prose, fixed headings/bullets, removed inconsistencies and duplicate sections
- Removed overuse of emojis from headings in integration pages (docling, snowflake)
- Fixed change_management reference page: closed unclosed JSON code block that broke the right TOC, demoted noisy sub-headings to bold text
- CSS layout: widened content area (max-width 1440px grid, left sidebar 11rem, right TOC narrowed to 11rem for broader content), tightened TOC spacing and font size, fixed word-wrap/overflow on TOC links
- Added mkdocs_local.yml for local serving without mkdocs-jupyter plugin
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Fix invalid Material Design Icons in provenance.md reference cards
- Replace old 'Semantica Updated Logo.png' with new 'Semantica Logo.png'
- Update README.md, docs/index.md, and docs/DOCS_README.md logo references
- Remove old logo files and add new logo to docs assets
- All documentation now uses consistent, valid icons and new branding
- Updated README.md with new logo reference
- Updated docs/index.md with new logo reference
- Updated docs/DOCS_README.md documentation
- Added new clean, professional logo (Semantica Updated Logo.png)
- Removed old illustrated logo (semantica_logo.png)
The new logo is minimal, scales well, and better represents Semantica as an enterprise-grade semantic layer.
- Reduced code examples in all guide pages (getting-started, quickstart, concepts, modules, examples, use-cases, learning-more)
- Added comprehensive cookbook links with descriptions (topics, difficulty, time, use cases)
- Improved structure and organization across all guide pages
- Updated use-cases.md to only include use cases with corresponding cookbooks
- Removed 'Last Updated: 2024' from all documentation files
- Enhanced navigation with better 'Next Steps' sections
- Deleted cookbook/use_cases/healthcare/02_Drug_Interactions_Analysis.ipynb
- Removed Healthcare section from README.md
- Removed Healthcare section from docs/cookbook.md
- Removed Drug Interactions references from STRATEGIES_SUMMARY.md
- Updated cookbook count from 18 to 17 in all documentation
- Updated docs/index.md to reflect 17 cookbooks
- Added grid‑card layouts, icons, and admonitions to all reference pages
- Removed all mkdocstrings ::: directives that caused alias‑resolution errors
- Fixed export module alias issue (RDFExporter) by cleaning the docs
- Updated README‑style sections for better readability
- Added a PowerShell helper script (remove_mkdocstrings.ps1) for future clean‑ups
- Enhanced home page with better problem statements and value propositions
- Fixed badge rendering in hero section
- Improved flowchart visibility with larger fonts and clearer arrows
- Added interactive Mermaid diagrams for Data-to-AI Gap and Semantica Solution
- Enhanced modules.md with class diagrams and code annotations
- Improved concepts.md with deep dive flowcharts and progressive disclosure
- Added architecture diagrams to use-cases.md for Finance and Cybersecurity
- Expanded 'Built For' section to include Data Engineers, Ontologists, and ML Engineers
- Unified color scheme across all flowcharts for consistent visual design
- Add side scrollbars to both left and right sidebars
- Implement gap-free layout with full-width content
- Add Pydantic-style callout boxes (Note, Tip, Warning, Danger)
- Enhance CSS with three-column layout similar to Pydantic
- Add example callout boxes to key documentation pages
- Maintain Semantica's green-brown color scheme
- Reorganize navigation structure (left sidebar: Home, Quickstart, Installation, Cookbook Recipes, Learning More, Deep Dive, API References)
- Add TOC sections on homepage (Features, How to Read this Documentation, Resources)
- Create new pages: learning-more.md, deep-dive.md, community-projects.md, citation.md, license.md
- Add Mermaid diagrams for architecture, workflows, and concepts
- Enhance all documentation pages with better code examples and explanations
- Add custom CSS for modern aesthetic (docs/css/custom.css)
- Update mkdocs.yml with Material theme, Mermaid support, and enhanced features
- Improve user-friendly navigation and clear visual hierarchy
- Add diagrams and charts throughout documentation
Mohd Kaif