mirror of
https://github.com/semantica-agi/semantica.git
synced 2026-08-29 04:26:20 +00:00
docs: apply full Mintlify component overhaul to all 27 reference pages and concepts.md
Replace plain markdown in every docs/reference/ file and docs/concepts.md with rich Mintlify JSX components — CardGroup, Steps, Tabs, AccordionGroup, Tip, Warning, Note, and CodeGroup — for a consistent, navigable, production-grade developer experience.
This commit is contained in:
KaifAhmad1
+352
-131
@@ -8,81 +8,87 @@ icon: "brain"
|
||||
|
||||
## What You Get
|
||||
|
||||
- **`AgentContext`** — unified interface for memory, decision tracking, and graph-backed retrieval
|
||||
- **`ContextGraph`** — persistent knowledge graph with centrality analysis, community detection, and decision management
|
||||
- **`AgentMemory`** — low-level embedding-backed memory with TTL, tagging, and importance scoring
|
||||
- **`DecisionRecorder`** — records decisions with causal chains, confidence scores, and outcome tracking
|
||||
- **`CausalAnalyzer`** — traces downstream impact of any decision
|
||||
- **`PolicyEngine`** — validates decisions against configurable rules before they're recorded
|
||||
<CardGroup cols={2}>
|
||||
<Card title="AgentContext" icon="brain">
|
||||
Unified interface for memory, decision tracking, and graph-backed retrieval.
|
||||
</Card>
|
||||
<Card title="ContextGraph" icon="diagram-project">
|
||||
Persistent knowledge graph with centrality analysis, community detection, and decision management.
|
||||
</Card>
|
||||
<Card title="AgentMemory" icon="database">
|
||||
Embedding-backed memory with TTL, tagging, and importance scoring.
|
||||
</Card>
|
||||
<Card title="DecisionRecorder" icon="list-check">
|
||||
Records decisions with causal chains, confidence scores, and outcome tracking.
|
||||
</Card>
|
||||
<Card title="PolicyEngine" icon="shield-check">
|
||||
Validates decisions against configurable rules before they're recorded.
|
||||
</Card>
|
||||
<Card title="EntityLinker" icon="link">
|
||||
Maps entity mentions to canonical URIs — prevents "Apple", "Apple Inc.", and "AAPL" from becoming three separate nodes.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<img src="/assets/img/diagrams/agent-context-flow.svg" alt="AgentContext hub: AI Agent calls store/retrieve against VectorStore and record_decision against ContextGraph" style={{ width: '100%', borderRadius: '12px', margin: '0 0 24px' }} />
|
||||
|
||||
## Quick Start
|
||||
|
||||
<Steps>
|
||||
<Step title="Initialize the agent context">
|
||||
```python
|
||||
from semantica.context import AgentContext, ContextGraph
|
||||
from semantica.vector_store import VectorStore
|
||||
|
||||
context = AgentContext(
|
||||
vector_store=VectorStore(backend="faiss", dimension=768, index_path="context.faiss"),
|
||||
knowledge_graph=ContextGraph(advanced_analytics=True),
|
||||
decision_tracking=True,
|
||||
)
|
||||
```
|
||||
</Step>
|
||||
<Step title="Store facts and retrieve by semantic similarity">
|
||||
```python
|
||||
memory_id = context.store(
|
||||
"GPT-4 outperforms GPT-3.5 on reasoning benchmarks by 40%",
|
||||
metadata={"source": "openai_blog", "date": "2024-01"}
|
||||
)
|
||||
|
||||
results = context.retrieve("LLM benchmark comparisons", top_k=5)
|
||||
for r in results:
|
||||
print(f"{r['content']} (score: {r['score']:.3f})")
|
||||
```
|
||||
</Step>
|
||||
<Step title="Record decisions with full provenance">
|
||||
```python
|
||||
decision_id = context.record_decision(
|
||||
category="model_selection",
|
||||
scenario="Choose LLM for production reasoning pipeline",
|
||||
reasoning="GPT-4 benchmark advantage justifies 3x cost increase",
|
||||
outcome="selected_gpt4",
|
||||
confidence=0.91,
|
||||
)
|
||||
```
|
||||
</Step>
|
||||
<Step title="Find precedents before new decisions">
|
||||
```python
|
||||
# Search past decisions — prevents contradictory choices across runs
|
||||
precedents = context.find_precedents("model selection reasoning", limit=5)
|
||||
|
||||
for p in precedents:
|
||||
print(f"[{p.category}] {p.outcome} (similarity: {p.similarity:.2f})")
|
||||
print(f" Reasoning: {p.reasoning}")
|
||||
|
||||
# Analyze downstream impact of a past decision
|
||||
influence = context.analyze_decision_influence(decision_id)
|
||||
print(f"Decisions influenced: {len(influence.downstream_decisions)}")
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## AgentContext
|
||||
|
||||
The main entry point. Wraps memory, graph, and decision tracking behind a single API.
|
||||
|
||||
```python
|
||||
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,
|
||||
)
|
||||
```
|
||||
|
||||
### Store and Retrieve Memories
|
||||
|
||||
```python
|
||||
# Store a fact — embedded and indexed automatically
|
||||
memory_id = context.store(
|
||||
"GPT-4 outperforms GPT-3.5 on reasoning benchmarks by 40%",
|
||||
metadata={"source": "openai_blog", "date": "2024-01"}
|
||||
)
|
||||
|
||||
# Retrieve by semantic similarity
|
||||
results = context.retrieve("LLM benchmark comparisons", top_k=5)
|
||||
for r in results:
|
||||
print(f"{r['content']} (score: {r['score']:.3f})")
|
||||
```
|
||||
|
||||
### Record and Search Decisions
|
||||
|
||||
```python
|
||||
decision_id = context.record_decision(
|
||||
category="model_selection",
|
||||
scenario="Choose LLM for production reasoning pipeline",
|
||||
reasoning="GPT-4 benchmark advantage justifies 3x cost increase",
|
||||
outcome="selected_gpt4",
|
||||
confidence=0.91,
|
||||
)
|
||||
|
||||
# Find similar past decisions — prevents inconsistent choices
|
||||
precedents = context.find_precedents("model selection reasoning", limit=5)
|
||||
|
||||
# Analyze downstream impact
|
||||
influence = context.analyze_decision_influence(decision_id)
|
||||
print(f"Decisions influenced: {len(influence.downstream_decisions)}")
|
||||
```
|
||||
|
||||
### Multi-Hop GraphRAG
|
||||
|
||||
```python
|
||||
from semantica.llms import Groq
|
||||
|
||||
llm = Groq(model="llama-3.3-70b-versatile")
|
||||
result = context.query_with_reasoning(
|
||||
query="What technologies have we chosen and why?",
|
||||
llm_provider=llm,
|
||||
max_hops=2,
|
||||
)
|
||||
|
||||
print(result["response"])
|
||||
for step in result["reasoning_path"]:
|
||||
print(f" {step}")
|
||||
```
|
||||
|
||||
### Constructor Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
@@ -106,6 +112,23 @@ for step in result["reasoning_path"]:
|
||||
| `query_with_reasoning(query, llm_provider, max_hops)` | `Dict` | GraphRAG with multi-hop traversal |
|
||||
| `get_context_insights()` | `Dict` | Analytics summary |
|
||||
|
||||
### Multi-Hop GraphRAG
|
||||
|
||||
```python
|
||||
from semantica.llms import Groq
|
||||
|
||||
llm = Groq(model="llama-3.3-70b-versatile")
|
||||
result = context.query_with_reasoning(
|
||||
query="What technologies have we chosen and why?",
|
||||
llm_provider=llm,
|
||||
max_hops=2,
|
||||
)
|
||||
|
||||
print(result["response"])
|
||||
for step in result["reasoning_path"]:
|
||||
print(f" {step}")
|
||||
```
|
||||
|
||||
## ContextGraph
|
||||
|
||||
The knowledge graph backing `AgentContext`. Can be used standalone for relationship modelling.
|
||||
@@ -115,12 +138,10 @@ from semantica.context import ContextGraph
|
||||
|
||||
graph = ContextGraph(advanced_analytics=True)
|
||||
|
||||
# Add nodes and edges
|
||||
graph.add_node("Python", "language", properties={"paradigm": "multi-paradigm"})
|
||||
graph.add_node("FastAPI", "framework", properties={"language": "Python"})
|
||||
graph.add_edge("Python", "FastAPI", "enables")
|
||||
|
||||
# Decision management
|
||||
decision_id = graph.add_decision_simple(
|
||||
category="technology_choice",
|
||||
scenario="Web API framework selection",
|
||||
@@ -144,7 +165,134 @@ chain = graph.trace_decision_chain(decision_id)
|
||||
| `community_detection` | `bool` | `False` | Louvain community clustering |
|
||||
| `node_embeddings` | `bool` | `False` | Node2Vec embeddings for structural similarity |
|
||||
|
||||
## Decision Data Structure
|
||||
### ContextGraph — Full Method Reference
|
||||
|
||||
| Method | Returns | Description |
|
||||
| ------ | ------- | ----------- |
|
||||
| `add_node(id, label, properties)` | `None` | Add a node to the context graph |
|
||||
| `add_edge(source, target, rel_type, properties)` | `None` | Add a directed edge |
|
||||
| `query_neighbors(node_id, depth)` | `List[ContextNode]` | BFS neighbors up to given depth |
|
||||
| `record_decision(...)` | `str` (decision_id) | Add decision node with causal edges |
|
||||
| `find_precedents(category, limit)` | `List[Decision]` | Recent decisions in this category |
|
||||
| `find_precedents_by_scenario(scenario, limit)` | `List[Decision]` | Semantically similar past scenarios |
|
||||
| `analyze_decision_impact(decision_id)` | `Dict` | Downstream nodes influenced |
|
||||
| `trace_decision_chain(decision_id)` | `CausalChain` | Full causality tree |
|
||||
| `get_decision_insights()` | `Dict` | Aggregate stats across all decisions |
|
||||
| `trace_decision_causality(decision_id)` | `CausalChain` | Alias for `trace_decision_chain` |
|
||||
|
||||
## AgentMemory (Low-Level)
|
||||
|
||||
For fine-grained control over memory storage, TTL, and importance scoring:
|
||||
|
||||
```python
|
||||
from semantica.context import AgentMemory
|
||||
from semantica.vector_store import VectorStore
|
||||
|
||||
memory = AgentMemory(
|
||||
vector_store=VectorStore(backend="faiss", dimension=768),
|
||||
capacity=10_000, # max memories before oldest are evicted
|
||||
ttl_days=90, # memories older than this are auto-expired (None = never)
|
||||
)
|
||||
|
||||
memory_id = memory.store(
|
||||
"Critical compliance rule: all trades must be pre-approved",
|
||||
importance=0.95,
|
||||
tags=["compliance", "trading"],
|
||||
)
|
||||
|
||||
results = memory.retrieve(
|
||||
query="trade approval requirements",
|
||||
top_k=5,
|
||||
min_importance=0.5,
|
||||
tags=["compliance"],
|
||||
)
|
||||
|
||||
memory.update(memory_id, importance=1.0)
|
||||
memory.forget(memory_id)
|
||||
all_memories = memory.get_all()
|
||||
```
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
| --------- | ---- | ------- | ----------- |
|
||||
| `vector_store` | `VectorStore` | required | Embedding backend for semantic retrieval |
|
||||
| `capacity` | `int` | `1000` | Max items before LRU eviction |
|
||||
| `ttl_days` | `Optional[int]` | `None` | Days before automatic expiry; `None` = keep forever |
|
||||
|
||||
## PolicyEngine
|
||||
|
||||
Validate decisions against configurable rules before they're committed:
|
||||
|
||||
```python
|
||||
from semantica.context import PolicyEngine
|
||||
|
||||
policy = PolicyEngine()
|
||||
policy.add_rule("confidence_threshold", lambda d: d.confidence >= 0.7)
|
||||
policy.add_rule("requires_reasoning", lambda d: len(d.reasoning) >= 20)
|
||||
|
||||
is_valid, violations = policy.validate(decision_data)
|
||||
|
||||
if is_valid:
|
||||
context.record_decision(**decision_data)
|
||||
else:
|
||||
# Create approval chain for manual review
|
||||
chain = policy.create_approval_chain(
|
||||
decision_data,
|
||||
approvers=["manager@company.com", "compliance@company.com"],
|
||||
)
|
||||
print(f"Approval chain created: {chain.chain_id}")
|
||||
```
|
||||
|
||||
## EntityLinker
|
||||
|
||||
Maps extracted entity mentions to canonical URIs — essential for cross-document entity resolution:
|
||||
|
||||
```python
|
||||
from semantica.context import EntityLinker
|
||||
|
||||
linker = EntityLinker()
|
||||
|
||||
entities = [
|
||||
{"text": "Apple Inc.", "type": "ORGANIZATION"},
|
||||
{"text": "Apple", "type": "ORGANIZATION"},
|
||||
{"text": "AAPL", "type": "ORGANIZATION"},
|
||||
]
|
||||
linked = linker.link_entities(entities, sources=["reuters", "sec_filings"])
|
||||
|
||||
for e in linked:
|
||||
print(f"{e.text} → {e.canonical_form} ({e.uri})")
|
||||
print(f" confidence: {e.confidence:.2f}, sources: {e.sources}")
|
||||
```
|
||||
|
||||
## ContextRetriever
|
||||
|
||||
Hybrid retrieval combining vector similarity, graph traversal, and memory — gives richer context than pure vector search:
|
||||
|
||||
```python
|
||||
from semantica.context import ContextRetriever
|
||||
|
||||
retriever = ContextRetriever(
|
||||
vector_store=vector_store,
|
||||
context_graph=context_graph,
|
||||
agent_memory=memory,
|
||||
)
|
||||
|
||||
results = retriever.retrieve(
|
||||
query="What decisions were made about cloud infrastructure?",
|
||||
top_k=10,
|
||||
vector_weight=0.5, # weight of vector similarity results
|
||||
graph_weight=0.3, # weight of graph-traversal results
|
||||
memory_weight=0.2, # weight of agent memory results
|
||||
filters={"category": "infrastructure"},
|
||||
)
|
||||
|
||||
for r in results:
|
||||
print(f"[{r['source']}] score={r['score']:.3f}: {r['content'][:80]}")
|
||||
```
|
||||
|
||||
## Data Structures
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Decision schema">
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
@@ -162,84 +310,157 @@ class Decision:
|
||||
causal_chain: List[str] # IDs of related decisions
|
||||
```
|
||||
|
||||
## AgentMemory (Low-Level)
|
||||
|
||||
For fine-grained control over memory storage, TTL, and importance scoring:
|
||||
</Accordion>
|
||||
<Accordion title="Precedent schema">
|
||||
|
||||
```python
|
||||
from semantica.context import AgentMemory
|
||||
|
||||
memory = AgentMemory(
|
||||
vector_store=VectorStore(backend="faiss", dimension=768),
|
||||
max_memories=10_000,
|
||||
ttl_days=90,
|
||||
)
|
||||
|
||||
memory.store("Important fact", importance=0.9, tags=["compliance"])
|
||||
results = memory.retrieve("fact query", top_k=5, min_importance=0.5)
|
||||
memory.forget(memory_id)
|
||||
@dataclass
|
||||
class Precedent:
|
||||
decision_id: str
|
||||
similarity: float # 0–1 match score to current scenario
|
||||
category: str
|
||||
scenario: str
|
||||
outcome: str
|
||||
reasoning: str
|
||||
confidence: float
|
||||
timestamp: datetime
|
||||
```
|
||||
|
||||
## PolicyEngine
|
||||
|
||||
Validate decisions against configurable rules before they're committed:
|
||||
</Accordion>
|
||||
<Accordion title="PolicyException schema">
|
||||
|
||||
```python
|
||||
from semantica.context import PolicyEngine
|
||||
|
||||
policy = PolicyEngine()
|
||||
policy.add_rule("confidence_threshold", lambda d: d.confidence >= 0.7)
|
||||
policy.add_rule("requires_reasoning", lambda d: len(d.reasoning) >= 20)
|
||||
|
||||
# Validate before recording
|
||||
is_valid, violations = policy.validate(decision_data)
|
||||
if is_valid:
|
||||
context.record_decision(**decision_data)
|
||||
@dataclass
|
||||
class PolicyException:
|
||||
exception_id: str
|
||||
policy_rule: str # name of the rule that was violated
|
||||
decision_id: str # the decision that triggered the exception
|
||||
justification: str # why the exception was granted
|
||||
approved_by: str # approver identity
|
||||
timestamp: datetime
|
||||
expiry: Optional[datetime]
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="ApprovalChain schema">
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ApprovalChain:
|
||||
chain_id: str
|
||||
decision_id: str
|
||||
steps: List[ApprovalStep]
|
||||
status: str # "pending" | "approved" | "rejected"
|
||||
created_at: datetime
|
||||
|
||||
@dataclass
|
||||
class ApprovalStep:
|
||||
step_id: str
|
||||
approver: str
|
||||
required: bool
|
||||
status: str # "pending" | "approved" | "rejected"
|
||||
comment: Optional[str]
|
||||
timestamp: Optional[datetime]
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="LinkedEntity schema">
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class LinkedEntity:
|
||||
text: str
|
||||
canonical_form: str # normalized primary name
|
||||
uri: str # e.g. "http://dbpedia.org/resource/Apple_Inc."
|
||||
confidence: float
|
||||
sources: List[str] # source documents that mention this entity
|
||||
aliases: List[str] # all observed surface forms
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Real-World Patterns
|
||||
|
||||
### Healthcare — Treatment Decisions
|
||||
<Tabs>
|
||||
<Tab title="Healthcare — Treatment Decisions">
|
||||
```python
|
||||
from semantica.context import AgentContext
|
||||
from semantica.vector_store import VectorStore
|
||||
|
||||
```python
|
||||
health_agent = AgentContext(
|
||||
vector_store=VectorStore(backend="faiss", dimension=768),
|
||||
decision_tracking=True,
|
||||
)
|
||||
health_agent = AgentContext(
|
||||
vector_store=VectorStore(backend="faiss", dimension=768),
|
||||
decision_tracking=True,
|
||||
)
|
||||
|
||||
health_agent.store("Patient has hypertension, type 2 diabetes")
|
||||
health_agent.store("Patient allergic to penicillin — verified 2024-01")
|
||||
health_agent.store("Patient has hypertension, type 2 diabetes")
|
||||
health_agent.store("Patient allergic to penicillin — verified 2024-01")
|
||||
|
||||
decision_id = health_agent.record_decision(
|
||||
category="treatment_plan",
|
||||
scenario="Hypertension with comorbid diabetes",
|
||||
reasoning="ACE inhibitors are renoprotective in diabetic patients — preferred over beta blockers",
|
||||
outcome="prescribed_lisinopril",
|
||||
confidence=0.91,
|
||||
)
|
||||
decision_id = health_agent.record_decision(
|
||||
category="treatment_plan",
|
||||
scenario="Hypertension with comorbid diabetes",
|
||||
reasoning="ACE inhibitors are renoprotective in diabetic patients — preferred over beta blockers",
|
||||
outcome="prescribed_lisinopril",
|
||||
confidence=0.91,
|
||||
)
|
||||
|
||||
# Check for similar cases
|
||||
precedents = health_agent.find_precedents("hypertension diabetes", limit=5)
|
||||
```
|
||||
precedents = health_agent.find_precedents("hypertension diabetes", limit=5)
|
||||
for p in precedents:
|
||||
print(f"Past decision: {p.outcome} (similarity: {p.similarity:.2f})")
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Finance — Loan Decisions">
|
||||
```python
|
||||
from semantica.context import AgentContext
|
||||
from semantica.vector_store import VectorStore
|
||||
|
||||
### Finance — Loan Decisions
|
||||
loan_agent = AgentContext(
|
||||
vector_store=VectorStore(backend="faiss", dimension=768),
|
||||
decision_tracking=True,
|
||||
)
|
||||
|
||||
```python
|
||||
loan_agent = AgentContext(
|
||||
vector_store=VectorStore(backend="faiss", dimension=768),
|
||||
decision_tracking=True,
|
||||
)
|
||||
loan_agent.store("Applicant: credit score 750, DTI 28%, stable employment 4yr")
|
||||
|
||||
loan_agent.store("Applicant: credit score 750, DTI 28%, stable employment 4yr")
|
||||
decision_id = loan_agent.record_decision(
|
||||
category="loan_approval",
|
||||
scenario="First-time homebuyer — 30yr fixed, 20% down",
|
||||
reasoning="Credit score above threshold, DTI within limits, stable income verified",
|
||||
outcome="approved_300k",
|
||||
confidence=0.94,
|
||||
)
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
decision_id = loan_agent.record_decision(
|
||||
category="loan_approval",
|
||||
scenario="First-time homebuyer — 30yr fixed, 20% down",
|
||||
reasoning="Credit score above threshold, DTI within limits, stable income verified",
|
||||
outcome="approved_300k",
|
||||
confidence=0.94,
|
||||
)
|
||||
```
|
||||
## Tips and Common Pitfalls
|
||||
|
||||
<Warning>
|
||||
**Persist your vector store between runs.** Use `VectorStore(backend="faiss", index_path="context.faiss")` — without a path, the FAISS index lives in memory and is lost on shutdown. An agent that forgets everything on restart isn't an agent.
|
||||
</Warning>
|
||||
|
||||
<Warning>
|
||||
**Enable `decision_tracking=True` from the start.** Adding it retroactively means historical decisions aren't linked to the causal chain — you lose the ability to trace how one decision influenced later ones. Enable it at agent initialization, even if you're not using it immediately.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
**Use `find_precedents()` before every significant decision.** This is how the context module prevents agents from making contradictory choices across runs. If precedents exist, surface them to the LLM as context — "we chose X for similar reasons before."
|
||||
</Tip>
|
||||
|
||||
<Tip>
|
||||
**Set `ttl_days` to avoid memory bloat.** Without TTL, `AgentMemory` accumulates indefinitely. For operational agents, 30–90 day TTL keeps memory relevant to current context. Compliance-critical agents may need `ttl_days=None` (keep forever) with explicit archival.
|
||||
</Tip>
|
||||
|
||||
<Warning>
|
||||
**Use `PolicyEngine` before recording irreversible decisions.** Decisions recorded with `record_decision()` become part of the causal chain immediately. If you need a human approval gate, validate first with `policy.validate()` and create an `ApprovalChain` — don't record until approved.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
**`ContextRetriever` is richer than direct vector search.** The three-channel fusion (vector + graph + memory) surfaces results that pure vector search misses — especially for decisions with complex causal relationships. Use it when you need comprehensive context assembly, not just semantic similarity.
|
||||
</Tip>
|
||||
|
||||
<Tip>
|
||||
**`EntityLinker` prevents entity proliferation.** Without it, "Apple", "Apple Inc.", and "AAPL" land as three separate nodes in `ContextGraph`. Run `EntityLinker` on mentions before storing them to maintain a clean, canonical graph.
|
||||
</Tip>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Vector Store" icon="database" href="vector_store">
|
||||
|
||||
Reference in New Issue
Block a user