🧠 Semantica

用于构建上下文图和 AI 决策智能层的框架

⭐ 给我们点个 Star • 🍴 Fork 我们 • 💬 加入我们的 Discord • 🐦 在 X 上关注我们

将混沌转化为智能。构建具备上下文图、决策追踪和高级知识工程的 AI 系统，使其可解释、可追溯且值得信赖——而不是黑箱。

问题

如今的 AI 代理虽然功能强大，却缺乏可信度：

• 无记忆结构 — 代理存储的是嵌入向量，而非语义信息。检索结果模糊不清，无法追问“为何会召回该内容”。
• 无决策轨迹 — 代理持续做出决策，却未记录任何信息。一旦出现问题，便无历史记录可供调试或审计。
• 无出处溯源 — 输出结果无法追溯到原始事实来源。在受监管的行业中，这成为合规性障碍。
• 推理透明度不足 — 黑箱式的回答，缺乏对结论得出过程的解释。
• 无冲突检测机制 — 相互矛盾的事实会在向量存储中悄然共存，导致输出结果不可预测。

这些问题并非边缘情况，而是阻碍 AI 在医疗、金融、法律和政府等领域部署的根本原因，除非从头构建定制化的安全防护机制。

解决方案

Semantica 是您为 AI 技术栈添加的 上下文与智能层：

• 上下文图 — 由您的代理在运行过程中构建的实体、关系和决策的结构化图谱。可查询、可追溯、持久化存储。
• 决策智能 — 每个决策都是第一类对象：被记录、以因果关系链接、可通过先例搜索，并可分析其下游影响。
• 出处溯源 — 每条事实都与其来源相关联。符合 W3C PROV-O 标准。从数据摄入到推理的完整 lineage。
• 推理引擎 — 前向链式推理、Rete 网络、演绎推理、溯因推理以及 SPARQL 推理。提供可解释的推理路径，而非黑箱答案。
• 去重与质量保证 — 冲突检测、实体解析和验证内置于管道中。

Semantica 可与 LangChain、LlamaIndex、AutoGen、CrewAI 以及任何 LLM 提供商协同工作。它并非替代品，而是位于顶层的责任保障层。

⚡ 快速安装

pip install semantica

v0.3.0 新特性

首个稳定版本 — PyPI 上标记为 Production/Stable。分三个阶段发布：0.3.0-alpha、0.3.0-beta 和 0.3.0 稳定版。

完整按贡献者划分的说明请参阅 RELEASE_NOTES.md，完整变更日志请参阅 [CHANGELOG.md]。

尚未发布 / 即将推出

功能

上下文与决策智能

• 上下文图 — 实体、关系和决策的结构化图谱；可查询、具因果关系、持久化存储
• 决策追踪 — 使用 add_decision() 和 record_decision() 记录、链接并分析每个代理决策
• 因果链条 — 使用 add_causal_relationship() 链接决策，用 trace_decision_chain() 追踪其沿袭
• 先例搜索 — 使用 find_similar_decisions() 对过往决策进行混合相似度搜索
• 影响力分析 — analyze_decision_impact() 和 analyze_decision_influence() — 了解决策的下游效应
• 政策引擎 — 使用 check_decision_rules() 强制执行业务规则；实现自动化合规验证
• 代理记忆 — AgentMemory 提供短期/长期存储、对话历史和统计数据
• 跨系统上下文捕获 — capture_cross_system_inputs() 用于多代理流水线

知识图谱

• 知识图谱构建 — 实体、关系、属性、类型化边
• 图算法 — PageRank、介数中心性、聚类系数、社区发现
• 节点嵌入 — 通过 NodeEmbedder 生成 Node2Vec 嵌入
• 相似度 — 通过 SimilarityCalculator 计算余弦相似度
• 链接预测 — 通过 LinkPredictor 评分潜在的新边
• 时序图 — 考虑时间的节点和边
• 增量/差异处理 — 在不完全重新计算的情况下更新图

语义抽取

• 实体抽取 — 命名实体识别、归一化、分类
• 关系抽取 — 使用大语言模型或基于规则的方法从原始文本中生成三元组
• 大语言模型类型化抽取 — 抽取带有类型化关系元数据的结果
• 去重 v1 — Jaro-Winkler 相似度、基础分块
• 去重 v2 — blocking_v2、hybrid_v2、semantic_v2 策略，配合 max_candidates_per_entity
• 三元组去重 — 使用 dedup_triplets() 移除重复的 (主体, 谓语, 客体) 三元组

推理引擎

• 正向链式推理 — 使用 IF/THEN 字符串规则和字典事实的 Reasoner
• Rete 网络 — 高吞吐量生产规则匹配的 ReteEngine
• 演绎推理 — 用于经典推理的 DeductiveReasoner
• 溯因推理 — 根据观测结果生成假设的 AbductiveReasoner
• SPARQL 推理 — 用于 RDF 图上基于查询的推理的 SPARQLReasoner

来源追踪与可审计性

• 实体来源追踪 — ProvenanceTracker.track_entity(id, source_url, metadata)
• 算法来源追踪 — AlgorithmTrackerWithProvenance 追踪计算 lineage
• 图构建者来源追踪 — GraphBuilderWithProvenance 记录来自 URL 的实体来源 lineage
• W3C PROV-O 兼容 — 所有模块的 lineage 追踪
• 变更管理 — 使用校验和进行版本控制，提供审计轨迹和支持合规性

向量存储

• 后端 — FAISS、Pinecone、Weaviate、Qdrant、Milvus、PgVector、内存中存储
• 语义搜索 — 按嵌入相似度检索 top-k 结果
• 混合搜索 — 向量 + 关键词，权重可配置
• 过滤搜索 — 基于元数据对任意字段进行过滤
• 自定义相似度权重 — 针对不同用例调整检索方式

🌐 图数据库支持

• AWS Neptune — 带有 IAM 认证的 Amazon Neptune 图数据库
• Apache AGE — PostgreSQL 图扩展，通过 SQL 支持 openCypher
• FalkorDB — 原生支持；DecisionQuery 和 CausalChainAnalyzer 可直接处理 FalkorDB 的行/表头格式

数据摄入

• 文件格式 — PDF、DOCX、HTML、JSON、CSV、Excel、PPTX、压缩包
• 网页爬取 — 可配置深度的 WebIngestor
• 数据库 — 支持 SQL 查询的 DBIngestor
• Snowflake — SnowflakeIngestor 支持表/查询摄入、分页以及密钥对/OAuth 认证
• Docling — 高级文档解析，支持表格和版面提取（PDF、DOCX、PPTX、XLSX）
• 媒体 — 图像 OCR、音频/视频元数据提取

导出格式

• RDF — Turtle (.ttl)、JSON-LD、N-Triples (.nt)、XML，通过 RDFExporter 输出
• Parquet — ParquetExporter 用于导出实体、关系及完整知识图谱
• ArangoDB AQL — 通过 ArangoAQLExporter 生成可直接运行的 INSERT 语句
• OWL 本体 — 将生成的本体以 Turtle 或 RDF/XML 格式导出
• SHACL 形状 — 通过 RDFExporter.export_shacl() 自动导出约束形状（.ttl、.jsonld、.nt、.shacl）

流水线与生产

• 流水线构建器 — PipelineBuilder 支持阶段串联和平行工作进程
• 验证 — PipelineValidator 在执行前返回 ValidationResult(valid, errors, warnings)
• 失败处理 — FailureHandler 提供 RetryPolicy 和 RetryStrategy（指数退避、固定等）
• 并行处理 — 可为每个流水线阶段配置工作进程数量
• 大语言模型提供商 — 通过 LiteLLM 支持 100 多种模型（OpenAI、Anthropic、Cohere、Mistral、Ollama 等）

本体

• 自动生成 — 通过 OntologyGenerator 从知识图谱推导 OWL 本体
• 导入 — 通过 OntologyImporter 加载现有的 OWL、RDF、Turtle、JSON-LD 本体
• 验证 — 兼容 HermiT/Pellet 的一致性检查
• SHACL 形状生成 — OntologyEngine.to_shacl() 会自动从任何 Semantica 本体字典中推导出 SHACL 节点和属性形状，无需手动编写，且具有确定性（同一本体生成相同形状）
• SHACL 验证 — OntologyEngine.validate_graph() 会将形状应用于数据图，并返回包含机器可读违规信息及英文说明的 SHACLValidationReport
• 质量等级 — "basic"（结构 + 基数）、"standard"（+ 枚举、继承）、"strict"（+ sh:closed 拒绝未声明的属性）
• 继承传播 — 子形状会自动包含所有祖先属性形状（最多 3 层以上），且循环安全
• 三种输出格式 — Turtle (.ttl)、JSON-LD、N-Triples；可通过 export_shacl() 导出文件

模块

⚡ 快速入门

import semantica
from semantica.context import AgentContext, ContextGraph
from semantica.vector_store import VectorStore

# 构建具有结构化上下文的智能体
context = AgentContext(
    vector_store=VectorStore(backend="faiss", dimension=768),
    knowledge_graph=ContextGraph(advanced_analytics=True),
    decision_tracking=True,
    kg_algorithms=True,
)

# 存储记忆
memory_id = context.store(
    "GPT-4在推理基准测试中比GPT-3.5高出40%",
    conversation_id="research_session_1",
)

# 记录带有完整上下文的决策
decision_id = context.record_decision(
    category="model_selection",
    scenario="为生产推理流水线选择大模型",
    reasoning="GPT-4的基准优势足以证明其价格高出3倍的合理性",
    outcome="selected_gpt4",
    confidence=0.91，
    entities=["gpt4", "gpt35", "reasoning_pipeline"],
)

# 查找历史中的相似决策
precedents = context.find_precedents("模型选择推理", limit=5)

# 分析该决策的下游影响
influence = context.analyze_decision_influence(decision_id)

📖 完整快速入门 • 🍳 食谱示例 • 💬 加入Discord • ⭐ 给我们点个赞

核心价值主张

关键特性与优势

不只是又一个智能体框架

Semantica补充了 LangChain、LlamaIndex、AutoGen、CrewAI、Google ADK、Agno等框架，通过以下方式增强您的智能体：

非常适合高风险应用场景

驱动您的 AI 技术栈

• 上下文图谱 — 带有实体关系和语义上下文的结构化知识表示
• 决策追踪系统 — 全面的决策生命周期管理，支持先例检索与因果分析
• GraphRAG 系统 — 结合图推理与混合搜索的检索系统，采用知识图谱算法
• AI 代理 — 可信、可问责的多智能体系统，具备语义记忆与决策历史
• 推理模型 — 提供带有推理路径与影响分析的可解释 AI 决策
• 企业级 AI — 受治理、可审计的平台，支持合规性与政策执行

集成

• Docling 支持 — 文档解析与表格提取（PDF、DOCX、PPTX、XLSX）
• AWS Neptune — 支持 Amazon Neptune 图数据库，并提供 IAM 身份验证
• Apache AGE — PostgreSQL 图扩展后端（通过 SQL 使用 openCypher）
• Snowflake — 原生数据摄取工具 SnowflakeIngestor；支持表/查询摄取、分页、密钥对及 OAuth 认证
• 自定义本体导入 — 导入现有本体（OWL、RDF、Turtle、JSON-LD）

专为需要每一条回答都可解释且受监管的环境打造。

上下文图谱与决策追踪

Semantica 的旗舰模块。将您的代理所做的每一个决策以结构化的图节点形式记录下来——包含因果链接、先例检索、影响分析以及政策执行。

from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

# 记录一笔贷款审批决策
loan_id = graph.add_decision(
    category="loan_approval",
    scenario="抵押贷款申请 — 信用评分780，DTI 28%",
    reasoning="良好的信用记录，稳定收入8年，低 DTI",
    outcome="批准",
    confidence=0.95,
)

# 记录下游的从属决策
rate_id = graph.add_decision(
    category="interest_rate",
    scenario="为已批准的抵押贷款设定利率",
    reasoning="优质申请人符合最低等级利率条件",
    outcome="利率定为6.2%",
    confidence=0.98，
)

# 将两个决策以因果关系连接
graph.add_causal_relationship(loan_id, rate_id, relationship_type="enables")

# 使用混合相似度查找类似的历史决策
similar    = graph.find_similar_decisions("抵押贷款审批", max_results=5)
chain      = graph.trace_decision_chain(loan_id)
impact     = graph.analyze_decision_impact(loan_id)
compliance = graph.check_decision_rules({"category": "loan_approval", "confidence": 0.95})
insights   = graph.get_decision_insights()

from semantica.context import AgentContext, AgentMemory
from semantica.vector_store import VectorStore

context = AgentContext(
    vector_store=VectorStore(backend="inmemory"),
    knowledge_graph=ContextGraph(advanced_analytics=True),
    decision_tracking=True,
    graph_expansion=True,
    kg_algorithms=True,
)

context.store("欧盟法规 2024/1689 要求高风险 AI 必须具备可解释性", conversation_id="compliance_review")
context.store("我们的欺诈模型会标记 0.3% 的交易", conversation_id="compliance_review")

results = context.retrieve("AI 法规中的可解释性要求", limit=3)
history = context.get_conversation_history("compliance_review")
stats   = context.get_statistics()

知识图谱

from semantica.kg import KnowledgeGraph, Entity, Relationship
from semantica.kg import CentralityAnalyzer, NodeEmbedder, LinkPredictor

kg = KnowledgeGraph()

kg.add_entity(Entity(id="transformer", label="Transformer", type="Architecture",
                     properties={"year": 2017, "paper": "Attention Is All You Need"}))
kg.add_entity(Entity(id="bert", label="BERT", type="Model",
                     properties={"year": 2018, "parameters": "340M"}))
kg.add_entity(Entity(id="gpt4", label="GPT-4", type="Model", properties={"year": 2023}))

kg.add_relationship(Relationship(source="bert", target="transformer", type="based_on"))
kg.add_relationship(Relationship(source="gpt4", target="transformer", type="based_on"))

# 图算法
analyzer    = CentralityAnalyzer(kg)
centrality  = analyzer.compute_pagerank()
betweenness = analyzer.compute_betweenness()

# 节点嵌入（Node2Vec）
embedder   = NodeEmbedder()
embeddings = embedder.compute_embeddings(kg, node_labels=["Model"], relationship_types=["based_on"])

# 链接预测
predictor = LinkPredictor()
score     = predictor.score_link(kg, "gpt4", "bert", method="common_neighbors")

models      = kg.find_nodes(type="Model")
descendants = kg.get_neighbors("transformer", direction="incoming")

语义抽取

from semantica.semantic_extract import extract_entities, extract_relations, extract_triplets

text = """
OpenAI 于 2023 年 3 月发布了 GPT-4。微软将 GPT-4 集成到了 Azure OpenAI 服务中。
由前 OpenAI 研究人员创立的 Anthropic 发布了 Claude 作为竞争模型。
"""

entities = extract_entities(text)
# → [Entity(label="OpenAI", type="Organization"), Entity(label="GPT-4", type="Model"), ...]

relations = extract_relations(text)
# → [Relation(source="OpenAI", type="released", target="GPT-4"), ...]

triplets = extract_triplets(text)

from semantica.deduplication import DuplicateDetector

entities = [
    {"id": "e1", "name": "OpenAI Inc.", "type": "Organization"},
    {"id": "e2", "name": "Open AI",    "type": "Organization"},
    {"id": "e3", "name": "Anthropic",  "type": "Organization"},
]

detector   = DuplicateDetector()
duplicates = detector.detect_duplicates(entities, threshold=0.85)
# → [("e1", "e2")]

duplicates_v2 = detector.detect_duplicates(entities, threshold=0.85, strategy="semantic_v2")

推理引擎

from semantica.reasoning import Reasoner

reasoner = Reasoner()
reasoner.add_rule("IF Person(?x) THEN Mortal(?x)")
reasoner.add_rule("IF Employee(?x) AND WorksAt(?x, ?y) THEN HasEmployer(?x, ?y)")

results = reasoner.infer_facts([
    "Person(Socrates)",
    "Employee(Alice)",
    {"source_name": "Alice", "target_name": "OpenAI", "type": "WorksAt"},
])
# → ["Mortal(Socrates)", "HasEmployer(Alice, OpenAI)"]

from semantica.reasoning import ReteEngine

rete = ReteEngine()
rete.add_rule({
    "name": "flag_high_risk_transaction",
    "conditions": [
        {"field": "amount",  "operator": ">",  "value": 10000},
        {"field": "country", "operator": "in", "value": ["IR", "KP", "SY"]},
    ],
    "action": "flag_for_compliance_review",
})
matches = rete.match({"amount": 15000, "country": "IR", "id": "txn_9921"})

from semantica.reasoning import DeductiveReasoner, AbductiveReasoner

deductive = DeductiveReasoner()
deductive.add_axiom("所有 Transformer 模型都使用注意力机制")
deductive.add_fact("BERT 是一种 Transformer")
conclusion = deductive.reason("BERT 是否使用注意力机制？")

abductive = AbductiveReasoner()
abductive.add_observation("模型部署后准确率下降了 12%")
hypotheses = abductive.generate_hypotheses()

# → ["生产数据中的分布偏移", "预处理管道不匹配", ...]

出处追踪

符合 W3C PROV-O 标准的谱系追踪。每个事实都能追溯到其源头。

from semantica.kg import ProvenanceTracker, AlgorithmTrackerWithProvenance

tracker = ProvenanceTracker()
tracker.track_entity("gpt4_benchmark",
    source_url="https://openai.com/research/gpt-4",
    metadata={"metric": "MMLU", "score": 86.4})

algo_tracker = AlgorithmTrackerWithProvenance(provenance=True)
algo_tracker.track_graph_construction(
    algorithm="node2vec",
    input_data={"nodes": 1500, "edges": 4200},
    parameters={"dimensions": 128, "walk_length": 80},
)

sources      = tracker.get_all_sources("gpt4_benchmark")
all_entities = tracker.get_all_entities()

向量存储与混合搜索

from semantica.vector_store import VectorStore

vs = VectorStore(backend="faiss", dimension=768)

vs.store("Transformer 架构彻底革新了自然语言处理",
         metadata={"source": "arxiv", "year": 2017}, id="doc_001")
vs.store("BERT 引入了用于语言理解的双向预训练",
         metadata={"source": "arxiv", "year": 2018}, id="doc_002")

results = vs.search("语言模型中的注意力机制", top_k=5)

results = vs.hybrid_search(
    query="Transformer 预训练",
    top_k=10,
    vector_weight=0.6,
    keyword_weight=0.4,
)

results = vs.search("预训练", top_k=5, filter={"year": 2018})

数据摄取

from semantica.ingest import FileIngestor, WebIngestor, DBIngestor

file_ingestor = FileIngestor(recursive=True)
docs = file_ingestor.ingest("./research_papers/")

web_ingestor = WebIngestor(max_depth=2)
web_docs = web_ingestor.ingest("https://arxiv.org/abs/1706.03762")

db_ingestor = DBIngestor(connection_string="postgresql://user:pass@localhost/kg_db")
db_docs = db_ingestor.ingest(query="SELECT title, abstract FROM papers WHERE year >= 2020")

all_sources = docs + web_docs + db_docs

from semantica.parse import DoclingParser

# 高级表格和布局提取
docling = DoclingParser()
parsed  = docling.parse("financial_report.pdf")

from semantica.ingest import SnowflakeIngestor

# 连接到 Snowflake 并摄取一张表
ingestor = SnowflakeIngestor(
    account="myorg-myaccount",
    user="analyst",
    password="...",
    warehouse="COMPUTE_WH",
    database="ANALYTICS",
    schema="PUBLIC",
)

# 摄取一张表，可选进行过滤和分页
data = ingestor.ingest_table(
    table_name="customer_events",
    where="event_date >= '2024-01-01'",
    limit=10000,
)

# 或者运行自定义 SQL 查询
data = ingestor.ingest_query(
    query="SELECT id, content, tags FROM knowledge_base WHERE active = TRUE",
    batch_size=500,
)

# 转换为 Semantica 文档，供下游流程使用
docs = ingestor.export_as_documents(data, id_field="id", text_fields=["content"])

# 支持通过环境变量进行密钥对和 OAuth 认证：
# SNOWFLAKE_PRIVATE_KEY_PATH、SNOWFLAKE_TOKEN、SNOWFLAKE_AUTHENTICATOR

导出

from semantica.export import RDFExporter、ParquetExporter、ArangoAQLExporter

rdf_exporter = RDFExporter()
turtle   = rdf_exporter.export_to_rdf(kg, format="turtle")
jsonld   = rdf_exporter.export_to_rdf(kg, format="json-ld")
ntriples = rdf_exporter.export_to_rdf(kg, format="nt")

parquet_exporter = ParquetExporter()
parquet_exporter.export_entities(kg,        path="output/entities.parquet")
parquet_exporter.export_relationships(kg,   path="output/relationships.parquet")
parquet_exporter.export_knowledge_graph(kg, path="output/")

aql_exporter = ArangoAQLExporter()
aql_exporter.export(kg, path="output/insert.aql")

流水线编排

from semantica.pipeline import PipelineBuilder、PipelineValidator、FailureHandler
from semantica.pipeline import RetryPolicy、RetryStrategy

builder = (
    PipelineBuilder()
    .add_stage("ingest",      FileIngestor(recursive=True))
    .add_stage("extract",     extract_triplets)
    .add_stage("deduplicate", DuplicateDetector())
    .add_stage("build_kg",    KnowledgeGraph())
    .add_stage("export",      RDFExporter())
    .with_parallel_workers(4)
)

validator = PipelineValidator()
result    = validator.validate(builder)
if result.valid:
    pipeline = builder.build()
    pipeline.run(input_path="./documents/")

retry_policy = RetryPolicy(strategy=RetryStrategy.EXPONENTIAL_BACKOFF, max_retries=3)
handler = FailureHandler()
handler.handle_failure(error=last_error, policy=retry_policy, retry_count=1)

本体论

from semantica.ontology import OntologyGenerator、OntologyImporter

generator = OntologyGenerator()
ontology  = generator.generate(kg)
generator.export(ontology, path="domain_ontology.owl", format="turtle")

importer = OntologyImporter()
ontology = importer.load("existing_ontology.owl")
ontology = importer.load("schema.ttl", format="turtle")
ontology = importer.load("context.jsonld")

SHACL 形状生成与验证

Semantica 将本体论转化为可执行的数据契约。约束层完善了混合推理系统——符号约束（SHACL）与语义检索（嵌入）相结合。

阶段 1 — 从任意本体字典生成形状：

from semantica.ontology import OntologyEngine

engine   = OntologyEngine()
ontology = engine.from_data(data)          # 或 engine.from_text(...) / engine.to_owl(...)

# 生成 SHACL 形状——无需手动编写
shacl_ttl  = engine.to_shacl(ontology)                        # Turtle 字符串（默认）
shacl_jld  = engine.to_shacl(ontology, format="json-ld")      # JSON-LD 字符串
shacl_nt   = engine.to_shacl(ontology, format="n-triples")    # N-Triples 字符串

# 写入文件
engine.export_shacl(ontology, path="shapes/domain.ttl")

质量等级——控制约束严格程度：

# "basic"    — 节点形状、属性路径、数据类型、基数
# "standard" — + 枚举（sh:in）、模式、继承传播  [默认]
# "strict"   — + sh:closed true 在所有形状上（拒绝未声明的属性）

shacl = engine.to_shacl(ontology, quality_tier="strict")

阶段 2 — 根据形状验证图：

import pathlib

report = engine.validate_graph(
    data_graph=pathlib.Path("data/graph.ttl").read_text(),
    ontology=ontology,   # 自动在验证前生成 SHACL
    explain=True,        # 为每项违规添加通俗易懂的解释
)

print(report.summary())
# → "图不符合规范：2 处违规。"

for v in report.violations:
    print(v.explanation)
# → "节点 <https://example.com/john> 缺少必需的属性 <ex:name>。至少需要 1 个值。"

# → “节点 <https://example.com/acme> 在 <ex:employeeCount> 上的值为 '999'，但预期的数据类型是 xsd:string。”

import json
print(json.dumps(report.to_dict(), indent=2))  # 机器可读 — 可输入到 LLM 或流水线中

或者使用预构建的 SHACL 文件进行验证：

report = engine.validate_graph(
    data_graph=graph_turtle_string,
    shacl="shapes/domain.ttl",   # 路径或 SHACL 字符串
)

在 CI 中重新生成形状以检测破坏性本体变更：

python -c "
from semantica.ontology import OntologyEngine
import json, pathlib
engine = OntologyEngine()
onto = engine.from_data(json.loads(pathlib.Path('ontology.json').read_text()))
engine.export_shacl(onto, 'shapes/shapes.ttl')
"
git diff shapes/shapes.ttl   # 检测破坏性本体变更

validate_graph() 需要 pyshacl： pip install semantica[shacl] 形状生成（to_shacl、export_shacl）无需任何可选依赖即可运行。

集成

图数据库

• AWS Neptune — 带有 IAM 认证的 Amazon Neptune
• Apache AGE — 通过 SQL 使用 PostgreSQL + openCypher
• FalkorDB — 原生支持决策查询和因果分析

向量数据库

• FAISS — 高性能稠密向量搜索
• Pinecone — 无服务器且基于 Pod 的托管向量数据库（pip install semantica[vectorstore-pinecone]）
• Weaviate — 基于 GraphQL 的向量存储，具有丰富的模式管理功能（pip install semantica[vectorstore-weaviate]）
• Qdrant — 基于集合的存储，支持负载过滤（pip install semantica[vectorstore-qdrant]）
• Milvus — 具有分区支持和多种索引类型的可扩展存储（pip install semantica[vectorstore-milvus]）
• PgVector — 带有 JSONB 元数据的 PostgreSQL pgvector 扩展（pip install semantica[vectorstore-pgvector]）
• 内存中 — 轻量级、零依赖的存储，适用于开发和测试

数据源

• Snowflake — SnowflakeIngestor 用于表/查询摄取、模式自省、分页以及多种认证方式（密码、密钥对、OAuth、SSO）（pip install semantica[db-snowflake]）

文档解析

• Docling — 支持 PDF、DOCX、PPTX、XLSX，并可提取表格和布局

LLM 提供商

• 通过 LiteLLM 支持 100 多种模型 — OpenAI、Anthropic、Cohere、Mistral、Ollama、Azure、AWS Bedrock 等
• Novita AI — 兼容 OpenAI 的提供商（deepseek/deepseek-v3.2 等）；可通过 NOVITA_API_KEY 进行配置

代理框架

• 补充 LangChain、LlamaIndex、AutoGen、CrewAI、Google ADK 等

Agno — 一流集成 pip install semantica[agno]

Semantica 提供专门的 Agno 集成，包含五个开箱即用的组件：

• AgnoContextStore — 基于图的代理记忆
• AgnoKnowledgeGraph — 多跳 GraphRAG 知识库
• AgnoDecisionKit — 6 种决策智能工具
• AgnoKGToolkit — 7 种知识图谱流水线工具
• AgnoSharedContext — 用于多代理团队的共享上下文图

导出

• RDF：Turtle、JSON-LD、N-Triples、XML · Parquet · ArangoDB AQL

安装

# 核心包
pip install semantica

# 包含所有可选依赖
pip install semantica[all]

# 向量存储后端（仅安装所需）
pip install semantica[vectorstore-pinecone]
pip install semantica[vectorstore-weaviate]
pip install semantica[vectorstore-qdrant]
pip install semantica[vectorstore-milvus]
pip install semantica[vectorstore-pgvector]

# SHACL 验证（validate_graph）
pip install semantica[shacl]

# Snowflake 数据摄取
pip install semantica[db-snowflake]

# 从源码安装
git clone https://github.com/Hawksight-AI/semantica.git
cd semantica
pip install -e ".[dev]"

# 运行测试
pytest tests/

🤝 社区与支持

加入我们的社区

学习资源

企业支持

未来将提供企业支持、专业服务和商业许可。目前，我们通过 Discord 和 GitHub Discussions 提供社区支持。

当前支持：

• 社区支持 - 通过 Discord 和 GitHub Discussions 提供的免费支持
• Bug 报告 - GitHub Issues

未来的企业服务：

• 带有 SLA 的专业支持
• 企业许可
• 定制开发服务
• 优先处理的功能请求
• 专属支持渠道

敬请期待更新！

• AI / ML 工程师 — GraphRAG、可解释代理、决策追踪
• 数据工程师 — 受治理的语义管道，具备完整溯源能力
• 知识工程师 — 大规模本体管理和知识图谱构建
• 高风险领域 — 医疗保健、金融、法律、网络安全、政府

资源

• 文档
• 食谱与笔记本
• 贡献指南
• 变更日志
• 💬 Discord 社区
• 关注 X

贡献

欢迎所有贡献 — Bug 修复、新功能、测试和文档。

1. 分支仓库并创建分支
2. pip install -e ".[dev]"
3. 在修改的同时编写测试
4. 打开 PR 并标记 @KaifAhmad1 进行审查

完整指南请参阅 CONTRIBUTING.md。

pip install semantica

pip install semantica -i https://pypi.tuna.tsinghua.edu.cn/simple

python -c "import semantica; print(semantica.__version__)"

from semantica.context import ContextGraph, AgentMemory
from semantica.decision import DecisionEngine

# 1. 初始化上下文图谱和代理记忆
graph = ContextGraph()
memory = AgentMemory(graph)
decision_engine = DecisionEngine(graph)

# 2. 构建知识图谱 (添加实体和关系)
# 添加实体
graph.add_entity("Patient_001", type="Person", properties={"age": 45, "symptom": "fever"})
graph.add_entity("Medication_A", type="Drug", properties={"name": "Aspirin"})

# 添加关系
graph.add_relationship("Patient_001", "has_symptom", "fever")
graph.add_relationship("Medication_A", "treats", "fever")

# 3. 记录 AI 决策
# 模拟一个 AI 代理做出的治疗决策
decision_id = decision_engine.record_decision(
    agent_id="MedicalAgent_v1",
    action="prescribe",
    target="Medication_A",
    context={"patient": "Patient_001", "reason": "fever_reduction"},
    metadata={"confidence": 0.95}
)

# 4. 建立因果链
# 将决策与之前的观察事实联系起来
decision_engine.add_causal_relationship(
    cause_entity="fever",
    effect_decision=decision_id,
    relationship_type="triggered_by"
)

# 5. 查询与追溯
# 追踪决策链路，查看该决策是如何产生的
chain = decision_engine.trace_decision_chain(decision_id)
print(f"决策链路: {chain}")

# 6. 查找类似先例
# 基于混合相似度搜索过去的类似决策
similar_decisions = decision_engine.find_similar_decisions(
    query_context={"symptom": "fever"},
    top_k=3
)
print(f"相似先例数量：{len(similar_decisions)}")

# 7. 持久化保存 (可选)
# graph.save("my_context_graph.json")