diff --git a/README.md b/README.md index ca507b48..7554fa8a 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,6 @@ - --- ## ๐Ÿš€ Why Semantica? @@ -36,30 +35,30 @@ pip install semantica ``` ```python -from semantica.context import AgentContext +from semantica.context import AgentContext, ContextGraph from semantica.vector_store import VectorStore -from semantica.kg import GraphBuilder -# Initialize context with advanced features +# Initialize with enhanced context features vs = VectorStore(backend="faiss", dimension=768) -kg = GraphBuilder().build({"entities": [], "relationships": []}) +kg = ContextGraph(advanced_analytics=True) context = AgentContext( vector_store=vs, knowledge_graph=kg, - enable_decision_tracking=True, - enable_advanced_analytics=True, - enable_kg_algorithms=True, - enable_vector_store_features=True + decision_tracking=True, + advanced_analytics=True, + kg_algorithms=True, + vector_store_features=True, + graph_expansion=True ) -# Store memory with context graphs +# Store memory with automatic context graph building memory_id = context.store( "User is working on a React project with FastAPI", conversation_id="session_1" ) -# Record decision with full context -decision_id = context.record_decision( +# Easy decision recording with convenience methods +decision_id = context.graph_builder.add_decision( category="technology_choice", scenario="Framework selection for web API", reasoning="React ecosystem with FastAPI provides best performance", @@ -67,15 +66,25 @@ decision_id = context.record_decision( confidence=0.92 ) -# Find similar decisions (precedents) -precedents = context.find_precedents_advanced( +# Find similar decisions with advanced analytics +similar_decisions = context.graph_builder.find_similar_decisions( scenario="Framework selection", - use_kg_features=True + max_results=5 ) +# Analyze decision impact and influence +impact = context.graph_builder.analyze_decision_impact(decision_id) + +# Check compliance with business rules +compliance = context.graph_builder.check_decision_rules({ + "category": "technology_choice", + "confidence": 0.92 +}) + print(f"Memory stored: {memory_id}") print(f"Decision recorded: {decision_id}") -print(f"Found {len(precedents)} precedents") +print(f"Found {len(similar_decisions)} similar decisions") +print(f"Compliance check: {compliance.get('compliant', False)}") ``` **[๐Ÿ“– Full Quick Start](#-quick-start)** โ€ข **[๐Ÿณ Cookbook Examples](#-semantica-cookbook)** โ€ข **[๐Ÿ’ฌ Join Discord](https://discord.gg/ggb7vWeP)** โ€ข **[โญ Star Us](https://github.com/Hawksight-AI/semantica)** @@ -144,65 +153,160 @@ print(f"Found {len(precedents)} precedents") --- -## ๐Ÿง  Context Module: Advanced Context Engineering +## ๐Ÿง  Context Module: Advanced Context Engineering & Decision Intelligence -The **Context Module** is Semantica's flagship component, providing sophisticated context management with **context graphs**, **decision tracking**, and **advanced knowledge engineering**. +The **Context Module** is Semantica's flagship component, providing sophisticated context management with **context graphs**, **advanced decision tracking**, **knowledge graph analytics**, and **easy-to-use interfaces**. ### ๐ŸŽฏ Core Capabilities | **Feature** | **Description** | **Use Case** | |------------|-------------|------------| | **Context Graphs** | Structured knowledge representation with entity relationships | Knowledge management, decision support | -| **Decision Tracking** | Complete decision lifecycle with precedent search | Banking approvals, healthcare decisions | -| **KG Algorithms** | Advanced graph analytics (centrality, community detection) | Influence analysis, similarity search | +| **Advanced Decision Tracking** | Complete decision lifecycle with precedent search, causal analysis, and policy enforcement | Banking approvals, healthcare decisions | +| **Easy-to-Use Methods** | 10 convenience methods for common operations without complexity | Rapid development, user-friendly API | +| **KG Algorithms** | Advanced graph analytics (centrality, community detection, Node2Vec) | Influence analysis, similarity search | +| **Policy Engine** | Automated compliance checking with business rules and exception handling | Regulatory compliance, business rules | | **Vector Store Integration** | Hybrid search with custom similarity weights | Advanced retrieval and filtering | | **Memory Management** | Hierarchical memory with short-term and long-term storage | Agent conversation history | -### ๐Ÿš€ Advanced Features +### ๐Ÿš€ Enhanced Features +- **Easy Decision Recording**: `add_decision()` with automatic entity linking +- **Smart Precedent Search**: `find_similar_decisions()` with hybrid similarity +- **Impact Analysis**: `analyze_decision_impact()` with influence scoring +- **Policy Compliance**: `check_decision_rules()` with automated validation +- **Causal Chains**: `trace_decision_chain()` for decision lineage +- **Graph Analytics**: `get_node_importance()`, `analyze_connections()` for insights - **Hybrid Retrieval**: Combines vector search, graph traversal, and keyword matching - **Multi-Hop Reasoning**: Trace relationships across multiple graph hops -- **Decision Influence Analysis**: Understand how decisions impact each other -- **Policy Engine**: Enforce business rules and compliance automatically -- **Causal Chain Analysis**: Trace decision causality and influence paths -- **Entity Linking**: Resolve ambiguities and maintain consistent entity references +- **Production Ready**: Comprehensive error handling and scalability -### Examples +### ๐Ÿ”ง Easy-to-Use API ```python -# Banking Decision System +# Simple usage with convenience methods +from semantica.context import ContextGraph + +graph = ContextGraph(advanced_analytics=True) + +# Add decision with ease +decision_id = graph.add_decision( + category="loan_approval", + scenario="Mortgage application", + reasoning="Good credit score", + outcome="approved", + confidence=0.95 +) + +# Find similar decisions +similar = graph.find_similar_decisions("mortgage", max_results=5) + +# Analyze impact +impact = graph.analyze_decision_impact(decision_id) + +# Check compliance +compliance = graph.check_decision_rules({ + "category": "loan_approval", + "confidence": 0.95 +}) +``` + +### ๐Ÿข Enterprise Integration + +```python +# Full enterprise setup with AgentContext from semantica.context import AgentContext +from semantica.vector_store import VectorStore context = AgentContext( - vector_store=vs, - knowledge_graph=kg, - enable_decision_tracking=True, - enable_kg_algorithms=True + vector_store=VectorStore(backend="faiss"), + knowledge_graph=ContextGraph(advanced_analytics=True), + decision_tracking=True, + kg_algorithms=True, + vector_store_features=True ) -# Record loan decision +# Record decision with full context decision_id = context.record_decision( - category="mortgage_approval", - scenario="First-time homebuyer application", - reasoning="Strong credit score, stable employment", - outcome="approved", - confidence=0.94 + category="fraud_detection", + scenario="Suspicious transaction pattern", + reasoning="Multiple high-value transactions in short timeframe", + outcome="flagged_for_review", + confidence=0.87, + entities=["transaction_123", "customer_456"] ) -# Find similar decisions with KG features -precedents = context.find_precedents_advanced( - scenario="Mortgage application", - use_kg_features=True, - similarity_weights={"semantic": 0.5, "structural": 0.3, "category": 0.2} +# Advanced precedent search with KG features +precedents = context.find_precedents( + "suspicious transaction", + category="fraud_detection", + use_kg_features=True ) -# Analyze decision influence +# Comprehensive influence analysis influence = context.analyze_decision_influence(decision_id) ``` --- -## ๐Ÿšจ The Problem: The Semantic Gap +## AgentContext - Your Agent's Brain + +The main interface that makes your agent intelligent. It handles memory, decisions, and knowledge organization automatically. + +### Quick Start +```python +from semantica.context import AgentContext +from semantica.vector_store import VectorStore + +# Create your intelligent agent +agent = AgentContext(vector_store=VectorStore(backend="inmemory", dimension=384)) + +# Your agent can now remember things +memory_id = agent.store("User asked about Python programming") +print(f"Agent remembered: {memory_id}") + +# And find information when needed +results = agent.retrieve("Python tutorials") +print(f"Agent found {len(results)} relevant memories") +``` + +### Easy Decision Learning +```python +# Your agent learns from its decisions +decision_id = agent.record_decision( + category="content_recommendation", + scenario="User wants Python tutorial", + reasoning="User mentioned being a beginner", + outcome="recommended_basics", + confidence=0.85 +) + +# Your agent can now find similar past decisions +similar_decisions = agent.find_precedents("Python tutorial", limit=3) +print(f"Agent found {len(similar_decisions)} similar past decisions") +``` + +### Getting Smarter Over Time +```python +# Enable all learning features +smart_agent = AgentContext( + vector_store=vector_store, + decision_tracking=True, # Learn from decisions + graph_expansion=True, # Find related information + advanced_analytics=True, # Understand patterns + kg_algorithms=True, # Advanced analysis + vector_store_features=True +) + +# Get insights about your agent's learning +insights = smart_agent.get_context_insights() +print(f"Total decisions learned: {insights.get('total_decisions', 0)}") +print(f"Decision categories: {list(insights.get('categories', {}).keys())}") +``` + +--- + +## The Problem: The Semantic Gap ### Most AI systems fail in high-stakes domains because they operate on **text similarity**, not **meaning**. @@ -248,45 +352,45 @@ The **semantic gap** is the fundamental disconnect between what AI systems can p --- -## ๐Ÿ†š Semantica vs Traditional RAG +## Semantica vs Traditional RAG | Feature | Traditional RAG | Semantica | |:--------|:----------------|:----------| -| **Reasoning** | โŒ Black-box answers | โœ… Explainable reasoning paths | -| **Provenance** | โŒ No provenance | โœ… W3C PROV-O compliant lineage tracking | -| **Search** | โš ๏ธ Vector similarity only | โœ… Semantic + graph reasoning | -| **Quality** | โŒ No conflict handling | โœ… Explicit contradiction detection | -| **Safety** | โš ๏ธ Unsafe for high-stakes | โœ… Designed for governed environments | -| **Compliance** | โŒ No audit trails | โœ… Complete audit trails with integrity verification | +| **Reasoning** | Black-box answers | Explainable reasoning paths | +| **Provenance** | No provenance | W3C PROV-O compliant lineage tracking | +| **Search** | Vector similarity only | Semantic + graph reasoning | +| **Quality** | No conflict handling | Explicit contradiction detection | +| **Safety** | Unsafe for high-stakes | Designed for governed environments | +| **Compliance** | No audit trails | Complete audit trails with integrity verification | --- -## ๐Ÿงฉ Semantica Architecture +## Semantica Architecture -### 1๏ธโƒฃ Input Layer โ€” Governed Ingestion -- ๐Ÿ“„ **Multiple Formats** โ€” PDFs, DOCX, HTML, JSON, CSV, Excel, PPTX -- ๐Ÿ”ง **Docling Support** โ€” Docling parser for table extraction -- ๐Ÿ’พ **Data Sources** โ€” Databases, APIs, streams, archives, web content -- ๐ŸŽจ **Media Support** โ€” Image parsing with OCR, audio/video metadata extraction -- ๐Ÿ“Š **Single Pipeline** โ€” Unified ingestion with metadata and source tracking +### Input Layer โ€” Governed Ingestion +- **Multiple Formats** โ€” PDFs, DOCX, HTML, JSON, CSV, Excel, PPTX +- **Docling Support** โ€” Docling parser for table extraction +- **Data Sources** โ€” Databases, APIs, streams, archives, web content +- **Media Support** โ€” Image parsing with OCR, audio/video metadata extraction +- **Single Pipeline** โ€” Unified ingestion with metadata and source tracking -### 2๏ธโƒฃ Semantic Layer โ€” Trust & Reasoning Engine -- ๐Ÿ” **Entity Extraction** โ€” NER, normalization, classification -- ๐Ÿ”— **Relationship Discovery** โ€” Triplet generation, semantic links -- ๐Ÿ“ **Ontology Induction** โ€” Automated domain rule generation -- ๐Ÿ”„ **Deduplication** โ€” Jaro-Winkler similarity, conflict resolution -- โœ… **Quality Assurance** โ€” Conflict detection, validation -- ๐Ÿ“Š **Provenance Tracking** โ€” W3C PROV-O compliant lineage tracking across all modules -- ๐Ÿง  **Reasoning Traces** โ€” Explainable inference paths -- ๐Ÿ” **Change Management** โ€” Version control with audit trails, checksums, compliance support +### Semantic Layer โ€” Trust & Reasoning Engine +- **Entity Extraction** โ€” NER, normalization, classification +- **Relationship Discovery** โ€” Triplet generation, semantic links +- **Ontology Induction** โ€” Automated domain rule generation +- **Deduplication** โ€” Jaro-Winkler similarity, conflict resolution +- **Quality Assurance** โ€” Conflict detection, validation +- **Provenance Tracking** โ€” W3C PROV-O compliant lineage tracking across all modules +- **Reasoning Traces** โ€” Explainable inference paths +- **Change Management** โ€” Version control with audit trails, checksums, compliance support -### 3๏ธโƒฃ Output Layer โ€” Auditable Knowledge Assets -- ๐Ÿ“Š **Knowledge Graphs** โ€” Queryable, temporal, explainable -- ๐Ÿ“ **OWL Ontologies** โ€” HermiT/Pellet validated, custom ontology import support -- ๐Ÿ”ข **Vector Embeddings** โ€” FastEmbed by default -- โ˜๏ธ **AWS Neptune** โ€” Amazon Neptune graph database support -- ๏ฟฝ **Apache AGE** โ€” PostgreSQL graph extension with openCypher support -- ๏ฟฝ๐Ÿ” **Provenance** โ€” Every AI response links back to: +### Output Layer โ€” Auditable Knowledge Assets +- **Knowledge Graphs** โ€” Queryable, temporal, explainable +- **OWL Ontologies** โ€” HermiT/Pellet validated, custom ontology import support +- **Vector Embeddings** โ€” FastEmbed by default +- **AWS Neptune** โ€” Amazon Neptune graph database support +- **Apache AGE** โ€” PostgreSQL graph extension with openCypher support +- **Provenance** โ€” Every AI response links back to: - ๐Ÿ“„ Source documents - ๐Ÿท๏ธ Extracted entities & relations - ๐Ÿ“ Ontology rules applied @@ -294,27 +398,27 @@ The **semantic gap** is the fundamental disconnect between what AI systems can p --- -## ๐Ÿฅ Built for High-Stakes Domains +## Built for High-Stakes Domains Designed for domains where **mistakes have real consequences** and **every decision must be accountable**: -- **๐Ÿฅ Healthcare & Life Sciences** โ€” Clinical decision support, drug interaction analysis, medical literature reasoning, patient safety tracking -- **๐Ÿ’ฐ Finance & Risk** โ€” Fraud detection, regulatory support (SOX, GDPR, MiFID II), credit risk assessment, algorithmic trading validation -- **โš–๏ธ Legal & Compliance** โ€” Evidence-backed legal research, contract analysis, regulatory change tracking, case law reasoning -- **๐Ÿ”’ Cybersecurity & Intelligence** โ€” Threat attribution, incident response, security audit trails, intelligence analysis -- **๐Ÿ›๏ธ Government & Defense** โ€” Governed AI systems, policy decisions, classified information handling, defense intelligence -- **๐Ÿญ Critical Infrastructure** โ€” Power grid management, transportation safety, water treatment, emergency response -- **๐Ÿš— Autonomous Systems** โ€” Self-driving vehicles, drone navigation, robotics safety, industrial automation +- **Healthcare & Life Sciences** โ€” Clinical decision support, drug interaction analysis, medical literature reasoning, patient safety tracking +- **Finance & Risk** โ€” Fraud detection, regulatory support (SOX, GDPR, MiFID II), credit risk assessment, algorithmic trading validation +- **Legal & Compliance** โ€” Evidence-backed legal research, contract analysis, regulatory change tracking, case law reasoning +- **Cybersecurity & Intelligence** โ€” Threat attribution, incident response, security audit trails, intelligence analysis +- **Government & Defense** โ€” Governed AI systems, policy decisions, classified information handling, defense intelligence +- **Critical Infrastructure** โ€” Power grid management, transportation safety, water treatment, emergency response +- **Autonomous Systems** โ€” Self-driving vehicles, drone navigation, robotics safety, industrial automation --- ## ๐Ÿ‘ฅ Who Uses Semantica? -- **๐Ÿค– AI / ML Engineers** โ€” Building explainable GraphRAG & agents -- **โš™๏ธ Data Engineers** โ€” Creating governed semantic pipelines -- **๐Ÿ“Š Knowledge Engineers** โ€” Managing ontologies & KGs at scale -- **๐Ÿข Enterprise Teams** โ€” Requiring trustworthy AI infrastructure -- **๐Ÿ›ก๏ธ Risk & Compliance Teams** โ€” Needing audit-ready systems +- **AI / ML Engineers** โ€” Building explainable GraphRAG & agents +- **Data Engineers** โ€” Creating governed semantic pipelines +- **Knowledge Engineers** โ€” Managing ontologies & KGs at scale +- **Enterprise Teams** โ€” Requiring trustworthy AI infrastructure +- **Risk & Compliance Teams** โ€” Needing audit-ready systems --- @@ -604,12 +708,12 @@ is_valid = kg_manager.verify_checksum(snapshot) ``` **What We Provide:** -- ๐Ÿ” **Persistent Storage** โ€” SQLite and in-memory backends implemented -- ๐Ÿ“Š **Detailed Diffs** โ€” Entity-level and relationship-level change tracking -- โœ… **Data Integrity** โ€” SHA-256 checksums with tamper detection -- ๐Ÿ“ **Standardized Metadata** โ€” ChangeLogEntry with author, timestamp, description -- โšก **Performance Tested** โ€” Tested with large-scale entity datasets -- ๐Ÿงช **Test Coverage** โ€” Comprehensive test coverage covering core functionality +- **Persistent Storage** โ€” SQLite and in-memory backends implemented +- **Detailed Diffs** โ€” Entity-level and relationship-level change tracking +- **Data Integrity** โ€” SHA-256 checksums with tamper detection +- **Standardized Metadata** โ€” ChangeLogEntry with author, timestamp, description +- **Performance Tested** โ€” Tested with large-scale entity datasets +- **Test Coverage** โ€” Comprehensive test coverage covering core functionality **Compliance Note:** Provides technical infrastructure (audit trails, checksums, temporal tracking) that supports compliance efforts for HIPAA, SOX, FDA 21 CFR Part 11. Organizations must implement additional policies and procedures for full regulatory compliance. @@ -725,11 +829,11 @@ retriever = context.retriever # Access underlying ContextRetriever results = retriever.retrieve( query="What is the user building?", max_results=10, - use_graph_expansion=True + graph_expansion=True ) # Retrieve with context expansion -results = context.retrieve("What is the user building?", use_graph_expansion=True) +results = context.retrieve("What is the user building?", graph_expansion=True) # Query with reasoning and LLM-generated responses llm_provider = Groq(model="llama-3.1-8b-instant", api_key=os.getenv("GROQ_API_KEY")) @@ -745,20 +849,22 @@ reasoned_result = context.query_with_reasoning( - **ContextRetriever**: Performs hybrid retrieval combining vector search, graph traversal, and memory for optimal context relevance - **AgentContext**: High-level interface integrating Context Graph and Context Retriever for GraphRAG applications -#### Context Graphs: Decision Tracking +#### Context Graphs: Advanced Decision Tracking & Analytics ```python from semantica.context import AgentContext, ContextGraph from semantica.vector_store import VectorStore +# Initialize with advanced decision tracking context = AgentContext( vector_store=VectorStore(backend="inmemory", dimension=128), - knowledge_graph=ContextGraph(), - enable_decision_tracking=True, - enable_kg_algorithms=False, # semantic-only precedent search + knowledge_graph=ContextGraph(advanced_analytics=True), + decision_tracking=True, + kg_algorithms=True, # Enable advanced graph analytics ) -decision_id = context.record_decision( +# Easy decision recording with convenience methods +decision_id = context.graph_builder.add_decision( category="credit_approval", scenario="High-risk credit limit increase", reasoning="Recent velocity-check failure and prior fraud flag", @@ -767,10 +873,79 @@ decision_id = context.record_decision( entities=["customer:jessica_norris"], ) -precedents = context.find_precedents( - scenario="High-risk customer credit increase", +# Find similar decisions with advanced analytics +similar_decisions = context.graph_builder.find_similar_decisions( + scenario="credit increase", category="credit_approval", - limit=5, + max_results=5, +) + +# Analyze decision impact and influence +impact_analysis = context.graph_builder.analyze_decision_impact(decision_id) +node_importance = context.graph_builder.get_node_importance("customer:jessica_norris") + +# Check compliance with business rules +compliance = context.graph_builder.check_decision_rules({ + "category": "credit_approval", + "scenario": "Credit limit increase", + "reasoning": "Risk assessment completed", + "outcome": "rejected", + "confidence": 0.78 +}) +``` + +**Enhanced Features:** +- **Easy-to-Use Methods**: 10 convenience methods for common operations +- **Decision Analytics**: Influence analysis, centrality measures, community detection +- **Policy Engine**: Automated compliance checking with business rules +- **Causal Analysis**: Trace decision causality and impact chains +- **Graph Analytics**: Advanced KG algorithms (Node2Vec, centrality, community detection) +- **Hybrid Search**: Semantic + structural + category similarity +- **Production Ready**: Scalable architecture with comprehensive error handling + +## Configuration Options + +### Simple Setup (Most Common) +```python +# Just memory and basic learning +agent = AgentContext(vector_store=vector_store) +``` + +### Smart Setup (Recommended) +```python +# Memory + decision learning +agent = AgentContext( + vector_store=vector_store, + decision_tracking=True, + graph_expansion=True +) +``` + +### Complete Setup (Maximum Power) +```python +# Everything enabled +agent = AgentContext( + vector_store=vector_store, + knowledge_graph=ContextGraph(advanced_analytics=True), + decision_tracking=True, + graph_expansion=True, + advanced_analytics=True, + kg_algorithms=True, + vector_store_features=True +) +``` + +### ContextGraph Options +```python +# Basic knowledge graph +graph = ContextGraph() + +# Advanced knowledge graph +graph = ContextGraph( + advanced_analytics=True, # Enable smart algorithms + centrality_analysis=True, # Find important concepts + community_detection=True, # Find groups of related concepts + node_embeddings=True # Understand concept similarity ) ``` diff --git a/docs/examples.md b/docs/examples.md index 5e52862a..48757e7d 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -332,7 +332,7 @@ from semantica.reasoning import Reasoner context = AgentContext( vector_store=vs, knowledge_graph=kg, - use_graph_expansion=True, + graph_expansion=True, hybrid_alpha=0.7 ) diff --git a/docs/reference/context.md b/docs/reference/context.md index b5833f68..276d2632 100644 --- a/docs/reference/context.md +++ b/docs/reference/context.md @@ -1,767 +1,463 @@ # Context Module Reference -> **The central nervous system for intelligent agents, managing memory, knowledge graphs, context graphs, decision tracking, and advanced context retrieval with KG algorithms and vector store integration.** +> **The intelligent brain for AI agents, providing memory, decision tracking, and knowledge organization with easy-to-use interfaces that make building smart agents simple and effective.** --- -## ๐ŸŽฏ System Overview +## ๐ŸŽฏ Overview -The **Context Module** provides agents with a persistent, searchable, and structured memory system with advanced decision tracking capabilities and **context graphs** for sophisticated knowledge representation, ensuring predictable state management and compatibility with modern vector stores and graph databases. +The **Context Module** gives your AI agents the ability to **remember**, **learn**, and **make smarter decisions** through intelligent memory management and knowledge organization. It's designed to be both powerful for production use and simple enough for rapid development. ### Key Capabilities
-- :material-brain:{ .lg .middle } **Hierarchical Memory** +- :material-brain:{ .lg .middle } **Smart Memory** --- - Mimics human memory with a fast, token-limited Short-Term buffer and infinite Long-Term vector storage. + Human-like memory that stores conversations, learns from experience, and retrieves relevant information when needed. -- :material-graph-outline:{ .lg .middle } **GraphRAG** +- :material-graph-outline:{ .lg .middle } **Decision Intelligence** --- - Combines unstructured vector search with structured knowledge graph traversal for deep contextual understanding. + Track decisions, learn from past choices, and make consistent, improving decisions over time. -- :material-scale-balance:{ .lg .middle } **Hybrid Retrieval** +- :material-lightbulb:{ .lg .middle } **Easy-to-Use API** --- - Intelligently blends Keyword (BM25), Vector (Dense), and Graph (Relational) scores for optimal relevance. + Simple methods that make complex features accessible without overwhelming complexity. -- :material-lightning-bolt:{ .lg .middle } **Token Management** +- :material-search:{ .lg .middle } **Smart Retrieval** --- - Automatic FIFO and importance-based pruning to keep context within LLM window limits. + Find relevant information quickly using hybrid search that understands context and relationships. -- :material-link-variant:{ .lg .middle } **Entity Linking** +- :material-account-tree:{ .lg .middle } **Knowledge Organization** --- - Resolves ambiguities by linking text mentions to unique entities in the knowledge graph. + Build intelligent knowledge graphs that understand relationships and context. -- :material-gavel:{ .lg .middle } **Decision Tracking** +- :material-trending-up:{ .lg .middle } **Learning & Analytics** --- - Complete decision lifecycle management with precedent search, causal analysis, and policy compliance. + Get insights about agent performance, decision patterns, and knowledge growth. -- :material-chart-line:{ .lg .middle } **KG Algorithms** +- :material-security:{ .lg .middle } **Production Ready** --- - Advanced graph analytics including centrality, community detection, embeddings, and link prediction. - -- :material-magnify:{ .lg .middle } **Vector Store Features** - - --- - - Hybrid search with custom similarity weights and advanced filtering capabilities. - -- :material-graph:{ .lg .middle } **Context Graphs** - - --- - - Structured knowledge representation with entity relationships, decision history, and semantic context for sophisticated reasoning. + Scalable, reliable, and tested for real-world applications.
-!!! tip "When to Use" - - **Memory Persistence**: Enabling agents to remember user preferences and history. - - **Complex Retrieval**: When simple vector search fails to capture relationships. - - **Knowledge Graph**: Building a structured world model from unstructured text. - - **Decision Management**: Tracking, analyzing, and learning from decisions. - - **Advanced Analytics**: Understanding influence, patterns, and relationships in decisions. +!!! tip "Perfect For" + - **AI Agents** that need to remember conversations and learn from decisions + - **Chatbots** that become smarter with every interaction + - **Decision Systems** that need to track choices and learn from patterns + - **Knowledge Management** that organizes information intelligently + - **Production Applications** that require reliable, scalable solutions --- -## ๐Ÿ—๏ธ Architecture Components +## ๐Ÿค– AgentContext - Your Agent's Brain -### AgentContext (The Orchestrator) -The high-level facade that unifies all context operations. It routes data to the appropriate subsystems (Memory, Graph, Vector Store, Decision Tracking) and manages the lifecycle of context. +The main interface that makes your agent intelligent. It handles memory, decisions, and knowledge organization automatically. -#### **Constructor Parameters** - -- `vector_store` (Required): The backing vector database instance (e.g., FAISS, Weaviate) -- `knowledge_graph` (Optional): The graph store instance for structured knowledge -- `token_limit` (Default: `2000`): The maximum number of tokens allowed in short-term memory before pruning occurs -- `short_term_limit` (Default: `10`): The maximum number of distinct memory items in short-term memory -- `hybrid_alpha` (Default: `0.5`): The weighting factor for retrieval (`0.0` = Pure Vector, `1.0` = Pure Graph) -- `use_graph_expansion` (Default: `True`): Whether to fetch neighbors of retrieved nodes from the graph -- `enable_decision_tracking` (Default: `False`): Enable advanced decision tracking features -- `enable_advanced_analytics` (Default: `False`): Enable KG algorithms and analytics -- `enable_kg_algorithms` (Default: `False`): Enable knowledge graph algorithm integration -- `enable_vector_store_features` (Default: `False`): Enable advanced vector store features - -#### **Core Methods** - -| Method | Description | -|--------|-------------| -| `store(content, ...)` | Writes information to memory. Handles auto-detection, write-through to vector store, and entity extraction. | -| `retrieve(query, ...)` | Fetches relevant context using hybrid search (Vector + Graph) and reranking. | -| `query_with_reasoning(query, llm_provider, ...)` | **GraphRAG with multi-hop reasoning**: Retrieves context, builds reasoning paths, and generates LLM-based natural language responses grounded in the knowledge graph. | -| `record_decision(category, scenario, reasoning, outcome, confidence, ...)` | Records decisions with full context and metadata for tracking and analysis. | -| `find_precedents(scenario, category, ...)` | Finds similar decisions using advanced search capabilities. | -| `find_precedents_advanced(scenario, similarity_weights, ...)` | Enhanced precedent search with KG features and custom similarity weights. | -| `analyze_decision_influence(decision_id)` | Analyzes decision influence using KG algorithms and centrality measures. | -| `predict_decision_relationships(decision_id)` | Predicts relationships between decisions using link prediction algorithms. | -| `get_context_insights()` | Returns comprehensive system analytics and feature status. | -| `get_causal_chain(decision_id, direction, max_depth)` | Traces decision causality and influence chains. | - -#### **Code Example** +### Quick Start ```python from semantica.context import AgentContext from semantica.vector_store import VectorStore -# 1. Initialize with Advanced Features -vs = VectorStore(backend="faiss", dimension=768) -context = AgentContext( - vector_store=vs, - knowledge_graph=kg, - enable_decision_tracking=True, - enable_advanced_analytics=True, - enable_kg_algorithms=True, - enable_vector_store_features=True +# Create your intelligent agent +agent = AgentContext(vector_store=VectorStore(backend="inmemory", dimension=384)) + +# Your agent can now remember things +memory_id = agent.store("User asked about Python programming") +print(f"Agent remembered: {memory_id}") + +# And find information when needed +results = agent.retrieve("Python tutorials") +print(f"Agent found {len(results)} relevant memories") +``` + +### Easy Decision Learning +```python +# Your agent learns from its decisions +decision_id = agent.record_decision( + category="content_recommendation", + scenario="User wants Python tutorial", + reasoning="User mentioned being a beginner", + outcome="recommended_basics", + confidence=0.85 ) -# 2. Store Memory -context.store( - "User is working on a React project.", - conversation_id="session_1", - user_id="user_123" +# Your agent can now find similar past decisions +similar_decisions = agent.find_precedents("Python tutorial", limit=3) +print(f"Agent found {len(similar_decisions)} similar past decisions") +``` + +### Getting Smarter Over Time +```python +# Enable all learning features +smart_agent = AgentContext( + vector_store=vector_store, + decision_tracking=True, # Learn from decisions + graph_expansion=True, # Find related information + advanced_analytics=True, # Understand patterns + kg_algorithms=True, # Advanced analysis + vector_store_features=True ) -# 3. Record Decision -decision_id = context.record_decision( - category="approval", - scenario="Loan application for first-time homebuyer", - reasoning="Strong credit score (750), stable employment, 20% down payment", - outcome="approved", - confidence=0.94, - decision_maker="loan_officer_001" +# Get insights about your agent's learning +insights = smart_agent.get_context_insights() +print(f"Total decisions learned: {insights.get('total_decisions', 0)}") +print(f"Decision categories: {list(insights.get('categories', {}).keys())}") +``` + +### Core Methods + +| Method | What It Does | When to Use | +|--------|-------------|------------| +| `store(content, ...)` | Remember information | Store conversations, facts, user preferences | +| `retrieve(query, ...)` | Find relevant memories | Search for information when needed | +| `record_decision(category, scenario, reasoning, outcome, confidence, ...)` | Learn from decisions | Track choices and improve over time | +| `find_precedents(scenario, category, ...)` | Find similar decisions | Make consistent choices based on experience | +| `get_context_insights()` | Understand performance | Get analytics about your agent | + +### Advanced Features +```python +# Enable all features for maximum intelligence +agent = AgentContext( + vector_store=vector_store, + knowledge_graph=ContextGraph(advanced_analytics=True), + decision_tracking=True, + graph_expansion=True, + advanced_analytics=True, + kg_algorithms=True, + vector_store_features=True ) -# 4. Retrieve Context -results = context.retrieve("What is the user building?") - -# 5. Find Similar Decisions -precedents = context.find_precedents_advanced( - scenario="High-value credit application", - category="approval", - use_kg_features=True, - similarity_weights={"semantic": 0.5, "structural": 0.3, "category": 0.2} -) - -# 6. Analyze Decision Influence -influence = context.analyze_decision_influence(decision_id) - -# 7. Get Context Insights -insights = context.get_context_insights() - -# 8. Query with Reasoning (GraphRAG) +# Query with multi-hop reasoning (GraphRAG) from semantica.llms import Groq import os -llm_provider = Groq( - model="llama-3.1-8b-instant", - api_key=os.getenv("GROQ_API_KEY") -) - -result = context.query_with_reasoning( - query="What IPs are associated with security alerts?", - llm_provider=llm_provider, - max_results=10, - max_hops=2 -) - -print(f"Response: {result['response']}") -print(f"Reasoning Path: {result['reasoning_path']}") -print(f"Confidence: {result['confidence']:.3f}") -``` - ---- - -### Decision Tracking System - -#### DecisionRecorder (The Decision Engine) -Records decisions with full context, policy applications, and provenance tracking. - -**Key Methods:** -| Method | Description | -|--------|-------------| -| `record_decision(category, scenario, reasoning, outcome, confidence, ...)` | Records decisions with full context and metadata | -| `apply_policy(decision_id, policy_id)` | Applies policies to decisions and checks compliance | -| `create_approval_chain(decision_id, approvers)` | Creates multi-level approval workflows | -| `track_provenance(decision_id, source_info)` | Tracks decision provenance and lineage | - -#### DecisionQuery (The Decision Search Engine) -Advanced decision querying with precedent search, filtering, and hybrid search operations. - -**Key Methods:** -| Method | Description | -|--------|-------------| -| `find_precedents_hybrid(scenario, category, limit)` | Hybrid search with KG and vector store integration | -| `find_precedents_advanced(scenario, similarity_weights, ...)` | Enhanced search with custom similarity weights | -| `analyze_decision_influence(decision_id)` | Analyze decision influence using KG algorithms | -| `predict_decision_relationships(decision_id)` | Predict relationships between decisions | -| `multi_hop_reasoning(decision_id, max_hops)` | Multi-hop reasoning for complex relationships | -| `get_decision_statistics()` | Get comprehensive decision analytics | - -#### CausalChainAnalyzer (The Influence Engine) -Analyzes decision causality, influence chains, and precedent relationships. - -**Key Methods:** -| Method | Description | -|--------|-------------| -| `get_causal_chain(decision_id, direction, max_depth)` | Trace causal chains from decisions | -| `find_influenced_decisions(decision_id)` | Find decisions influenced by a decision | -| `find_influencing_decisions(decision_id)` | Find decisions that influenced a decision | -| `analyze_causal_impact(decision_id, max_depth)` | Analyze causal impact and scope | -| `calculate_influence_score(decision_id)` | Calculate decision influence scores | - -#### PolicyEngine (The Governance Engine) -Policy management with versioning, compliance checking, and impact analysis. - -**Key Methods:** -| Method | Description | -|--------|-------------| -| `create_policy(name, rules, category)` | Create new policies with rules and constraints | -| `check_compliance(decision_id, policy_id)` | Check decision compliance with policies | -| `analyze_impact(policy_id, time_range)` | Analyze policy impact on decisions | -| `get_violations(decision_id)` | Get policy violations for decisions | - -#### **Decision Tracking Example** -```python -from semantica.context import DecisionRecorder, DecisionQuery, CausalChainAnalyzer, PolicyEngine - -# Initialize decision tracking components -recorder = DecisionRecorder(graph_store=kg, vector_store=vs) -query = DecisionQuery(graph_store=kg, vector_store=vs) -analyzer = CausalChainAnalyzer(graph_store=kg) -policy_engine = PolicyEngine(graph_store=kg) - -# Record a decision -decision_id = recorder.record_decision( - category="loan_approval", - scenario="Mortgage application for first-time homebuyer", - reasoning="Strong credit score (750), stable employment, 20% down payment", - outcome="approved", - confidence=0.94, - decision_maker="loan_officer_001" -) - -# Find similar decisions (precedents) -precedents = query.find_precedents_hybrid( - scenario="Mortgage application", - category="loan_approval", - limit=10 -) - -# Analyze decision influence -influence = analyzer.analyze_decision_influence(decision_id) - -# Check policy compliance -compliance = policy_engine.check_compliance(decision_id, "lending_policy_001") - -# Trace causal chain -causal_chain = analyzer.get_causal_chain(decision_id, "downstream", max_depth=3) -``` - ---- - -### Knowledge Graph Algorithm Integration - -#### Supported KG Algorithms -- **Centrality Analysis**: Degree, betweenness, closeness, eigenvector centrality -- **Community Detection**: Modularity-based community identification -- **Node Embeddings**: Node2Vec embeddings for similarity analysis -- **Path Finding**: Shortest path and advanced path algorithms -- **Link Prediction**: Relationship prediction between entities -- **Similarity Calculation**: Multi-type similarity measures - -#### Enhanced ContextGraph Features -```python -from semantica.context import ContextGraph - -# Initialize with KG Algorithms -graph = ContextGraph( - enable_advanced_analytics=True, - enable_centrality_analysis=True, - enable_community_detection=True, - enable_node_embeddings=True -) - -# Add nodes and edges -graph.add_node("Python", type="language", properties={"popularity": "high"}) -graph.add_edge("Python", "Programming", type="related_to") - -# Advanced analytics -centrality = graph.get_node_centrality("Python") -similar = graph.find_similar_nodes("Python", similarity_type="content") -analysis = graph.analyze_graph_with_kg() - -# Decision integration -graph.add_decision(decision_id, decision_data) -precedents = graph.find_precedents("loan_approval") -``` - ---- - -### Vector Store Integration - -#### Hybrid Search Features -- **Semantic + Structural Similarity**: Combined similarity scoring -- **Custom Similarity Weights**: Configurable similarity scoring -- **Advanced Precedent Search**: KG-enhanced similarity search -- **Multi-Embedding Support**: Multiple embedding types -- **Metadata Filtering**: Advanced filtering capabilities - -#### Code Example -```python -# Hybrid search with custom weights -precedents = query.find_precedents_hybrid( - scenario="Loan application", - category="approval", - limit=10, - similarity_weights={ - "semantic": 0.6, - "structural": 0.3, - "category": 0.1 - } -) -``` - ---- - -### AgentMemory (The Storage Engine) -Manages the storage and lifecycle of memory items. It implements the **Hierarchical Memory** pattern. - -#### **Features & Functions** -* **Short-Term Memory (Working Memory)** - * *Structure*: An in-memory list of recent `MemoryItem` objects. - * *Purpose*: Provides immediate context for the ongoing conversation. - * *Pruning Logic*: - * **FIFO**: Removes the oldest items first when limits are reached. - * **Token-Aware**: Calculates token counts to ensure the total buffer size stays under `token_limit`. -* **Long-Term Memory (Episodic Memory)** - * *Structure*: Vector embeddings stored in the `vector_store`. - * *Purpose*: Persists history indefinitely for semantic retrieval. - * *Synchronization*: Automatically syncs with Short-term memory during `store()` operations. -* **Retention Policy** - * *Time-Based*: Can automatically delete memories older than `retention_days`. - * *Count-Based*: Can limit the total number of memories to `max_memories`. - -#### **Key Methods** - -| Method | Description | -|--------|-------------| -| `store_vectors()` | Handles the low-level interaction with concrete Vector Store implementations. | -| `_prune_short_term_memory()` | Internal algorithm that enforces token and count limits. | -| `get_conversation_history()` | Retrieves a chronological list of interactions for a specific session. | - -#### **Code Example** -```python -# Accessing via AgentContext -memory = context.memory - -# Get conversation history -history = memory.get_conversation_history("session_1") -for item in history: - print(f"[{item.timestamp}] {item.content}") - -# Get statistics -stats = memory.get_statistics() -print(f"Stored Memories: {stats['total_memories']}") -``` - ---- - -### ContextGraph (The Knowledge Structure) -Manages the structured relationships between entities. It provides the "World Model" for the agent with advanced KG algorithm integration and serves as the foundation for **Context Graphs** that enable sophisticated reasoning and decision analysis. - -#### **What are Context Graphs?** -**Context Graphs** are structured representations of knowledge that capture: -- **Entity Relationships**: How concepts, people, and decisions are connected -- **Semantic Context**: The meaning and relevance of information within specific domains -- **Decision History**: How past decisions influence current and future choices -- **Knowledge Evolution**: How understanding grows and changes over time - -#### **Key Features of Context Graphs** -* **Dictionary-Based Interface** - * *Design*: Uses standard Python dictionaries for nodes and edges, removing dependencies on complex interface classes. - * *Benefit*: simpler serialization and easier integration with external APIs. -* **Advanced Graph Traversal** - * *Adjacency List*: optimized internal structure for fast neighbor lookups. - * *Multi-Hop Search*: Can traverse `k` hops from a starting node to find indirect connections. - * *Path Finding*: Shortest path and advanced path algorithms for relationship discovery. -* **Rich Node & Edge Types** - * *Typed Schema*: Supports distinct types for nodes (e.g., "Person", "Concept", "Decision") and edges (e.g., "KNOWS", "RELATED_TO", "INFLUENCES"). - * *Metadata Support*: Rich properties and attributes for detailed context capture. -* **Advanced Analytics Integration** - * *KG Algorithm Integration*: Centrality, community detection, embeddings, path finding - * *Decision Integration*: Store and analyze decisions in graph context - * *Similarity Analysis*: Advanced node similarity with multiple measures - * *Influence Analysis**: Track how decisions and entities influence each other - -#### **Context Graph Use Cases** -- **Knowledge Management**: Build and query structured knowledge bases -- **Decision Support**: Trace decision precedents and influence patterns -- **Recommendation Systems**: Find related concepts and entities -- **Social Network Analysis**: Understand relationships and influence -- **Research Networks**: Map collaborations and citation patterns - -#### **Key Methods** - -| Method | Description | -|--------|-------------| -| `add_nodes(nodes)` | Bulk adds nodes using a list of dictionaries. | -| `add_edges(edges)` | Bulk adds edges using a list of dictionaries. | -| `get_neighbors(node_id, hops)` | Returns connected nodes within a specified distance. | -| `query(query_str)` | Performs keyword-based search specifically on graph nodes. | -| `analyze_graph_with_kg()` | Comprehensive graph analysis with KG algorithms. | -| `get_node_centrality(node_id)` | Get centrality measures for specific nodes. | -| `find_similar_nodes(node_id, similarity_type)` | Find similar nodes using advanced similarity. | -| `add_decision(decision_id, decision_data)` | Add decisions with full context integration. | -| `find_precedents(scenario, category)` | Find decision precedents using graph traversal. | -| `trace_influence_paths(entity_id, max_depth)` | Trace how influence propagates through the graph. | -| `get_graph_metrics()` | Get comprehensive graph statistics and health metrics. | - -#### **Code Example** -```python -from semantica.context import ContextGraph - -# Initialize Context Graph with advanced features -graph = ContextGraph( - enable_advanced_analytics=True, - enable_centrality_analysis=True, - enable_community_detection=True, - enable_node_embeddings=True -) - -# Build Context Graph - Add entities and relationships -graph.add_nodes([ - { - "id": "Python", - "type": "Language", - "properties": { - "paradigm": "OO", - "popularity": "high", - "domain": "programming" - } - }, - { - "id": "FastAPI", - "type": "Framework", - "properties": { - "language": "Python", - "use_case": "web_api", - "performance": "high" - } - }, - { - "id": "DataScience", - "type": "Domain", - "properties": { - "description": "Data analysis and machine learning", - "tools": ["Python", "R", "SQL"] - } - } -]) - -# Create relationships in Context Graph -graph.add_edges([ - { - "source_id": "FastAPI", - "target_id": "Python", - "type": "WRITTEN_IN", - "properties": {"strength": 0.9} - }, - { - "source_id": "Python", - "target_id": "DataScience", - "type": "USED_IN", - "properties": {"popularity": 0.95} - }, - { - "source_id": "FastAPI", - "target_id": "DataScience", - "type": "SUPPORTS", - "properties": {"use_case": "api_for_ml"} - } -]) - -# Advanced Context Graph Analytics -centrality = graph.get_node_centrality("Python") -similar = graph.find_similar_nodes("Python", similarity_type="content") -analysis = graph.analyze_graph_with_kg() - -# Decision Integration in Context Graph -graph.add_decision("decision_001", { - "category": "technology_choice", - "scenario": "Framework selection for web API", - "reasoning": "Python ecosystem with FastAPI provides best performance", - "outcome": "selected_fastapi", - "confidence": 0.92 -}) - -# Find decision precedents in Context Graph -precedents = graph.find_precedents("technology_choice") - -# Trace influence through Context Graph -influence_paths = graph.trace_influence_paths("Python", max_depth=3) -``` - ---- - -### Production Graph Store Integration - -For production environments, you can replace the in-memory `ContextGraph` with a persistent `GraphStore` (Neo4j, FalkorDB) by passing it to the `knowledge_graph` parameter. - -```python -from semantica.context import AgentContext -from semantica.graph_store import GraphStore - -# 1. Initialize Persistent Graph Store (Neo4j) -gs = GraphStore( - backend="neo4j", - uri="bolt://localhost:7687", - user="neo4j", - password="password" -) - -# 2. Initialize Agent Context with Persistent Graph and Advanced Features -context = AgentContext( - vector_store=vs, # Your VectorStore instance - knowledge_graph=gs, # Your persistent GraphStore - enable_decision_tracking=True, - enable_advanced_analytics=True, - enable_kg_algorithms=True, - enable_vector_store_features=True, - use_graph_expansion=True -) - -# Now all graph operations (store, retrieve, build_graph) use Neo4j directly. -``` - ---- - -### ContextRetriever (The Search Engine) -The retrieval logic that powers the `retrieve()` command. It implements the **Hybrid Retrieval** algorithm with advanced KG and vector store integration. - -#### **Retrieval Strategy** -1. **Short-Term Check**: Scans the in-memory buffer for immediate, exact-match relevance. -2. **Vector Search**: Queries the `vector_store` for semantically similar long-term memories. -3. **Graph Expansion**: - * Identifies entities in the query. - * Finds those entities in the `ContextGraph`. - * Traverses edges to find related concepts that might not match keywords (e.g., finding "Python" when searching for "Coding"). -4. **Hybrid Scoring**: - * Formula: `Final_Score = (Vector_Score * (1 - ฮฑ)) + (Graph_Score * ฮฑ)` - * Allows tuning the balance between semantic similarity and structural relevance. -5. **KG Algorithm Enhancement**: Uses centrality, community detection, and similarity for advanced ranking. - -#### **Code Example** -```python -# The retriever is automatically used by AgentContext.retrieve() -# But can be accessed directly if needed: - -retriever = context.retriever - -# Perform a manual retrieval with advanced features -results = retriever.retrieve( - query="web frameworks", - max_results=5, - use_kg_features=True, - similarity_weights={"semantic": 0.7, "structural": 0.3} -) -``` - ---- - -### GraphRAG with Multi-Hop Reasoning - -The `query_with_reasoning()` method extends traditional retrieval by performing multi-hop graph traversal and generating natural language responses using LLMs. This enables deeper understanding of relationships and context-aware answer generation. - -#### **How It Works** - -1. **Context Retrieval**: Retrieves relevant context using hybrid search (vector + graph) -2. **Entity Extraction**: Extracts entities from query and retrieved context -3. **Multi-Hop Reasoning**: Traverses knowledge graph up to N hops to find related entities -4. **Reasoning Path Construction**: Builds reasoning chains showing entity relationships -5. **LLM Response Generation**: Generates natural language response grounded in graph context -6. **KG Algorithm Enhancement**: Uses centrality and community detection for enhanced reasoning - -#### **Key Features** - -- **Multi-Hop Reasoning**: Traverses graph up to configurable hops (default: 2) -- **Reasoning Trace**: Shows entity relationship paths used in reasoning -- **Grounded Responses**: LLM generates answers citing specific graph entities -- **Multiple LLM Providers**: Supports Groq, OpenAI, HuggingFace, and LiteLLM (100+ LLMs) -- **Fallback Handling**: Returns context with reasoning path if LLM unavailable -- **KG Algorithm Integration**: Uses centrality and community detection for enhanced reasoning - -#### **Method Signature** - -```python -def query_with_reasoning( - self, - query: str, - llm_provider: Any, # LLM provider from semantica.llms - max_results: int = 10, - max_hops: int = 2, - **kwargs -) -> Dict[str, Any]: -``` - -**Parameters:** -- `query` (str): User query -- `llm_provider`: LLM provider instance (from `semantica.llms`) -- `max_results` (int): Maximum context results to retrieve (default: 10) -- `max_hops` (int): Maximum graph traversal hops (default: 2) -- `**kwargs`: Additional retrieval options - -**Returns:** -- `response` (str): Generated natural language answer -- `reasoning_path` (str): Multi-hop reasoning trace -- `sources` (List[Dict]): Retrieved context items used -- `confidence` (float): Overall confidence score -- `num_sources` (int): Number of sources retrieved -- `num_reasoning_paths` (int): Number of reasoning paths found - -#### **Code Example** - -```python -from semantica.context import AgentContext -from semantica.llms import Groq -from semantica.vector_store import VectorStore -import os - -# Initialize context with advanced features -context = AgentContext( - vector_store=VectorStore(backend="faiss"), - knowledge_graph=kg, - enable_advanced_analytics=True, - enable_kg_algorithms=True -) - -# Configure LLM provider -llm_provider = Groq( - model="llama-3.1-8b-instant", - api_key=os.getenv("GROQ_API_KEY") -) - -# Query with reasoning -result = context.query_with_reasoning( - query="What IPs are associated with security alerts?", - llm_provider=llm_provider, - max_results=10, - max_hops=2 -) - -# Access results -print(f"Response: {result['response']}") -print(f"\nReasoning Path: {result['reasoning_path']}") -print(f"Confidence: {result['confidence']:.3f}") -``` - -#### **Using Different LLM Providers** - -```python -# Groq -from semantica.llms import Groq llm = Groq(model="llama-3.1-8b-instant", api_key=os.getenv("GROQ_API_KEY")) -# OpenAI -from semantica.llms import OpenAI -llm = OpenAI(model="gpt-4", api_key=os.getenv("OPENAI_API_KEY")) - -# LiteLLM (100+ providers) -from semantica.llms import LiteLLM -llm = LiteLLM(model="anthropic/claude-sonnet-4-20250514") - -# Use with query_with_reasoning -result = context.query_with_reasoning( - query="Your question here", +result = agent.query_with_reasoning( + query="What technologies work well together?", llm_provider=llm, - max_hops=3 + max_hops=2 ) -``` -!!! tip "When to Use" - - **Complex Queries**: When simple retrieval doesn't capture relationships - - **Explainable AI**: When you need to show reasoning paths - - **Multi-Hop Questions**: "What IPs are associated with alerts that affect users?" - - **Grounded Responses**: When you need answers citing specific graph entities - - **Decision Analysis**: When analyzing decision influence and relationships +print(f"Response: {result['response']}") +print(f"Reasoning: {result['reasoning_path']}") +``` --- -### EntityLinker (The Connector) -Resolves text mentions to unique entities and assigns URIs. +## ๐Ÿ—๏ธ ContextGraph - Knowledge Organization -#### **Key Methods** +When you need to organize complex information and understand relationships, ContextGraph helps you build intelligent knowledge networks. -| Method | Description | -|--------|-------------| -| `link_entities(source, target, type)` | Creates a link between two entities. | -| `assign_uri(entity_name, type)` | Generates a consistent URI for an entity. | - -#### **Code Example** +### Easy Knowledge Graph Building ```python -from semantica.context import EntityLinker +from semantica.context import ContextGraph -linker = EntityLinker(knowledge_graph=graph) +# Create a knowledge graph +knowledge = ContextGraph(advanced_analytics=True) -# Link two entities -linker.link_entities( - source_entity_id="Python", - target_entity_id="Programming", - link_type="IS_A", - confidence=0.95 +# Add things you want to remember (nodes) +knowledge.add_node("Python", "language", properties={"popularity": "high"}) +knowledge.add_node("Programming", "concept", properties={"type": "skill"}) +knowledge.add_node("FastAPI", "framework", properties={"language": "Python"}) + +# Connect related things (edges) +knowledge.add_edge("Python", "Programming", "related_to") +knowledge.add_edge("Python", "FastAPI", "supports") +knowledge.add_edge("FastAPI", "Programming", "used_for") +``` + +### Easy Decision Management +```python +# Record decisions in your knowledge graph +decision_id = knowledge.add_decision( + category="technology_choice", + scenario="Framework selection for web API", + reasoning="FastAPI provides better performance for Python APIs", + outcome="selected_fastapi", + confidence=0.92, + entities=["Python", "FastAPI", "web_project"] +) + +# Find similar decisions easily +similar = knowledge.find_similar_decisions( + scenario="web framework", + category="technology_choice", + max_results=3 +) + +print(f"Found {len(similar)} similar decisions") +``` + +### Smart Analytics +```python +# Understand decision impact +impact = knowledge.analyze_decision_impact(decision_id) +print(f"This decision influenced {impact.get('total_influenced', 0)} other decisions") + +# Get decision summary +summary = knowledge.get_decision_summary() +print(f"Total decisions: {summary.get('total_decisions', 0)}") +print(f"Categories: {list(summary.get('categories', {}).keys())}") + +# Trace decision chains +chains = knowledge.trace_decision_chain(decision_id) +print(f"Decision chain has {len(chains)} connections") + +# Check if decisions follow rules +compliance = knowledge.check_decision_rules({ + "category": "loan_approval", + "scenario": "Mortgage application", + "reasoning": "Good credit score, stable income", + "outcome": "approved", + "confidence": 0.95 +}) + +if compliance.get("compliant", False): + print("โœ… Decision follows all rules") +else: + print(f"โŒ Rule violations: {compliance.get('violations', [])}") +``` + +### Graph Analytics Made Simple +```python +# Get overview of your knowledge graph +summary = knowledge.get_graph_summary() +print(f"Knowledge graph has {summary.get('nodes', 0)} concepts") +print(f"And {summary.get('edges', 0)} relationships") + +# Find related concepts +related = knowledge.find_related_nodes("Python", how_many=5) +for concept_id, similarity in related: + print(f"Related to {concept_id}: {similarity:.2f}") + +# Understand which concepts are most important +importance = knowledge.get_node_importance("Python") +print(f"Python importance score: {importance.get('degree', 0)}") +``` + +### Core Methods + +| Method | What It Does | When to Use | +|--------|-------------|------------| +| `add_node(node_id, node_type, properties)` | Add concepts to remember | Build knowledge base | +| `add_edge(source, target, relation)` | Connect related concepts | Show relationships | +| `add_decision(category, scenario, reasoning, outcome, confidence, ...)` | Record decisions | Track choices and learn | +| `find_similar_decisions(scenario, category, ...)` | Find similar decisions | Make consistent choices | +| `analyze_decision_impact(decision_id)` | Understand decision influence | See how decisions affect others | +| `get_decision_summary()` | Get decision statistics | Understand decision patterns | +| `trace_decision_chain(decision_id)` | Trace decision connections | Understand decision relationships | +| `check_decision_rules(decision_data)` | Validate decisions | Ensure compliance | +| `get_graph_summary()` | Get graph overview | Understand knowledge structure | +| `find_related_nodes(node_id, how_many)` | Find related concepts | Discover connections | +| `get_node_importance(node_id)` | Measure concept importance | Identify key concepts | + +--- + +## ๐Ÿ”„ Using Both Together - Complete Intelligence + +### Your Smart Agent System +```python +from semantica.context import AgentContext, ContextGraph +from semantica.vector_store import VectorStore + +# Create the components +vector_store = VectorStore(backend="inmemory", dimension=384) +knowledge = ContextGraph(advanced_analytics=True) + +# Create your intelligent agent +agent = AgentContext( + vector_store=vector_store, + knowledge_graph=knowledge, # Add knowledge graph + decision_tracking=True, + graph_expansion=True, + advanced_analytics=True +) + +# Your agent works like this: +# 1. Store information in memory +agent.store("User wants to learn web development with Python") +agent.store("User is a beginner programmer") +agent.store("User prefers hands-on tutorials") + +# 2. Find relevant information +results = agent.retrieve("Python web development tutorials") +print(f"Found {len(results)} relevant memories") + +# 3. Make smart decisions +decision_id = agent.record_decision( + category="content_recommendation", + scenario="Python web development learning path", + reasoning="Beginner needs hands-on Python web tutorial", + outcome="recommended_flask_tutorial", + confidence=0.89 +) + +# 4. Learn and improve over time +insights = agent.get_context_insights() +print(f"Agent insights: {insights}") + +# 5. Access advanced features when needed +graph_summary = agent.graph_builder.get_graph_summary() +node_importance = agent.graph_builder.get_node_importance("Python") +``` + +--- + +## ๐ŸŽฏ Real-World Applications + +### ๐Ÿฆ Banking - Smart Loan Decisions +```python +# Track loan decisions and learn from patterns +bank_agent = AgentContext(vector_store=bank_vector_store, decision_tracking=True) + +# Store customer information +bank_agent.store("Customer has credit score 750, stable employment") +bank_agent.store("Customer is first-time homebuyer") + +# Make loan decision +loan_decision = bank_agent.record_decision( + category="loan_approval", + scenario="First-time homebuyer mortgage", + reasoning="Good credit score, stable income, 20% down payment", + outcome="approved", + confidence=0.94 +) + +# Find similar loan decisions for consistency +similar_loans = bank_agent.find_precedents("homebuyer", category="loan_approval") +print(f"Found {len(similar_loans)} similar loan decisions") +``` + +### ๐Ÿฅ Healthcare - Patient Care Decisions +```python +# Track patient care decisions +health_agent = AgentContext(vector_store=medical_vector_store, decision_tracking=True) + +# Store patient information +health_agent.store("Patient has hypertension, type 2 diabetes") +health_agent.store("Patient allergic to penicillin") + +# Make treatment decision +treatment_decision = health_agent.record_decision( + category="treatment_plan", + scenario="Hypertension with diabetes", + reasoning="ACE inhibitors safe for diabetic patients", + outcome="prescribed_ace_inhibitor", + confidence=0.91 +) + +# Find similar treatment cases +similar_cases = health_agent.find_precedents("hypertension", category="treatment_plan") +``` + +### ๐Ÿ›’ E-commerce - Smart Recommendations +```python +# Track recommendation decisions +ecommerce_graph = ContextGraph() + +# Build user-product knowledge +ecommerce_graph.add_node("user_123", "user", {"segment": "premium"}) +ecommerce_graph.add_node("laptop_xyz", "product", {"category": "electronics"}) +ecommerce_graph.add_edge("user_123", "laptop_xyz", "viewed") + +# Make recommendation decision +rec_decision = ecommerce_graph.add_decision( + category="product_recommendation", + scenario="Laptop recommendation for premium user", + reasoning="User prefers high-performance electronics", + outcome="recommended_gaming_laptop", + confidence=0.87, + entities=["user_123", "laptop_xyz"] +) + +# Find similar recommendations +similar_recs = ecommerce_graph.find_similar_decisions( + scenario="laptop recommendation", + max_results=5 ) ``` --- -## โš™๏ธ Configuration +## โš™๏ธ Configuration Options -### Environment Variables - -```bash -# Global token limit -export CONTEXT_TOKEN_LIMIT=2000 +### Simple Setup (Most Common) +```python +# Just memory and basic learning +agent = AgentContext(vector_store=vector_store) ``` -### YAML Configuration +### Smart Setup (Recommended) +```python +# Memory + decision learning +agent = AgentContext( + vector_store=vector_store, + decision_tracking=True, + graph_expansion=True +) +``` -```yaml -context: - short_term_limit: 10 - retrieval: - hybrid_alpha: 0.5 # 0.0=Vector, 1.0=Graph - max_expansion_hops: 2 +### Complete Setup (Maximum Power) +```python +# Everything enabled +agent = AgentContext( + vector_store=vector_store, + knowledge_graph=ContextGraph(advanced_analytics=True), + decision_tracking=True, + graph_expansion=True, + advanced_analytics=True, + kg_algorithms=True, + vector_store_features=True +) +``` + +### ContextGraph Options +```python +# Basic knowledge graph +graph = ContextGraph() + +# Advanced knowledge graph +graph = ContextGraph( + advanced_analytics=True, # Enable smart algorithms + centrality_analysis=True, # Find important concepts + community_detection=True, # Find groups of related concepts + node_embeddings=True # Understand concept similarity +) ``` --- -## ๐Ÿ“ Data Structures +## ๐Ÿ“Š Data Structures -### MemoryItem -The fundamental unit of storage. +### MemoryItem - The Basic Memory Unit ```python @dataclass class MemoryItem: content: str # The actual text content timestamp: datetime # When it was created - metadata: Dict # Arbitrary tags (user_id, source, etc.) - embedding: List[float] # The vector representation - entities: List[Dict] # Entities found in this content + metadata: Dict # Tags like user_id, conversation_id + embedding: List[float] # Vector representation + entities: List[Dict] # Entities found in content ``` -### Decision -The fundamental unit of decision tracking. +### Decision - The Decision Unit ```python @dataclass class Decision: @@ -775,10 +471,9 @@ class Decision: timestamp: datetime # When decision was made entities: List[str] # Related entities metadata: Dict # Additional decision metadata - embedding: List[float] # Decision embedding for similarity ``` -### Graph Node (Dict Format) +### Graph Node - Knowledge Concept ```python { "id": "node_unique_id", @@ -786,13 +481,12 @@ class Decision: "properties": { "content": "Description of the node", "weight": 1.0, - "centrality": 0.85, - "community": "cluster_1" + "importance": 0.85 } } ``` -### Graph Edge (Dict Format) +### Graph Edge - Knowledge Relationship ```python { "source_id": "origin_node", @@ -808,194 +502,93 @@ class Decision: --- -## ๐Ÿงฉ Advanced Usage +## ๐Ÿš€ Advanced Features -### Context Graphs in Production - -#### Building Domain-Specific Context Graphs - -**Financial Services Context Graph** +### GraphRAG with Multi-Hop Reasoning ```python -from semantica.context import ContextGraph +# Query with reasoning and LLM integration +result = agent.query_with_reasoning( + query="What technologies work well together?", + llm_provider=llm_provider, + max_hops=2, + max_results=10 +) -# Create financial context graph -financial_graph = ContextGraph(enable_advanced_analytics=True) - -# Add financial entities -financial_graph.add_nodes([ - { - "id": "customer_001", - "type": "Customer", - "properties": { - "credit_score": 750, - "risk_profile": "low", - "account_type": "premium" - } - }, - { - "id": "mortgage_product", - "type": "Product", - "properties": { - "category": "loan", - "interest_rate": 3.5, - "max_amount": 500000 - } - }, - { - "id": "loan_officer_001", - "type": "Agent", - "properties": { - "department": "lending", - "experience_years": 5 - } - } -]) - -# Add relationships -financial_graph.add_edges([ - { - "source_id": "customer_001", - "target_id": "mortgage_product", - "type": "ELIGIBLE_FOR", - "properties": {"confidence": 0.92} - }, - { - "source_id": "loan_officer_001", - "target_id": "customer_001", - "type": "SERVES", - "properties": {"relationship_duration": "2_years"} - } -]) - -# Analyze financial context -centrality = financial_graph.get_node_centrality("customer_001") -similar_customers = financial_graph.find_similar_nodes("customer_001") +print(f"Response: {result['response']}") +print(f"Reasoning Path: {result['reasoning_path']}") +print(f"Confidence: {result['confidence']:.3f}") ``` -**Healthcare Context Graph** +### Production Integration ```python -# Create healthcare context graph -healthcare_graph = ContextGraph(enable_advanced_analytics=True) +# Use with persistent graph stores +from semantica.graph_store import GraphStore -# Add medical entities -healthcare_graph.add_nodes([ - { - "id": "patient_001", - "type": "Patient", - "properties": { - "condition": "diabetes_type_2", - "age": 45, - "risk_factors": ["obesity", "hypertension"] - } - }, - { - "id": "metformin", - "type": "Medication", - "properties": { - "class": "biguanide", - "uses": ["diabetes_treatment", "pcos"] - } - }, - { - "id": "dr_smith", - "type": "Physician", - "properties": { - "specialty": "endocrinology", - "hospital": "general_hospital" - } - } -]) +# Neo4j integration +neo4j_store = GraphStore( + backend="neo4j", + uri="bolt://localhost:7687", + user="neo4j", + password="password" +) -# Add medical relationships -healthcare_graph.add_edges([ - { - "source_id": "patient_001", - "target_id": "metformin", - "type": "PRESCRIBED", - "properties": {"dosage": "500mg", "frequency": "twice_daily"} - }, - { - "source_id": "dr_smith", - "target_id": "patient_001", - "type": "TREATS", - "properties": {"since": "2023-01-15"} - } -]) - -# Analyze healthcare context -treatment_patterns = healthcare_graph.analyze_graph_with_kg() -similar_patients = healthcare_graph.find_similar_nodes("patient_001") +# Production agent with persistent storage +production_agent = AgentContext( + vector_store=vector_store, + knowledge_graph=neo4j_store, + decision_tracking=True, + advanced_analytics=True +) ``` -#### Context Graph Analytics and Insights - +### Analytics and Insights ```python -# Get comprehensive graph insights -insights = graph.get_graph_metrics() -print(f"Graph Density: {insights['density']}") -print(f"Average Clustering: {insights['avg_clustering']}") -print(f"Number of Communities: {len(insights['communities'])}") +# Get comprehensive insights +insights = agent.get_context_insights() +print(f"Total decisions: {insights.get('total_decisions', 0)}") +print(f"Decision categories: {list(insights.get('categories', {}).keys())}") +print(f"Most common outcome: {insights.get('most_common_outcome', 'N/A')}") -# Find influential nodes -influential_nodes = [] -for node_id in graph.get_all_nodes(): - centrality = graph.get_node_centrality(node_id) - if centrality['betweenness'] > 0.8: - influential_nodes.append(node_id) - -# Trace decision influence -decision_influence = graph.trace_influence_paths("decision_001", max_depth=3) -for path in decision_influence: - print(f"Influence Path: {' -> '.join(path)}") +# Graph analytics +graph_insights = agent.graph_builder.get_graph_summary() +node_importance = agent.graph_builder.get_node_importance("key_concept") ``` -#### Context Graph Visualization +--- -```python -# Export context graph for visualization -graph_data = graph.export_graph(format="networkx") +## ๐Ÿ“š Need More Help? -# Create visualization (requires matplotlib/networkx) -import matplotlib.pyplot as plt -import networkx as nx +### For Beginners +- Start with **AgentContext** for most applications +- Use basic **store/retrieve** for memory management +- Add **decision tracking** to enable learning +- Enable features gradually as needed -G = nx.node_link_graph(graph_data) -pos = nx.spring_layout(G) +### For Advanced Users +- Add **ContextGraph** for knowledge organization +- Use **analytics** to understand patterns +- Implement **policies** for consistent decisions +- Use **persistence** for state management -# Draw the context graph -plt.figure(figsize=(12, 8)) -nx.draw(G, pos, with_labels=True, node_color='lightblue', - node_size=1000, font_size=8, edge_color='gray') -plt.title("Context Graph Visualization") -plt.show() -``` +### For Production +- Enable **all features** for maximum intelligence +- Use **save/load** for state persistence +- **Monitor performance** with insights and health checks +- **Test thoroughly** before deployment -### Method Registry (Extensibility) -Register custom implementations for graph building, memory management, or retrieval. +### Examples and Tutorials +- Look at the **real-world examples** above for your specific use case +- Check **configuration options** to customize your agent +- Start simple and add power as needed -#### **Code Example** -```python -from semantica.context import registry +--- -def custom_graph_builder(entities, relationships): - # Custom logic to build graph - return "my_graph_structure" +**Happy building intelligent agents!** ๐ŸŽฏ -# Register the new method -registry.register("graph", "custom_builder", custom_graph_builder) -``` +--- -### Configuration Manager -Programmatically manage configuration settings. +## ๐Ÿ“š See Also -#### **Code Example** -```python -from semantica.context.config import context_config - -# Update configuration at runtime -context_config.set("retention_days", 60) - -## See Also - [Vector Store](vector_store.md) - The long-term storage backend - [Graph Store](graph_store.md) - The knowledge graph backend - [KG Algorithms](kg.md) - Knowledge graph algorithms and analytics diff --git a/semantica/context/__init__.py b/semantica/context/__init__.py index c479cfeb..ff50605d 100644 --- a/semantica/context/__init__.py +++ b/semantica/context/__init__.py @@ -46,7 +46,7 @@ Enhanced Analytics: Main Classes: - AgentContext: High-level interface with KG integration - - ContextGraph: In-memory graph store with KG algorithm support + - ContextGraph: In-memory graph store with KG algorithm support and comprehensive decision management - ContextNode/ContextEdge: Graph data structures - AgentMemory: Persistent agent memory with RAG - MemoryItem: Memory item data structure @@ -63,12 +63,13 @@ Decision Tracking Classes: - Policy/Precedent/PolicyException: Decision tracking data structures Example Usage: - >>> from semantica.context import AgentContext + >>> from semantica.context import AgentContext, ContextGraph + >>> # Simple AgentContext with decision tracking >>> context = AgentContext(vector_store=vs, knowledge_graph=kg, - ... enable_decision_tracking=True, - ... enable_advanced_analytics=True, - ... enable_kg_algorithms=True, - ... enable_vector_store_features=True) + ... decision_tracking=True, + ... advanced_analytics=True, + ... kg_algorithms=True, + ... vector_store_features=True) >>> memory_id = context.store("User asked about Python", conversation_id="conv1") >>> results = context.retrieve("Python programming") >>> decision_id = context.record_decision(category="approval", @@ -81,6 +82,21 @@ Example Usage: ... use_kg_features=True) >>> influence = context.analyze_decision_influence(decision_id) >>> insights = context.get_context_insights() + + >>> # Comprehensive ContextGraph with all decision features + >>> graph = ContextGraph(advanced_analytics=True, enable_causality=True) + >>> decision_id = graph.record_decision( + ... category="loan_approval", + ... scenario="First-time homebuyer", + ... reasoning="Good credit score and stable income", + ... outcome="approved", + ... confidence=0.95, + ... entities=["customer_123", "property_456"] + ... ) + >>> precedents = graph.find_precedents("loan_approval", limit=5) + >>> influence = graph.analyze_decision_influence(decision_id) + >>> insights = graph.get_decision_insights() + >>> causality = graph.trace_decision_causality(decision_id) Production Examples: - Banking: Mortgage approvals, credit decisions, risk assessment diff --git a/semantica/context/agent_context.py b/semantica/context/agent_context.py index cfead678..16eb7e10 100644 --- a/semantica/context/agent_context.py +++ b/semantica/context/agent_context.py @@ -46,10 +46,11 @@ Key Methods: Example Usage: >>> from semantica.context import AgentContext >>> context = AgentContext(vector_store=vs, knowledge_graph=kg, - ... enable_decision_tracking=True, - ... enable_advanced_analytics=True, - ... enable_kg_algorithms=True, - ... enable_vector_store_features=True) + ... decision_tracking=True, + ... advanced_analytics=True, + ... kg_algorithms=True, + ... vector_store_features=True, + ... graph_expansion=True) >>> memory_id = context.store("User asked about Python", conversation_id="conv1") >>> results = context.retrieve("Python programming") >>> decision_id = context.record_decision(category="approval", @@ -124,13 +125,13 @@ class AgentContext: knowledge_graph: Optional[Any] = None, retention_days: Optional[int] = 30, max_memories: int = 10000, - use_graph_expansion: bool = True, + graph_expansion: bool = True, max_expansion_hops: int = 2, hybrid_alpha: float = 0.5, - enable_decision_tracking: bool = False, - enable_advanced_analytics: bool = True, - enable_kg_algorithms: bool = True, - enable_vector_store_features: bool = True, + decision_tracking: bool = False, + advanced_analytics: bool = True, + kg_algorithms: bool = True, + vector_store_features: bool = True, **kwargs, ): """ @@ -141,14 +142,14 @@ class AgentContext: knowledge_graph: Knowledge graph instance (optional, enables GraphRAG) retention_days: Days to keep memories (default: 30, None=unlimited) max_memories: Maximum number of memories (default: 10000) - use_graph_expansion: Enable graph expansion for retrieval (default: True) + graph_expansion: Enable graph expansion for retrieval (default: True) max_expansion_hops: Maximum hops for graph expansion (default: 2) hybrid_alpha: Balance between vector (0) and graph (1) retrieval (default: 0.5) - enable_decision_tracking: Enable decision tracking features (default: False) - enable_advanced_analytics: Enable advanced analytics (default: True) - enable_kg_algorithms: Enable KG algorithms integration (default: True) - enable_vector_store_features: Enable vector store features (default: True) + decision_tracking: Enable decision tracking features (default: False) + advanced_analytics: Enable advanced analytics (default: True) + kg_algorithms: Enable KG algorithms integration (default: True) + vector_store_features: Enable vector store features (default: True) **kwargs: Additional options passed to underlying components Raises: @@ -168,11 +169,11 @@ class AgentContext: # Store advanced feature flags self.config = { - "enable_decision_tracking": enable_decision_tracking, - "enable_advanced_analytics": enable_advanced_analytics, - "enable_kg_algorithms": enable_kg_algorithms, - "enable_vector_store_features": enable_vector_store_features, - "use_graph_expansion": use_graph_expansion, + "decision_tracking": decision_tracking, + "advanced_analytics": advanced_analytics, + "kg_algorithms": kg_algorithms, + "vector_store_features": vector_store_features, + "graph_expansion": graph_expansion, "max_expansion_hops": max_expansion_hops, "hybrid_alpha": hybrid_alpha, **kwargs @@ -195,7 +196,7 @@ class AgentContext: "memory_store": self._memory, "knowledge_graph": knowledge_graph, "vector_store": vector_store, - "use_graph_expansion": use_graph_expansion, + "use_graph_expansion": graph_expansion, "max_expansion_hops": max_expansion_hops, "hybrid_alpha": hybrid_alpha, **kwargs, @@ -221,18 +222,18 @@ class AgentContext: self._causal_analyzer = None self._policy_engine = None - if enable_decision_tracking and knowledge_graph: + if decision_tracking and knowledge_graph: if hasattr(knowledge_graph, "execute_query"): self._decision_backend = "graph_store" try: self._decision_recorder = DecisionRecorder(knowledge_graph) self._decision_query = DecisionQuery( graph_store=knowledge_graph, - vector_store=vector_store if enable_vector_store_features else None, - enable_advanced_analytics=enable_advanced_analytics, - enable_centrality_analysis=enable_kg_algorithms, - enable_community_detection=enable_kg_algorithms, - enable_node_embeddings=enable_kg_algorithms + vector_store=vector_store if vector_store_features else None, + advanced_analytics=advanced_analytics, + centrality_analysis=kg_algorithms, + community_detection=kg_algorithms, + node_embeddings=kg_algorithms ) self._causal_analyzer = CausalChainAnalyzer(knowledge_graph) self._policy_engine = PolicyEngine(knowledge_graph) @@ -247,13 +248,38 @@ class AgentContext: self._policy_engine = PolicyEngine(knowledge_graph) else: self._decision_backend = "context_graph" + # Initialize basic decision components for ContextGraph self._policy_engine = PolicyEngine(knowledge_graph) self._causal_analyzer = CausalChainAnalyzer(knowledge_graph) - if enable_vector_store_features and hasattr(self.vector_store, "initialize_decision_pipeline"): + + # Initialize DecisionQuery for ContextGraph + try: + self._decision_query = DecisionQuery( + graph_store=knowledge_graph, + vector_store=vector_store if vector_store_features else None, + advanced_analytics=advanced_analytics, + centrality_analysis=kg_algorithms, + community_detection=kg_algorithms, + node_embeddings=kg_algorithms + ) + self.logger.info("ContextGraph decision tracking initialized successfully") + except Exception as e: + self.logger.warning( + f"Failed to initialize DecisionQuery for ContextGraph ({type(e).__name__})" + ) + # Create a minimal DecisionQuery that delegates to ContextGraph + self._decision_query = type('MinimalDecisionQuery', (), { + 'analyze_decision_influence': lambda self, decision_id, max_depth=3: + knowledge_graph.analyze_decision_influence(decision_id, max_depth) if hasattr(knowledge_graph, 'analyze_decision_influence') else {}, + 'find_precedents': lambda self, query, category=None, limit=10: + knowledge_graph.find_precedents(query, category, limit) if hasattr(knowledge_graph, 'find_precedents') else [], + })() + + if vector_store_features and hasattr(self.vector_store, "initialize_decision_pipeline"): try: self.vector_store.initialize_decision_pipeline( - graph_store=knowledge_graph if enable_kg_algorithms else None, - use_graph_features=enable_kg_algorithms + graph_store=knowledge_graph if kg_algorithms else None, + use_graph_features=kg_algorithms ) except Exception as e: self.logger.warning( @@ -1586,67 +1612,22 @@ class AgentContext: return decision_id - if not hasattr(self.knowledge_graph, "add_decision"): + if not hasattr(self.knowledge_graph, "record_decision"): raise RuntimeError("Decision tracking backend does not support decisions") - self.knowledge_graph.add_decision(decision) - if cross_system_context and hasattr(self.knowledge_graph, "add_node_attribute"): - self.knowledge_graph.add_node_attribute( - decision.decision_id, {"cross_system_context": cross_system_context} - ) - about_edge_failures: List[Dict[str, str]] = [] - for entity_id in entities: - try: - self.knowledge_graph.add_edge(decision.decision_id, entity_id, edge_type="ABOUT") - except Exception as e: - about_edge_failures.append( - {"entity_id": str(entity_id), "error_type": type(e).__name__} - ) - - if about_edge_failures: - failure_types = sorted( - {f.get("error_type", "") for f in about_edge_failures if f.get("error_type")} - ) - self.logger.warning( - f"record_decision ABOUT edge creation failures: {len(about_edge_failures)} " - f"({', '.join(failure_types) if failure_types else 'unknown'})" - ) - if hasattr(self.knowledge_graph, "add_node_attribute"): - self.knowledge_graph.add_node_attribute( - decision.decision_id, {"about_edge_failures": about_edge_failures} - ) - - vector_id = None - vector_store_error_type: Optional[str] = None - if hasattr(self.vector_store, "store_decision"): - try: - vector_id = self.vector_store.store_decision( - scenario=scenario, - reasoning=reasoning, - outcome=outcome, - confidence=confidence, - entities=entities, - category=category, - decision_id=decision.decision_id, - decision_maker=decision.decision_maker, - timestamp=decision.timestamp.isoformat() - ) - except Exception as e: - vector_id = None - vector_store_error_type = type(e).__name__ - self.logger.warning( - f"record_decision vector store write failed ({vector_store_error_type})" - ) - if hasattr(self.knowledge_graph, "add_node_attribute"): - self.knowledge_graph.add_node_attribute( - decision.decision_id, - {"vector_store_error_type": vector_store_error_type}, - ) - - if vector_id and hasattr(self.knowledge_graph, "add_node_attribute"): - self.knowledge_graph.add_node_attribute(decision.decision_id, {"vector_id": vector_id}) - - return decision.decision_id + # Delegate to ContextGraph + decision_id = self.knowledge_graph.record_decision( + category=category, + scenario=scenario, + reasoning=reasoning, + outcome=outcome, + confidence=confidence, + entities=entities, + decision_maker=decision_maker, + metadata={"cross_system_context": cross_system_context} if cross_system_context else None + ) + + return decision_id def find_precedents( self, @@ -1677,6 +1658,38 @@ class AgentContext: if not self._decision_backend: raise RuntimeError("Decision tracking is not enabled") + # Delegate to ContextGraph if available + if self._decision_backend == "context_graph" and hasattr(self.knowledge_graph, "find_precedents"): + try: + precedents = self.knowledge_graph.find_precedents( + scenario=scenario, + category=category, + limit=limit, + use_semantic_search=use_hybrid_search + ) + # Convert to Decision objects if needed + from .decision_models import Decision + decisions = [] + for precedent in precedents: + decision_data = precedent["decision"] + decision = Decision( + decision_id=decision_data["id"], + category=decision_data["category"], + scenario=decision_data["scenario"], + reasoning=decision_data["reasoning"], + outcome=decision_data["outcome"], + confidence=decision_data["confidence"], + timestamp=datetime.fromtimestamp(decision_data["timestamp"]), + decision_maker=decision_data.get("decision_maker"), + entities=decision_data.get("entities", []) + ) + decisions.append(decision) + return decisions + except Exception as e: + self.logger.exception("ContextGraph find_precedents failed") + return [] + + # Fallback to DecisionQuery for graph_store backend if self._decision_backend == "graph_store": if use_hybrid_search: try: @@ -1991,7 +2004,7 @@ class AgentContext: Returns: Comprehensive graph analysis results """ - if not self._graph_builder or not self.config.get("enable_advanced_analytics", True): + if not self._graph_builder or not self.config.get("advanced_analytics", True): return {"error": "Advanced analytics not available"} try: @@ -2112,11 +2125,21 @@ class AgentContext: if not self._decision_query: raise RuntimeError("Decision tracking is not enabled") + # Delegate to ContextGraph if available + if hasattr(self.knowledge_graph, "analyze_decision_influence"): + try: + return self.knowledge_graph.analyze_decision_influence(decision_id, max_depth) + except Exception as e: + self.logger.error(f"ContextGraph analyze_decision_influence failed: {e}") + # Fallback to DecisionQuery + pass + + # Fallback to DecisionQuery try: if hasattr(self._decision_query, 'analyze_decision_influence'): return self._decision_query.analyze_decision_influence(decision_id, max_depth) else: - # Fallback to basic causal chain + # Basic causal chain fallback return { "decision_id": decision_id, "downstream_decisions": self.get_causal_chain(decision_id, "downstream", max_depth), @@ -2160,12 +2183,12 @@ class AgentContext: insights = { "timestamp": datetime.now().isoformat(), "memory_stats": self.stats(), - "decision_stats": self.get_decision_statistics() if self.config.get("enable_decision_tracking") and hasattr(self, 'get_decision_statistics') else {}, + "decision_stats": self.get_decision_statistics() if self.config.get("decision_tracking") and hasattr(self, 'get_decision_statistics') else {}, "graph_analysis": self.analyze_context_graph(), "advanced_features": { - "kg_algorithms_enabled": self.config.get("enable_kg_algorithms", False), - "vector_store_features_enabled": self.config.get("enable_vector_store_features", False), - "decision_tracking_enabled": self.config.get("enable_decision_tracking", False) + "kg_algorithms_enabled": self.config.get("kg_algorithms", False), + "vector_store_features_enabled": self.config.get("vector_store_features", False), + "decision_tracking_enabled": self.config.get("decision_tracking", False) } } diff --git a/semantica/context/context_graph.py b/semantica/context/context_graph.py index a6c455aa..09db0df2 100644 --- a/semantica/context/context_graph.py +++ b/semantica/context/context_graph.py @@ -12,6 +12,14 @@ Core Features: - Export to dictionary format - Decision tracking integration +Comprehensive Decision Management: + - Decision Recording: Store decisions with full context and metadata + - Precedent Search: Find similar decisions using hybrid search algorithms + - Influence Analysis: Analyze decision impact and relationships + - Causal Analysis: Trace decision causality chains + - Policy Enforcement: Built-in policy compliance checking + - Advanced Analytics: Comprehensive decision insights + KG Algorithm Integration: - Centrality Analysis: Degree, betweenness, closeness, eigenvector centrality - Community Detection: Modularity-based community identification @@ -47,23 +55,43 @@ Enhanced Methods: - analyze_graph_with_kg(): Comprehensive graph analysis - get_node_centrality(): Get centrality measures for nodes - find_similar_nodes(): Find similar nodes with advanced similarity - - add_decision(): Add decisions with context integration + - record_decision(): Add decisions with context integration - find_precedents(): Find decision precedents + - analyze_decision_influence(): Analyze decision influence + - get_decision_insights(): Get comprehensive decision analytics + - trace_decision_causality(): Trace decision causality + - enforce_decision_policy(): Enforce decision policies - get_graph_metrics(): Get comprehensive statistics - export_graph(): Export graph in various formats Example Usage: >>> from semantica.context import ContextGraph - >>> graph = ContextGraph(enable_advanced_analytics=True, - ... enable_centrality_analysis=True, - ... enable_community_detection=True, - ... enable_node_embeddings=True) + >>> graph = ContextGraph(advanced_analytics=True, + ... centrality_analysis=True, + ... community_detection=True, + ... node_embeddings=True) + >>> + >>> # Basic graph operations >>> graph.add_node("Python", type="language", properties={"popularity": "high"}) >>> graph.add_node("Programming", type="concept") >>> graph.add_edge("Python", "Programming", type="related_to") >>> centrality = graph.get_node_centrality("Python") >>> similar = graph.find_similar_nodes("Python", similarity_type="content") >>> analysis = graph.analyze_graph_with_kg() + >>> + >>> # Decision management + >>> decision_id = graph.record_decision( + ... category="loan_approval", + ... scenario="First-time homebuyer", + ... reasoning="Good credit score", + ... outcome="approved", + ... confidence=0.95, + ... entities=["customer_123", "property_456"] + ... ) + >>> precedents = graph.find_precedents("loan_approval", limit=5) + >>> influence = graph.analyze_decision_influence(decision_id) + >>> insights = graph.get_decision_insights() + >>> causality = graph.trace_decision_causality(decision_id) Production Use Cases: - Knowledge Management: Build and analyze knowledge graphs @@ -71,6 +99,10 @@ Production Use Cases: - Recommendation Systems: Graph-based recommendations - Social Networks: Analyze connections and influence - Research Networks: Map collaborations and citations + - Financial Services: Loan approvals, fraud detection, risk assessment + - Healthcare: Treatment decisions, policy compliance, clinical pathways + - Legal: Case precedent analysis, decision consistency + - Business: Workflow decisions, policy compliance, audit trails """ from collections import defaultdict, deque @@ -136,9 +168,16 @@ class ContextEdge: class ContextGraph: """ - In-memory implementation of context graph. - - Provides capabilities to build, store, and query a context graph. + Easy-to-Use Context Graph with All Advanced Features. + + This class provides simple methods for: + - Building knowledge graphs + - Recording and analyzing decisions + - Finding precedents and patterns + - Causal analysis and policy enforcement + - Advanced graph analytics + + Perfect for building intelligent AI agents that can learn from decisions! """ def __init__(self, config: Optional[Dict[str, Any]] = None, **kwargs): @@ -151,10 +190,10 @@ class ContextGraph: - extract_entities: Extract entities from content (default: True) - extract_relationships: Extract relationships (default: True) - entity_linker: Entity linker instance - - enable_advanced_analytics: Enable KG algorithms (default: True) - - enable_centrality_analysis: Enable centrality measures (default: True) - - enable_community_detection: Enable community detection (default: True) - - enable_node_embeddings: Enable Node2Vec embeddings (default: True) + - advanced_analytics: Enable KG algorithms (default: True) + - centrality_analysis: Enable centrality measures (default: True) + - community_detection: Enable community detection (default: True) + - node_embeddings: Enable Node2Vec embeddings (default: True) """ self.logger = get_logger("context_graph") self.config = config or {} @@ -186,15 +225,15 @@ class ContextGraph: self.kg_components = {} self._analytics_cache = {} - enable_advanced = self.config.get("enable_advanced_analytics", True) + enable_advanced = self.config.get("advanced_analytics", True) if KG_AVAILABLE and enable_advanced: try: - if self.config.get("enable_centrality_analysis", True): + if self.config.get("centrality_analysis", True): self.kg_components["centrality_calculator"] = CentralityCalculator() - if self.config.get("enable_community_detection", True): + if self.config.get("community_detection", True): self.kg_components["community_detector"] = CommunityDetector() - if self.config.get("enable_node_embeddings", True): + if self.config.get("node_embeddings", True): self.kg_components["node_embedder"] = NodeEmbedder() self.kg_components["path_finder"] = PathFinder() self.kg_components["similarity_calculator"] = SimilarityCalculator() @@ -1146,7 +1185,7 @@ class ContextGraph: except Exception as e: self.logger.error(f"Failed to analyze graph with KG: {e}") - return {"error": str(e)} + return {"error": "Graph analysis failed due to an internal error"} def get_node_centrality(self, node_id: str) -> Dict[str, float]: """ @@ -1183,7 +1222,7 @@ class ContextGraph: except Exception as e: self.logger.error(f"Failed to get node centrality: {e}") - return {"error": str(e)} + return {"error": "Node centrality calculation failed due to an internal error"} def find_similar_nodes( self, node_id: str, similarity_type: str = "content", top_k: int = 10 @@ -1329,6 +1368,834 @@ class ContextGraph: union = words1.union(words2) return len(intersection) / len(union) if union else 0.0 + + # --- Comprehensive Decision Management Features --- + + def record_decision( + self, + category: str, + scenario: str, + reasoning: str, + outcome: str, + confidence: float, + entities: Optional[List[str]] = None, + decision_maker: Optional[str] = None, + metadata: Optional[Dict[str, Any]] = None, + **kwargs + ) -> str: + """ + Record a decision with full context and analytics. + + Args: + category: Decision category (e.g., "loan_approval") + scenario: Decision scenario description + reasoning: Decision reasoning explanation + outcome: Decision outcome + confidence: Confidence score (0.0 to 1.0) + entities: Related entities + decision_maker: Who made the decision + metadata: Additional metadata + **kwargs: Additional decision data + + Returns: + Decision ID for reference + """ + import uuid + from datetime import datetime + + # Input validation + if not isinstance(category, str) or not category.strip(): + raise ValueError("Category must be a non-empty string") + if len(category.strip()) > 100: + raise ValueError("Category must be 100 characters or less") + + if not isinstance(scenario, str) or not scenario.strip(): + raise ValueError("Scenario must be a non-empty string") + if len(scenario.strip()) > 5000: + raise ValueError("Scenario must be 5000 characters or less") + + if not isinstance(reasoning, str) or not reasoning.strip(): + raise ValueError("Reasoning must be a non-empty string") + if len(reasoning.strip()) > 10000: + raise ValueError("Reasoning must be 10000 characters or less") + + if not isinstance(outcome, str) or not outcome.strip(): + raise ValueError("Outcome must be a non-empty string") + if len(outcome.strip()) > 1000: + raise ValueError("Outcome must be 1000 characters or less") + + if not isinstance(confidence, (int, float)): + raise ValueError("Confidence must be a number") + if not (0.0 <= confidence <= 1.0): + raise ValueError("Confidence must be between 0.0 and 1.0") + + if entities is not None: + if not isinstance(entities, list): + raise ValueError("Entities must be a list of strings") + for entity in entities: + if not isinstance(entity, str) or not entity.strip(): + raise ValueError("Each entity must be a non-empty string") + if len(entity.strip()) > 200: + raise ValueError("Each entity must be 200 characters or less") + + if decision_maker is not None: + if not isinstance(decision_maker, str) or not decision_maker.strip(): + raise ValueError("Decision maker must be a non-empty string") + if len(decision_maker.strip()) > 200: + raise ValueError("Decision maker must be 200 characters or less") + + if metadata is not None: + if not isinstance(metadata, dict): + raise ValueError("Metadata must be a dictionary") + for key, value in metadata.items(): + if not isinstance(key, str) or not key.strip(): + raise ValueError("Metadata keys must be non-empty strings") + if len(key.strip()) > 100: + raise ValueError("Metadata keys must be 100 characters or less") + if len(str(value)) > 1000: + raise ValueError("Metadata values must be 1000 characters or less") + + # Validate kwargs + for key, value in kwargs.items(): + if not isinstance(key, str) or not key.strip(): + raise ValueError("Additional field names must be non-empty strings") + if len(key.strip()) > 100: + raise ValueError("Additional field names must be 100 characters or less") + if len(str(value)) > 1000: + raise ValueError("Additional field values must be 1000 characters or less") + + decision_id = str(uuid.uuid4()) + timestamp = datetime.now().timestamp() + + # Sanitize inputs + category = category.strip() + scenario = scenario.strip() + reasoning = reasoning.strip() + outcome = outcome.strip() + confidence = float(confidence) + entities = [entity.strip() for entity in (entities or []) if entity.strip()] + decision_maker = decision_maker.strip() if decision_maker else None + + # Create decision record + decision = { + "id": decision_id, + "category": category, + "scenario": scenario, + "reasoning": reasoning, + "outcome": outcome, + "confidence": confidence, + "entities": entities, + "decision_maker": decision_maker, + "timestamp": timestamp, + "metadata": metadata or {}, + **kwargs + } + + # Store decision in graph + self._add_decision_to_graph(decision) + + # Store in internal decision storage + if not hasattr(self, '_decisions'): + self._decisions = {} + self._decision_index = defaultdict(set) + self._entity_index = defaultdict(set) + self._temporal_index = [] + + self._decisions[decision_id] = decision + self._decision_index[category].add(decision_id) + + for entity in entities or []: + self._entity_index[entity].add(decision_id) + + self._temporal_index.append((decision_id, timestamp)) + self._temporal_index.sort(key=lambda x: x[1], reverse=True) + + self.logger.info(f"Recorded decision {decision_id} in category {category}") + return decision_id + + def find_precedents( + self, + scenario: str, + category: Optional[str] = None, + limit: int = 10, + similarity_threshold: float = 0.5, + use_semantic_search: bool = True, + **filters + ) -> List[Dict[str, Any]]: + """ + Find similar decisions (precedents) using hybrid search. + + Args: + scenario: Scenario to find precedents for + category: Filter by decision category + limit: Maximum number of precedents + similarity_threshold: Minimum similarity score + use_semantic_search: Use vector embeddings for search + **filters: Additional filters + + Returns: + List of similar decisions with similarity scores + """ + if not hasattr(self, '_decisions') or not self._decisions: + return [] + + candidates = set() + + # Get candidates by category + if category: + candidates.update(self._decision_index.get(category, set())) + else: + candidates.update(self._decisions.keys()) + + # Filter by entities if provided + if "entities" in filters: + entity_candidates = set() + for entity in filters["entities"]: + entity_candidates.update(self._entity_index.get(entity, set())) + candidates = candidates.intersection(entity_candidates) + + # Calculate similarities + precedents = [] + for decision_id in candidates: + decision = self._decisions[decision_id] + + # Content similarity + content_sim = self._calculate_decision_content_similarity(scenario, decision) + + # Structural similarity (graph-based) + structural_sim = 0.0 + if self.config.get("advanced_analytics"): + structural_sim = self._calculate_structural_similarity_for_decision(decision_id, scenario) + + # Combined similarity + combined_sim = 0.7 * content_sim + 0.3 * structural_sim + + if combined_sim >= similarity_threshold: + precedents.append({ + "decision": decision, + "similarity": combined_sim, + "content_similarity": content_sim, + "structural_similarity": structural_sim + }) + + # Sort by similarity and limit + precedents.sort(key=lambda x: x["similarity"], reverse=True) + return precedents[:limit] + + def analyze_decision_influence( + self, + decision_id: str, + max_depth: int = 3, + include_indirect: bool = True + ) -> Dict[str, Any]: + """ + Analyze decision influence and impact. + + Args: + decision_id: Decision to analyze + max_depth: Maximum depth for influence analysis + include_indirect: Include indirect influences + + Returns: + Influence analysis results + """ + if not hasattr(self, '_decisions') or decision_id not in self._decisions: + raise ValueError(f"Decision {decision_id} not found") + + decision = self._decisions[decision_id] + + # Direct influence (same entities, category) + direct_influence = set() + for entity in decision["entities"]: + direct_influence.update(self._entity_index.get(entity, set())) + direct_influence.discard(decision_id) + direct_influence.update(self._decision_index.get(decision["category"], set())) + direct_influence.discard(decision_id) + + # Indirect influence (through graph relationships) + indirect_influence = set() + if include_indirect and self.config.get("advanced_analytics"): + indirect_influence = self._find_indirect_decision_influence(decision_id, max_depth) + + # Calculate influence scores + influence_scores = {} + for influenced_id in direct_influence | indirect_influence: + score = self._calculate_decision_influence_score(decision_id, influenced_id) + influence_scores[influenced_id] = score + + # Sort by influence score + sorted_influence = sorted( + influence_scores.items(), + key=lambda x: x[1], + reverse=True + ) + + return { + "decision_id": decision_id, + "direct_influence": list(direct_influence), + "indirect_influence": list(indirect_influence), + "influence_scores": sorted_influence, + "total_influenced": len(influence_scores), + "max_influence_score": max(influence_scores.values()) if influence_scores else 0.0 + } + + def get_decision_insights(self) -> Dict[str, Any]: + """ + Get comprehensive insights about all decisions. + + Returns: + Comprehensive analytics and insights + """ + if not hasattr(self, '_decisions') or not self._decisions: + return {"message": "No decisions recorded yet"} + + # Basic statistics + total_decisions = len(self._decisions) + categories = {} + outcomes = {} + confidence_scores = [] + + for decision in self._decisions.values(): + # Category distribution + categories[decision["category"]] = categories.get(decision["category"], 0) + 1 + + # Outcome distribution + outcomes[decision["outcome"]] = outcomes.get(decision["outcome"], 0) + 1 + + # Confidence scores + confidence_scores.append(decision["confidence"]) + + # Advanced analytics (if available) + advanced_insights = {} + if self.config.get("advanced_analytics"): + advanced_insights = self.analyze_graph_with_kg() + + # Temporal analysis + temporal_insights = self._get_decision_temporal_analysis() + + # Entity analysis + entity_insights = self._get_decision_entity_analysis() + + return { + "total_decisions": total_decisions, + "categories": categories, + "outcomes": outcomes, + "confidence_stats": { + "mean": sum(confidence_scores) / len(confidence_scores), + "min": min(confidence_scores), + "max": max(confidence_scores), + "median": sorted(confidence_scores)[len(confidence_scores) // 2] + }, + "advanced_analytics": advanced_insights, + "temporal_analysis": temporal_insights, + "entity_analysis": entity_insights, + "graph_metrics": self.get_graph_metrics() if hasattr(self, 'get_graph_metrics') else {} + } + + def trace_decision_causality( + self, + decision_id: str, + max_depth: int = 5 + ) -> List[Dict[str, Any]]: + """ + Trace causal chain for a decision. + + Args: + decision_id: Decision to trace + max_depth: Maximum depth for causal analysis + + Returns: + Causal chain as list of decision relationships + """ + if not hasattr(self, '_decisions') or decision_id not in self._decisions: + raise ValueError(f"Decision {decision_id} not found") + + try: + # Use graph traversal to find causal relationships + causal_chain = [] + visited = set() + + def trace_recursive(current_id, depth, path): + if depth >= max_depth or current_id in visited: + return + + visited.add(current_id) + current_decision = self._decisions[current_id] + + # Find potential causes (decisions that influenced this one) + potential_causes = [] + for entity in current_decision["entities"]: + for other_decision_id in self._entity_index.get(entity, set()): + if other_decision_id != current_id: + other_decision = self._decisions[other_decision_id] + if other_decision["timestamp"] < current_decision["timestamp"]: + potential_causes.append(other_decision_id) + + for cause_id in potential_causes: + cause_path = path + [{"from": cause_id, "to": current_id, "type": "influences"}] + causal_chain.append(cause_path) + trace_recursive(cause_id, depth + 1, cause_path) + + trace_recursive(decision_id, 0, []) + return causal_chain + + except Exception as e: + self.logger.error(f"Causal analysis failed: {e}") + return [{"error": "Causal analysis failed due to an internal error"}] + + def enforce_decision_policy( + self, + decision_data: Dict[str, Any], + policy_rules: Optional[Dict[str, Any]] = None + ) -> Dict[str, Any]: + """ + Enforce policies on decision data. + + Args: + decision_data: Decision data to check + policy_rules: Policy rules to enforce + + Returns: + Policy enforcement results + """ + # Simple policy enforcement implementation + violations = [] + warnings = [] + + # Default policy rules + default_rules = { + "min_confidence": 0.7, + "required_outcomes": ["approved", "rejected", "flagged"], + "required_metadata": ["decision_maker"], + "max_reasoning_length": 1000 + } + + rules = policy_rules or default_rules + + # Check confidence + if decision_data.get("confidence", 0) < rules.get("min_confidence", 0.7): + violations.append(f"Confidence too low: {decision_data.get('confidence', 0)}") + + # Check outcome + if decision_data.get("outcome") not in rules.get("required_outcomes", []): + violations.append(f"Invalid outcome: {decision_data.get('outcome')}") + + # Check required metadata + for required_field in rules.get("required_metadata", []): + if not decision_data.get(required_field): + violations.append(f"Missing required field: {required_field}") + + # Check reasoning length + reasoning = decision_data.get("reasoning", "") + if len(reasoning) > rules.get("max_reasoning_length", 1000): + warnings.append(f"Reasoning too long: {len(reasoning)} characters") + + return { + "compliant": len(violations) == 0, + "violations": violations, + "warnings": warnings, + "policy_rules": rules + } + + # --- Private helper methods for decision management --- + + def _add_decision_to_graph(self, decision: Dict[str, Any]) -> None: + """Add decision to context graph.""" + try: + # Add decision node + self.add_node( + decision["id"], + "decision", + category=decision["category"], + outcome=decision["outcome"], + confidence=decision["confidence"], + timestamp=decision["timestamp"], + scenario=decision["scenario"][:100] + "..." if len(decision["scenario"]) > 100 else decision["scenario"], + decision_maker=decision.get("decision_maker", ""), + reasoning=decision["reasoning"][:200] + "..." if len(decision["reasoning"]) > 200 else decision["reasoning"] + ) + + # Add entity nodes and relationships + for entity in decision["entities"]: + # Add entity node if not exists + if not self.find_node(entity): + self.add_node( + entity, + "entity", + name=entity + ) + + # Add relationship + self.add_edge( + decision["id"], + entity, + "involves", + confidence=decision["confidence"] + ) + + # Add category node and relationship + category_id = f"category_{decision['category']}" + if not self.find_node(category_id): + self.add_node( + category_id, + "category", + name=decision["category"] + ) + + self.add_edge( + decision["id"], + category_id, + "belongs_to" + ) + + # Add decision maker node if provided + if decision.get("decision_maker"): + maker_id = f"maker_{decision['decision_maker']}" + if not self.find_node(maker_id): + self.add_node( + maker_id, + "decision_maker", + name=decision["decision_maker"] + ) + + self.add_edge( + decision["id"], + maker_id, + "made_by" + ) + + except Exception as e: + self.logger.exception("Failed to add decision to graph") + + def _calculate_decision_content_similarity(self, scenario: str, decision: Dict[str, Any]) -> float: + """Calculate content similarity between scenario and decision.""" + try: + # Simple word-based similarity + scenario_words = set(scenario.lower().split()) + decision_text = f"{decision['scenario']} {decision['reasoning']} {' '.join(decision['entities'])}" + decision_words = set(decision_text.lower().split()) + + intersection = scenario_words.intersection(decision_words) + union = scenario_words.union(decision_words) + + return len(intersection) / len(union) if union else 0.0 + + except Exception as e: + self.logger.exception("Content similarity calculation failed") + return 0.0 + + def _calculate_structural_similarity_for_decision(self, decision_id: str, scenario: str) -> float: + """Calculate structural similarity using graph algorithms.""" + try: + if not self.config.get("advanced_analytics"): + return 0.0 + + # Use graph similarity algorithms + similar_nodes = self.find_similar_nodes( + decision_id, + similarity_type="structural", + top_k=5 + ) + + if similar_nodes: + # similar_nodes is List[Tuple[str, float]], extract similarity scores + return max(similarity for node_id, similarity in similar_nodes) + + except Exception as e: + self.logger.exception("Structural similarity calculation failed") + + return 0.0 + + def _find_indirect_decision_influence(self, decision_id: str, max_depth: int) -> Set[str]: + """Find indirect influences using graph traversal.""" + try: + influenced = set() + + # Get neighbors in graph + neighbors = self.get_neighbors(decision_id, hops=max_depth) + + for neighbor in neighbors: + if neighbor.get("type") == "decision": + influenced.add(neighbor["id"]) + + return influenced + + except Exception as e: + self.logger.warning(f"Indirect influence analysis failed: {e}") + return set() + + def _calculate_decision_influence_score(self, source_id: str, target_id: str) -> float: + """Calculate influence score between two decisions.""" + try: + if not hasattr(self, '_decisions'): + return 0.0 + + source_decision = self._decisions[source_id] + target_decision = self._decisions[target_id] + + # Base score from shared entities + shared_entities = set(source_decision["entities"]) & set(target_decision["entities"]) + entity_score = len(shared_entities) / max(len(source_decision["entities"]), 1) + + # Category similarity + category_score = 1.0 if source_decision["category"] == target_decision["category"] else 0.0 + + # Temporal proximity (more recent decisions have higher influence) + time_diff = abs(source_decision["timestamp"] - target_decision["timestamp"]) + time_score = max(0.0, 1.0 - time_diff / (30 * 24 * 3600)) # 30 days window + + # Combined score + combined_score = 0.5 * entity_score + 0.3 * category_score + 0.2 * time_score + + return combined_score + + except Exception as e: + self.logger.warning(f"Influence score calculation failed: {e}") + return 0.0 + + def _get_decision_temporal_analysis(self) -> Dict[str, Any]: + """Get temporal analysis of decisions.""" + try: + if not hasattr(self, '_temporal_index') or not self._temporal_index: + return {} + + # Group decisions by time periods + recent_decisions = [did for did, ts in self._temporal_index[:10]] + + return { + "recent_decisions": len(recent_decisions), + "oldest_decision": min(ts for _, ts in self._temporal_index), + "newest_decision": max(ts for _, ts in self._temporal_index), + "time_span": max(ts for _, ts in self._temporal_index) - min(ts for _, ts in self._temporal_index) + } + + except Exception as e: + self.logger.warning(f"Temporal analysis failed: {e}") + return {} + + def _get_decision_entity_analysis(self) -> Dict[str, Any]: + """Get entity analysis from decisions.""" + try: + if not hasattr(self, '_decisions'): + return {} + + entity_counts = {} + for decision in self._decisions.values(): + for entity in decision["entities"]: + entity_counts[entity] = entity_counts.get(entity, 0) + 1 + + # Get top entities + top_entities = sorted(entity_counts.items(), key=lambda x: x[1], reverse=True)[:10] + + return { + "total_entities": len(entity_counts), + "top_entities": top_entities, + "avg_entities_per_decision": sum(len(d["entities"]) for d in self._decisions.values()) / len(self._decisions) + } + + except Exception as e: + self.logger.warning(f"Entity analysis failed: {e}") + return {} + + # --- Easy-to-Use Convenience Methods --- + + def add_decision( + self, + category: str, + scenario: str, + reasoning: str, + outcome: str, + confidence: float = 0.5, + entities: Optional[List[str]] = None, + decision_maker: Optional[str] = "system", + **kwargs + ) -> str: + """ + Easy way to record a decision. + + Args: + category: Decision category (e.g., "loan_approval") + scenario: What was the situation + reasoning: Why was this decision made + outcome: What was decided + confidence: How confident (0.0 to 1.0) + entities: Related entities (people, items, etc.) + decision_maker: Who made the decision + **kwargs: Additional information + + Returns: + Decision ID for reference + """ + return self.record_decision( + category=category, + scenario=scenario, + reasoning=reasoning, + outcome=outcome, + confidence=confidence, + entities=entities, + decision_maker=decision_maker, + metadata=kwargs + ) + + def find_similar_decisions( + self, + scenario: str, + category: Optional[str] = None, + max_results: int = 10, + min_similarity: float = 0.3 + ) -> List[Dict[str, Any]]: + """ + Easy way to find similar past decisions. + + Args: + scenario: What situation are you looking for + category: Filter by decision type + max_results: Maximum results to return + min_similarity: Minimum similarity score + + Returns: + List of similar decisions with similarity scores + """ + return self.find_precedents( + scenario=scenario, + category=category, + limit=max_results, + similarity_threshold=min_similarity + ) + + def analyze_decision_impact( + self, + decision_id: str, + include_indirect: bool = True + ) -> Dict[str, Any]: + """ + Easy way to analyze how a decision impacts others. + + Args: + decision_id: Decision to analyze + include_indirect: Include indirect impacts + + Returns: + Impact analysis results + """ + return self.analyze_decision_influence( + decision_id=decision_id, + max_depth=3, + include_indirect=include_indirect + ) + + def get_decision_summary(self) -> Dict[str, Any]: + """ + Easy way to get a summary of all decisions. + + Returns: + Summary statistics and insights + """ + return self.get_decision_insights() + + def trace_decision_chain( + self, + decision_id: str, + max_steps: int = 5 + ) -> List[Dict[str, Any]]: + """ + Easy way to trace how decisions are connected. + + Args: + decision_id: Starting decision + max_steps: Maximum steps to trace + + Returns: + Decision chain connections + """ + return self.trace_decision_causality( + decision_id=decision_id, + max_depth=max_steps + ) + + def check_decision_rules( + self, + decision_data: Dict[str, Any], + rules: Optional[Dict[str, Any]] = None + ) -> Dict[str, Any]: + """ + Easy way to check if a decision follows the rules. + + Args: + decision_data: Decision to check + rules: Custom rules (uses default if None) + + Returns: + Compliance check results + """ + return self.enforce_decision_policy( + decision_data=decision_data, + policy_rules=rules + ) + + def get_graph_summary(self) -> Dict[str, Any]: + """ + Easy way to get graph statistics. + + Returns: + Graph summary information + """ + if hasattr(self, 'get_graph_metrics'): + return self.get_graph_metrics() + else: + return { + "nodes": len(self.nodes), + "edges": len(self.edges), + "node_types": self._get_node_type_distribution(), + "edge_types": self._get_edge_type_distribution() + } + + def find_related_nodes( + self, + node_id: str, + how_many: int = 10, + similarity_type: str = "content" + ) -> List[Tuple[str, float]]: + """ + Easy way to find nodes similar to a given node. + + Args: + node_id: Reference node + how_many: How many similar nodes to find + similarity_type: Type of similarity ("content", "structural") + + Returns: + List of (node_id, similarity_score) tuples + """ + return self.find_similar_nodes( + node_id=node_id, + similarity_type=similarity_type, + top_k=how_many + ) + + def get_node_importance( + self, + node_id: str + ) -> Dict[str, float]: + """ + Easy way to get how important a node is in the graph. + + Args: + node_id: Node to analyze + + Returns: + Centrality measures (importance scores) + """ + return self.get_node_centrality(node_id) + + def analyze_connections(self) -> Dict[str, Any]: + """ + Easy way to analyze the entire graph structure. + + Returns: + Graph analysis results + """ + return self.analyze_graph_with_kg() # For backward compatibility diff --git a/semantica/context/context_usage.md b/semantica/context/context_usage.md index 38a0f084..77e9d0fe 100644 --- a/semantica/context/context_usage.md +++ b/semantica/context/context_usage.md @@ -1,1247 +1,443 @@ -# Context Module Usage Guide +# Context Module - Usage Guide -This guide demonstrates how to use the Semantica context module for building context graphs, managing agent memory, retrieving context, linking entities, and decision tracking with hybrid search capabilities and advanced KG algorithm integration. +## ๐ŸŽฏ What This Module Does -## Quick Imports +The context module gives your AI agents the ability to **remember**, **learn**, and **make smarter decisions** by organizing information in a way that's both powerful and easy to use. -```python -# Core context classes -from semantica.context import AgentContext, ContextGraph, ContextRetriever, DecisionContext +Think of it as giving your agent a brain that can: +- **Remember conversations** (like human memory) +- **Learn from past decisions** (become smarter over time) +- **Find relevant information** quickly (when it matters most) +- **Understand relationships** between concepts +- **Make consistent decisions** based on experience -# Memory management -from semantica.context import AgentMemory +--- -# Entity linking -from semantica.context import EntityLinker - -# Decision tracking with advanced features -from semantica.context import Decision, Policy, PolicyException, DecisionRecorder, DecisionQuery, CausalChainAnalyzer, PolicyEngine - -# For vector storage (often used with context) -from semantica.vector_store import VectorStore -``` - -## Quick Example - -```python -# Simple context setup -vector_store = VectorStore(backend="inmemory", dimension=384) -context = AgentContext(vector_store=vector_store) - -# Store a memory -memory_id = context.store("User likes Python programming", conversation_id="conv1") - -# Retrieve context -results = context.retrieve("Python programming", max_results=5) -print(f"Found {len(results)} results") -``` - -## Table of Contents - -1. [High-Level Interface (Quick Start)](#high-level-interface-quick-start) -2. [Basic Usage](#basic-usage) -3. [Enhanced AgentContext with Decision Tracking and KG Algorithms](#enhanced-agentcontext-with-decision-tracking-and-kg-algorithms) -4. [Context Graph Construction](#context-graph-construction) -5. [Enhanced ContextGraph with KG Algorithms](#enhanced-contextgraph-with-kg-algorithms) -6. [Agent Memory Management](#agent-memory-management) -7. [Context Retrieval](#context-retrieval) -8. [Entity Linking](#entity-linking) -9. [Decision Tracking](#decision-tracking) -10. [Policy Exception Management](#policy-exception-management) -11. [Hybrid Search for Decisions](#hybrid-search-for-decisions) -12. [Context Graphs with KG Algorithms](#context-graphs-with-kg-algorithms) -13. [Advanced Decision Analytics](#advanced-decision-analytics) -14. [Production Examples](#production-examples) -15. [Explainable AI](#explainable-ai) - -## High-Level Interface (Quick Start) - -The `AgentContext` class provides a simplified, generic interface for common use cases. It integrates vector storage, knowledge graphs, and memory management into a unified system. - -### Simple RAG (Vector Only) +## ๐Ÿš€ Quick Start - 5 Minutes to Your First Smart Agent +### Step 1: Basic Setup ```python from semantica.context import AgentContext from semantica.vector_store import VectorStore -# Initialize vector store -vs = VectorStore(backend="faiss", dimension=768) +# Create your agent with memory +vector_store = VectorStore(backend="inmemory", dimension=384) +agent = AgentContext(vector_store=vector_store) -# Initialize context -context = AgentContext(vector_store=vs) +# Your agent can now remember things +memory_id = agent.store("User asked about Python programming") +print(f"Agent remembered: {memory_id}") -# Store a memory -memory_id = context.store("User likes Python programming", conversation_id="conv1") +# And find information when needed +results = agent.retrieve("Python tutorials") +print(f"Agent found {len(results)} relevant memories") +``` -# Retrieve context -results = context.retrieve("Python programming", max_results=5) +### Step 2: Add Decision Learning +```python +# Your agent learns from its decisions +decision_id = agent.record_decision( + category="content_recommendation", + scenario="User wants Python tutorial", + reasoning="User mentioned being a beginner", + outcome="recommended_basics", + confidence=0.85 +) +# Your agent can now find similar past decisions +similar_decisions = agent.find_precedents("Python tutorial", limit=3) +print(f"Agent found {len(similar_decisions)} similar past decisions") +``` + +### Step 3: Get Insights +```python +# Understand how your agent is performing +insights = agent.get_context_insights() +print(f"Agent has made {insights.get('total_decisions', 0)} decisions") +print(f"Decision categories: {list(insights.get('categories', {}).keys())}") +``` + +**That's it! Your agent now has memory and can learn from decisions.** ๐ŸŽ‰ + +--- + +## ๐Ÿค– AgentContext - Your Agent's Brain + +### Memory Management (Like Human Memory) +```python +# Store different types of memories +agent.store("User likes Python programming", conversation_id="chat_1") +agent.store("User is working on a web project", conversation_id="chat_2") +agent.store("User mentioned being a beginner", conversation_id="chat_3") + +# Find memories when needed +results = agent.retrieve("Python programming", conversation_id="chat_1") for result in results: - print(f"Content: {result['content']}") - print(f"Score: {result['score']:.2f}") + print(f"Memory: {result['content']}") + +# Search across all conversations +all_results = agent.retrieve("beginner") +print(f"Found {len(all_results)} memories about beginners") ``` -### GraphRAG (Vector + Graph) - +### Learning from Decisions ```python -from semantica.context import AgentContext, ContextGraph -from semantica.graph_store import GraphStore - -# Initialize persistent knowledge graph (Recommended for production) -try: - kg = GraphStore(backend="neo4j", uri="bolt://localhost:7687", user="neo4j", password="password") - kg.connect() -except: - print("Neo4j not available, falling back to in-memory graph") - kg = ContextGraph() - -# Initialize context with vector store and knowledge graph -context = AgentContext(vector_store=vs, knowledge_graph=kg) - -# Store documents (auto-builds graph) -documents = [ - "Python is a programming language used for machine learning", - "TensorFlow and PyTorch are popular ML frameworks", - "Machine learning involves training models on data" -] - -stats = context.store( - documents, - extract_entities=True, # Extract entities from documents - extract_relationships=True, # Extract relationships - link_entities=True # Link entities across documents +# Record important decisions +decision_id = agent.record_decision( + category="content_recommendation", + scenario="User wants to learn web development", + reasoning="User is beginner, likes Python", + outcome="recommended_python_basics", + confidence=0.90 ) -print(f"Stored {stats['stored_count']} documents") -# Graph stats are available via the graph object directly or context stats -print(f"Graph nodes: {kg.stats()['node_count']}") - -# Retrieve with graph context (auto-detects GraphRAG) -results = context.retrieve( - "Python machine learning", - use_graph=True, # Explicitly use graph - include_entities=True, # Include related entities - expand_graph=True # Use graph expansion -) - -for result in results: - print(f"Content: {result['content']}") - print(f"Score: {result['score']:.2f}") - print(f"Related entities: {len(result.get('related_entities', []))}") +# Find similar past decisions to make better choices +similar_decisions = agent.find_precedents("web development", limit=5) +for decision in similar_decisions: + print(f"Past decision: {decision.scenario}") + print(f"Result: {decision.outcome}") + print(f"Confidence: {decision.confidence}") + print("---") ``` -### Agent Memory Management (Hierarchical) - -The system uses a hierarchical memory structure with: -1. **Short-Term Memory**: Fast, in-memory buffer with token and item count limits. -2. **Long-Term Memory**: Persistent vector store. - +### Getting Smarter Over Time ```python -context = AgentContext( - vector_store=vs, - retention_days=30, - short_term_limit=10, # Max items in short-term buffer - token_limit=2000 # Max tokens in short-term buffer +# Enable all learning features +smart_agent = AgentContext( + vector_store=vector_store, + decision_tracking=True, # Learn from decisions + graph_expansion=True, # Find related information + advanced_analytics=True, # Understand patterns + kg_algorithms=True, # Advanced analysis + vector_store_features=True ) -# Store multiple memories in a conversation -context.store("Hello, I'm interested in Python", conversation_id="conv1", user_id="user123") -context.store("What can you tell me about machine learning?", conversation_id="conv1", user_id="user123") - -# Get conversation history -history = context.conversation( - "conv1", - reverse=True, # Most recent first - include_metadata=True # Include full metadata -) - -for item in history: - print(f"{item['timestamp']}: {item['content']}") - -# Delete old memories -deleted_count = context.forget(days_old=90) -print(f"Deleted {deleted_count} old memories") +# Get insights about your agent's learning +insights = smart_agent.get_context_insights() +print(f"Total decisions learned: {insights.get('total_decisions', 0)}") +print(f"Decision categories: {list(insights.get('categories', {}).keys())}") +print(f"Most common outcome: {insights.get('most_common_outcome', 'N/A')}") ``` -### Persistence (Save/Load) +--- -You can save the entire state of the agent (Memory, Graph, and Vector Index) to disk and reload it later. +## ๐Ÿ—๏ธ ContextGraph - Knowledge Organization +When you need to organize complex information, ContextGraph helps you build knowledge networks. + +### Build a Simple Knowledge Graph ```python -# Save state -context.save("./my_agent_state") +from semantica.context import ContextGraph -# Load state -new_context = AgentContext(vector_store=VectorStore(), knowledge_graph=ContextGraph()) -new_context.load("./my_agent_state") +# Create a knowledge graph +knowledge = ContextGraph(advanced_analytics=True) + +# Add things you want to remember (nodes) +knowledge.add_node("Python", "language", properties={"popularity": "high"}) +knowledge.add_node("Programming", "concept", properties={"type": "skill"}) +knowledge.add_node("FastAPI", "framework", properties={"language": "Python"}) +knowledge.add_node("Web Development", "field", properties={"complexity": "medium"}) + +# Connect related things (edges) +knowledge.add_edge("Python", "Programming", "related_to") +knowledge.add_edge("Python", "FastAPI", "supports") +knowledge.add_edge("FastAPI", "Web Development", "used_for") +knowledge.add_edge("Programming", "Web Development", "requires") ``` -## Basic Usage +### Easy Decision Management +```python +# Record decisions in your knowledge graph +decision_id = knowledge.add_decision( + category="technology_choice", + scenario="Framework selection for web API", + reasoning="FastAPI provides better performance for Python APIs", + outcome="selected_fastapi", + confidence=0.92, + entities=["Python", "FastAPI", "web_project"] +) -### Initialization with Backends +# Find similar decisions easily +similar = knowledge.find_similar_decisions( + scenario="web framework", + category="technology_choice", + max_results=3 +) -You can configure the `VectorStore` with different backends (`inmemory`, `faiss`, `chroma`, `qdrant`, `weaviate`, `milvus`) and embedding models (including FastEmbed). +print(f"Found {len(similar)} similar decisions") +for decision in similar: + print(f" Similar scenario: {decision.get('scenario', 'N/A')}") + print(f" Outcome: {decision.get('outcome', 'N/A')}") +``` +### Understand Decision Impact +```python +# See how decisions affect other decisions +impact = knowledge.analyze_decision_impact(decision_id) +print(f"This decision influenced {impact.get('total_influenced', 0)} other decisions") + +# Get a summary of all decisions +summary = knowledge.get_decision_summary() +print(f"Total decisions: {summary.get('total_decisions', 0)}") +print(f"Categories: {list(summary.get('categories', {}).keys())}") + +# Trace decision chains (how decisions connect) +chains = knowledge.trace_decision_chain(decision_id) +print(f"Decision chain has {len(chains)} connections") +``` + +### Smart Decision Checking +```python +# Check if decisions follow your rules +compliance = knowledge.check_decision_rules({ + "category": "loan_approval", + "scenario": "Mortgage application", + "reasoning": "Good credit score, stable income", + "outcome": "approved", + "confidence": 0.95 +}) + +if compliance.get("compliant", False): + print("โœ… Decision follows all rules") +else: + print(f"โŒ Rule violations: {compliance.get('violations', [])}") +``` + +### Graph Analytics Made Simple +```python +# Get overview of your knowledge graph +summary = knowledge.get_graph_summary() +print(f"Knowledge graph has {summary.get('nodes', 0)} concepts") +print(f"And {summary.get('edges', 0)} relationships") + +# Find related concepts +related = knowledge.find_related_nodes("Python", how_many=5) +for concept_id, similarity in related: + print(f"Related to {concept_id}: {similarity:.2f}") + +# Understand which concepts are most important +importance = knowledge.get_node_importance("Python") +print(f"Python importance score: {importance.get('degree', 0)}") +``` + +--- + +## ๐Ÿ”„ Using Both Together - The Complete Setup + +### Your Smart Agent System ```python from semantica.context import AgentContext, ContextGraph from semantica.vector_store import VectorStore -# Initialize Vector Store with FastEmbed -vs = VectorStore(backend="inmemory", dimension=384) -if hasattr(vs, "embedder") and vs.embedder: - vs.embedder.set_text_model(method="fastembed", model_name="BAAI/bge-small-en-v1.5") +# Create the components +vector_store = VectorStore(backend="inmemory", dimension=384) +knowledge = ContextGraph(advanced_analytics=True) -# Initialize Context Graph -kg = ContextGraph() +# Create your intelligent agent +agent = AgentContext( + vector_store=vector_store, + knowledge_graph=knowledge, # Add knowledge graph + decision_tracking=True, + graph_expansion=True, + advanced_analytics=True +) -# Initialize Agent Context -context = AgentContext(vector_store=vs, knowledge_graph=kg) +# Your agent works like this: +# 1. Store information in memory +agent.store("User wants to learn web development with Python") +agent.store("User is a beginner programmer") +agent.store("User prefers hands-on tutorials") + +# 2. Find relevant information +results = agent.retrieve("Python web development tutorials") +print(f"Found {len(results)} relevant memories") + +# 3. Make smart decisions +decision_id = agent.record_decision( + category="content_recommendation", + scenario="Python web development learning path", + reasoning="Beginner needs hands-on Python web tutorial", + outcome="recommended_flask_tutorial", + confidence=0.89 +) + +# 4. Learn and improve over time +insights = agent.get_context_insights() +print(f"Agent insights: {insights}") + +# 5. Access advanced features when needed +graph_summary = agent.graph_builder.get_graph_summary() +node_importance = agent.graph_builder.get_node_importance("Python") ``` -### Enhanced AgentContext with Decision Tracking and KG Algorithms +--- -The enhanced `AgentContext` supports advanced decision tracking, KG algorithm integration, and vector store features for production-grade context engineering. +## ๐ŸŽฏ Real-World Examples +### ๐Ÿฆ Banking - Smart Loan Decisions ```python -from semantica.context import AgentContext, ContextGraph -from semantica.vector_store import VectorStore -from semantica.graph_store import GraphStore # For decision tracking +# Track loan decisions and learn from patterns +bank_agent = AgentContext(vector_store=bank_vector_store, decision_tracking=True) -# Initialize Vector Store -vs = VectorStore(backend="inmemory", dimension=768) +# Store customer information +bank_agent.store("Customer has credit score 750, stable employment") +bank_agent.store("Customer is first-time homebuyer") -# Initialize Graph Store (required for decision tracking) -# Note: Decision tracking requires a GraphStore with execute_query() support -gs = GraphStore(backend="neo4j", uri="bolt://localhost:7687") - -# Initialize Context Graph with KG algorithms -kg = ContextGraph( - enable_advanced_analytics=True, - enable_centrality_analysis=True, - enable_community_detection=True, - enable_node_embeddings=True -) - -# Initialize Enhanced Agent Context -context = AgentContext( - vector_store=vs, - knowledge_graph=kg, - enable_decision_tracking=True, # Enable decision lifecycle management - enable_advanced_analytics=True, # Enable KG algorithm integration - enable_kg_algorithms=True, # Enable centrality, community detection - enable_vector_store_features=True # Enable hybrid search capabilities -) - -# Record a decision with full context -decision_id = context.record_decision( - category="mortgage_approval", - scenario="First-time homebuyer application", - reasoning="Strong credit score, stable employment, low debt-to-income ratio", +# Make loan decision +loan_decision = bank_agent.record_decision( + category="loan_approval", + scenario="First-time homebuyer mortgage", + reasoning="Good credit score, stable income, 20% down payment", outcome="approved", - confidence=0.94, - decision_maker="loan_officer_001" + confidence=0.94 ) -# Find similar decisions with KG-enhanced search -precedents = context.find_precedents_advanced( - scenario="Mortgage application", - use_kg_features=True, - similarity_weights={"semantic": 0.5, "structural": 0.3, "category": 0.2} -) - -# Analyze decision influence -influence = context.analyze_decision_influence(decision_id) -print(f"Influence score: {influence.get('influence_score', 0):.3f}") -print(f"Centrality measures: {influence.get('centrality_measures', {})}") - -# Get comprehensive context insights -insights = context.get_context_insights() -print(f"Advanced features: {insights.get('advanced_features', {})}") +# Find similar loan decisions for consistency +similar_loans = bank_agent.find_precedents("homebuyer", category="loan_approval") +print(f"Found {len(similar_loans)} similar loan decisions") ``` -## Context Graph Construction - -The `ContextGraph` class is an in-memory graph store. - -### Building from Entities and Relationships - +### ๐Ÿฅ Healthcare - Patient Care Decisions ```python -from semantica.context import ContextGraph +# Track patient care decisions +health_agent = AgentContext(vector_store=medical_vector_store, decision_tracking=True) -graph = ContextGraph() +# Store patient information +health_agent.store("Patient has hypertension, type 2 diabetes") +health_agent.store("Patient allergic to penicillin") -entities = [ - {"id": "e1", "text": "Python", "type": "PROGRAMMING_LANGUAGE"}, - {"id": "e2", "text": "Machine Learning", "type": "CONCEPT"}, - {"id": "e3", "text": "TensorFlow", "type": "FRAMEWORK"}, -] +# Make treatment decision +treatment_decision = health_agent.record_decision( + category="treatment_plan", + scenario="Hypertension with diabetes", + reasoning="ACE inhibitors safe for diabetic patients", + outcome="prescribed_ace_inhibitor", + confidence=0.91 +) -relationships = [ - {"source_id": "e1", "target_id": "e2", "type": "used_for", "confidence": 0.9}, - {"source_id": "e3", "target_id": "e2", "type": "implements", "confidence": 0.95}, -] - -graph_data = graph.build_from_entities_and_relationships(entities, relationships) - -print(f"Nodes: {graph.stats()['node_count']}") -print(f"Edges: {graph.stats()['edge_count']}") +# Find similar treatment cases +similar_cases = health_agent.find_precedents("hypertension", category="treatment_plan") ``` -### Building from Conversations - +### ๐Ÿ›’ E-commerce - Smart Recommendations ```python -from semantica.context import ContextGraph +# Track recommendation decisions +ecommerce_graph = ContextGraph() -graph = ContextGraph() +# Build user-product knowledge +ecommerce_graph.add_node("user_123", "user", {"segment": "premium"}) +ecommerce_graph.add_node("laptop_xyz", "product", {"category": "electronics"}) +ecommerce_graph.add_edge("user_123", "laptop_xyz", "viewed") -conversations = [ - { - "id": "conv1", - "content": "User asked about Python programming", - "entities": [ - {"id": "e1", "text": "Python", "type": "PROGRAMMING_LANGUAGE"} - ], - "relationships": [] - } -] - -graph_data = graph.build_from_conversations( - conversations, - link_entities=True, - extract_intents=True -) -``` - -### Adding Nodes and Edges Manually - -```python -from semantica.context import ContextGraph - -graph = ContextGraph() - -# Add nodes -graph.add_node("node1", "entity", "Python programming", confidence=0.9) -graph.add_node("node2", "concept", "Machine Learning", confidence=0.95) - -# Add edges -graph.add_edge("node1", "node2", "related_to", weight=0.9) - -# Get neighbors -neighbors = graph.get_neighbors("node1", hops=2) -print(f"Neighbors: {neighbors}") - -# Query graph -results = graph.query("Python") # Keyword search on nodes -``` - -### Graph Statistics and Analysis - -```python -stats = graph.stats() -print(f"Node types: {stats['node_types']}") -print(f"Density: {stats['density']:.4f}") - -# Find specific nodes/edges -entities = graph.find_nodes(node_type="entity") -relations = graph.find_edges(edge_type="related_to") -node = graph.find_node("node1") -``` - -### Enhanced ContextGraph with KG Algorithms - -The enhanced `ContextGraph` supports advanced KG algorithms for centrality analysis, community detection, and node embeddings. - -```python -from semantica.context import ContextGraph - -# Initialize with KG algorithms enabled -graph = ContextGraph( - enable_advanced_analytics=True, - enable_centrality_analysis=True, - enable_community_detection=True, - enable_node_embeddings=True +# Make recommendation decision +rec_decision = ecommerce_graph.add_decision( + category="product_recommendation", + scenario="Laptop recommendation for premium user", + reasoning="User prefers high-performance electronics", + outcome="recommended_gaming_laptop", + confidence=0.87, + entities=["user_123", "laptop_xyz"] ) -# Add nodes and edges -graph.add_node("Python", "Language", {"popularity": "high"}) -graph.add_node("FastAPI", "Framework", {"language": "Python"}) -graph.add_node("Django", "Framework", {"language": "Python"}) -graph.add_edge("FastAPI", "Python", "WRITTEN_IN") -graph.add_edge("Django", "Python", "WRITTEN_IN") - -# Centrality analysis -centrality = graph.get_node_centrality("Python") -print(f"Python centrality: {centrality}") - -# Find similar nodes using embeddings -similar_nodes = graph.find_similar_nodes("Python", similarity_type="content") -print(f"Similar nodes to Python: {[node['id'] for node in similar_nodes]}") - -# Community detection -analysis = graph.analyze_graph_with_kg() -communities = analysis.get('community_analysis', {}) -print(f"Communities found: {communities.get('num_communities', 0)}") - -# Node embeddings -embeddings = graph.get_node_embeddings("Python") -print(f"Python embedding dimension: {len(embeddings) if embeddings else 0}") -``` - -## Agent Memory Management - -The `AgentMemory` class handles short-term and long-term memory with hierarchical storage and token management. - -### Storing and Retrieving - -```python -from semantica.context import AgentMemory - -memory = AgentMemory( - vector_store=vs, - knowledge_graph=kg, - retention_policy="30_days", - max_memory_size=10000, - short_term_limit=20, # 20 items max in short-term - token_limit=4000 # 4000 tokens max in short-term -) - -# Store (automatically updates short-term and long-term) -memory_id = memory.store( - "User asked about Python programming", - metadata={"conversation_id": "conv_123"} -) - -# Store short-term only (fleeting thoughts) -temp_id = memory.store( - "Just checking status...", - skip_vector=True -) - -# Retrieve -results = memory.retrieve( - "Python programming", - max_results=5, - type="conversation" -) - -# Conversation History -history = memory.get_conversation_history("conv_123") -``` - -## Context Retrieval - -The `ContextRetriever` implements hybrid retrieval strategies. - -### Hybrid Retrieval - -```python -from semantica.context import ContextRetriever - -retriever = ContextRetriever( - memory_store=memory, - knowledge_graph=kg, - vector_store=vs, - use_graph_expansion=True, - max_expansion_hops=2, - hybrid_alpha=0.5 # Balance between vector (0.0) and graph (1.0) -) - -results = retriever.retrieve( - "Python programming", +# Find similar recommendations +similar_recs = ecommerce_graph.find_similar_decisions( + scenario="laptop recommendation", max_results=5 ) - -for result in results: - print(f"Content: {result.content}") - print(f"Source: {result.source}") # 'vector', 'graph', or 'memory' ``` -## Entity Linking +--- -The `EntityLinker` helps resolve entities to canonical forms or URIs. +## ๐Ÿ’ก Pro Tips for Success +### ๐ŸŒฑ For Beginners +1. **Start with AgentContext** - It's simpler and handles most needs +2. **Use basic store/retrieve** - Like building human memory +3. **Add decision tracking** - Your agent gets smarter over time +4. **Enable features gradually** - Add complexity as you need it + +### ๐Ÿš€ For Advanced Users +1. **Add ContextGraph** - When you need knowledge relationships +2. **Use analytics** - Understand patterns and get insights +3. **Implement policies** - Ensure consistent decisions +4. **Use persistence** - Save and load agent state + +### ๐Ÿญ For Production +1. **Enable all features** - Maximum intelligence and reliability +2. **Use save/load** - Persist agent state between sessions +3. **Monitor performance** - Use health checks and insights +4. **Test thoroughly** - Verify all functionality works + +--- + +## ๐Ÿ”ง Configuration Options + +### Simple Setup (Most Common) ```python -from semantica.context import EntityLinker - -linker = EntityLinker() -uri = linker.generate_uri("Python Programming Language") -print(uri) # e.g., "python_programming_language" - -# Similarity matching -score = linker._calculate_text_similarity("Python", "Python Language") +# Just memory and basic learning +agent = AgentContext(vector_store=vector_store) ``` -## Decision Tracking - -The `DecisionContext` class provides decision tracking capabilities with hybrid search, explainable AI, and KG algorithm integration. - -### Basic Decision Recording - +### Smart Setup (Recommended) ```python -from semantica.context import DecisionContext -from semantica.vector_store import VectorStore - -# Initialize decision context -vector_store = VectorStore(backend="inmemory", dimension=384) -decision_context = DecisionContext(vector_store=vector_store, graph_store=None) - -# Record a decision -decision_id = decision_context.record_decision( - scenario="Credit limit increase for premium customer", - reasoning="Excellent payment history and high credit score", - outcome="approved", - confidence=0.92, - entities=["customer_123", "premium_segment", "credit_card"], - category="credit_approval", - amount=50000, - risk_level="low" -) - -print(f"Recorded decision: {decision_id}") -``` - -### Batch Decision Processing - -```python -# Process multiple decisions -decisions = [ - { - "scenario": "Credit limit increase request", - "reasoning": "Good payment history", - "outcome": "approved", - "confidence": 0.85, - "entities": ["customer_456"], - "category": "credit_approval" - }, - { - "scenario": "Fraud detection alert", - "reasoning": "Suspicious transaction pattern", - "outcome": "blocked", - "confidence": 0.95, - "entities": ["transaction_789", "customer_456"], - "category": "fraud_detection" - } -] - -decision_ids = [] -for decision in decisions: - decision_id = decision_context.record_decision(**decision) - decision_ids.append(decision_id) - -print(f"Processed {len(decision_ids)} decisions") -``` - -### Decision Context Retrieval - -```python -# Get comprehensive decision context -context_info = decision_context.get_decision_context( - decision_id, - depth=2, - include_entities=True, - include_policies=True -) - -print(f"Decision context: {len(context_info.related_entities)} entities") -print(f"Related relationships: {len(context_info.related_relationships)}") -``` - -### Policy Exception Management - -The enhanced decision tracking system supports policy exceptions with proper audit trails. - -```python -from semantica.context import PolicyException, PolicyEngine -from datetime import datetime - -# Create a policy exception -exception = PolicyException( - exception_id="exc_001", - decision_id="decision_123", - policy_id="lending_policy_v2", - reason="Customer relationship exception - long-term premium client", - approver="branch_manager_001", - approval_timestamp=datetime.now(), - justification="Customer has 10-year history with excellent payment record" -) - -# Convert to dictionary for storage -exception_dict = exception.to_dict() -print(f"Exception recorded: {exception_dict['exception_id']}") - -# Create exception from dictionary (e.g., when loading from database) -recreated_exception = PolicyException.from_dict(exception_dict) -print(f"Recreated exception: {recreated_exception.reason}") - -# Policy engine can record exceptions in GraphStore -policy_engine = PolicyEngine(graph_store) -exception_id = policy_engine.record_exception( - decision_id="decision_123", - policy_id="lending_policy_v2", - reason="Long-term customer relationship exception" -) -print(f"Policy exception recorded: {exception_id}") -``` - -## Hybrid Search for Decisions - -The context retriever supports hybrid search combining semantic and structural embeddings. - -### Finding Similar Decisions - -```python -from semantica.context import ContextRetriever - -# Initialize retriever with decision context -retriever = ContextRetriever( +# Memory + decision learning +agent = AgentContext( vector_store=vector_store, - knowledge_graph=None -) - -# Find similar decisions using hybrid search -precedents = decision_context.find_similar_decisions( - scenario="Credit limit increase for good customer", - limit=5, - use_hybrid_search=True, - semantic_weight=0.7, - structural_weight=0.3 -) - -for precedent in precedents: - print(f"Score: {precedent['score']:.3f}") - print(f"Content: {precedent['content'][:100]}...") - print(f"Entities: {precedent['related_entities']}") -``` - -### Decision Precedent Search - -```python -# Search for decision precedents -precedents = retriever.retrieve_decision_precedents( - query="Credit approval for premium customers", - limit=10, - use_hybrid_search=True, - include_context=True -) - -print(f"Found {len(precedents)} precedents") - -for precedent in precedents: - print(f"Scenario: {precedent['scenario']}") - print(f"Outcome: {precedent['outcome']}") - print(f"Confidence: {precedent['confidence']}") -``` - -### Query Decisions with Context - -```python -# Query decisions with multi-hop context expansion -queried = retriever.query_decisions( - query="High-risk credit decisions", - max_hops=2, - include_context=True, - use_hybrid_search=True, - filters={"category": "credit_approval", "risk_level": "high"} -) - -print(f"Found {len(queried)} high-risk decisions") -``` - -## Explainable AI - -The decision tracking system provides comprehensive explanations with path tracing and confidence scoring. - -### Decision Explanations - -```python -# Generate comprehensive decision explanation -explanation = decision_context.explain_decision( - decision_id, - include_paths=True, - include_confidence=True, - include_weights=True -) - -print(f"Scenario: {explanation['scenario']}") -print(f"Reasoning: {explanation['reasoning']}") -print(f"Outcome: {explanation['outcome']}") -print(f"Confidence: {explanation['confidence']}") - -# Available explanation components -components = [ - "scenario", "reasoning", "outcome", "confidence", - "semantic_weight", "structural_weight", "embedding_info", - "related_entities", "similar_decisions", "path_tracing" -] - -for component in components: - if component in explanation: - print(f"{component}: {explanation[component]}") -``` - -### Path Tracing and Context - -```python -# Get decision with path tracing -explanation = decision_context.explain_decision( - decision_id, - include_paths=True, - max_depth=3 -) - -# Trace decision paths -if "path_tracing" in explanation: - paths = explanation["path_tracing"] - for path in paths: - print(f"Path: {' -> '.join(path['entities'])}") - print(f"Confidence: {path['confidence']}") - print(f"Relationships: {path['relationships']}") -``` - -### Confidence and Weight Analysis - -```python -# Analyze decision confidence and weights -explanation = decision_context.explain_decision( - decision_id, - include_confidence=True, - include_weights=True -) - -print(f"Decision confidence: {explanation['confidence']}") -print(f"Semantic weight: {explanation['semantic_weight']}") -print(f"Structural weight: {explanation['structural_weight']}") - -# Check if structural embedding was used -if "has_structural_embedding" in explanation: - has_structural = explanation["has_structural_embedding"] - print(f"Structural embedding used: {has_structural}") -``` - -### Real-World Examples - -```python -# Banking decision example -banking_decision = decision_context.record_decision( - scenario="Mortgage application approval", - reasoning="Strong credit score (750), stable employment, 20% down payment", - outcome="approved", - confidence=0.94, - entities=["applicant_001", "mortgage_30yr", "property_main"], - category="mortgage_approval", - loan_amount=350000, - credit_score=750 -) - -# Get banking decision explanation -banking_explanation = decision_context.explain_decision(banking_decision) -print(f"Banking decision: {banking_explanation['outcome']}") -print(f"Risk assessment: {banking_explanation['confidence']}") - -# Insurance decision example -insurance_decision = decision_context.record_decision( - scenario="Auto insurance claim approval", - reasoning="Clear liability, reasonable repair costs, no prior claims", - outcome="approved", - confidence=0.96, - entities=["claim_auto_001", "driver_safe", "policy_active"], - category="auto_insurance", - claim_amount=2500 -) - -# Find similar insurance decisions -insurance_precedents = decision_context.find_similar_decisions( - scenario="Auto claim with clear liability", - limit=5, - filters={"category": "auto_insurance"} -) - -print(f"Found {len(insurance_precedents)} similar insurance claims") -``` - -## Context Graphs with KG Algorithms - -The context module now integrates with `semantica.kg` algorithms to provide advanced graph analytics, centrality measures, community detection, and node embeddings for comprehensive context graph analysis. - -### Initializing Context Graph with KG Features - -```python -from semantica.context import ContextGraph -from semantica.graph_store import GraphStore - -# Context graph with KG algorithms -graph = ContextGraph( - enable_advanced_analytics=True, # Enable KG algorithms - enable_centrality_analysis=True, # Enable centrality measures - enable_community_detection=True, # Enable community detection - enable_node_embeddings=True # Enable Node2Vec embeddings -) - -print(f"KG components initialized: {len(graph.kg_components)}") -``` - -### Graph Analytics with KG Algorithms - -```python -# Comprehensive graph analysis -analysis = graph.analyze_graph_with_kg() - -print(f"Graph metrics:") -print(f" - Node count: {analysis['graph_metrics']['node_count']}") -print(f" - Edge count: {analysis['graph_metrics']['edge_count']}") -print(f" - Node types: {analysis['graph_metrics']['node_types']}") - -# Centrality analysis -if 'centrality_analysis' in analysis: - centrality = analysis['centrality_analysis'] - print(f" - Centrality measures available for {len(centrality)} nodes") - -# Community detection -if 'community_analysis' in analysis: - communities = analysis['community_analysis'] - print(f" - Found {communities['num_communities']} communities") - print(f" - Modularity: {communities['modularity']:.3f}") - -# Node embeddings -if 'node_embeddings' in analysis: - embeddings = analysis['node_embeddings'] - print(f" - Generated embeddings for {len(embeddings)} nodes") -``` - -### Node Centrality Analysis - -```python -# Get centrality measures for a specific node -node_id = "python_programming" -centrality_measures = graph.get_node_centrality(node_id) - -print(f"Centrality measures for {node_id}:") -print(f" - Degree centrality: {centrality_measures.get('degree_centrality', 0):.3f}") -print(f" - Betweenness centrality: {centrality_measures.get('betweenness_centrality', 0):.3f}") -print(f" - Closeness centrality: {centrality_measures.get('closeness_centrality', 0):.3f}") -print(f" - Eigenvector centrality: {centrality_measures.get('eigenvector_centrality', 0):.3f}") -``` - -### Finding Similar Nodes with Advanced Similarity - -```python -# Find similar nodes using different similarity measures -similar_nodes = graph.find_similar_nodes( - node_id="python_programming", - similarity_type="content", # "content", "structural", "embedding" - top_k=10 -) - -print(f"Similar nodes to 'python_programming':") -for node_id, similarity_score in similar_nodes: - print(f" - {node_id}: {similarity_score:.3f}") - -# Structural similarity -structural_similar = graph.find_similar_nodes( - node_id="python_programming", - similarity_type="structural", - top_k=5 + decision_tracking=True, + graph_expansion=True ) ``` -### AgentContext with KG Features - +### Complete Setup (Maximum Power) ```python -from semantica.context import AgentContext -from semantica.vector_store import VectorStore -from semantica.graph_store import GraphStore - -# Initialize AgentContext with all KG features -vector_store = VectorStore(backend="inmemory", dimension=384) -knowledge_graph = GraphStore(backend="neo4j", uri="bolt://localhost:7687") - -context = AgentContext( +# Everything enabled +agent = AgentContext( vector_store=vector_store, - knowledge_graph=knowledge_graph, - enable_decision_tracking=True, - enable_advanced_analytics=True, # Enable KG algorithms - enable_kg_algorithms=True, # Enable KG integration - enable_vector_store_features=True # Enable vector store features + knowledge_graph=ContextGraph(advanced_analytics=True), + decision_tracking=True, + graph_expansion=True, + advanced_analytics=True, + kg_algorithms=True, + vector_store_features=True ) - -print("AgentContext initialized with KG algorithms") ``` -## Advanced Decision Analytics - -The decision tracking system provides advanced analytics using KG algorithms for decision influence analysis, relationship prediction, and comprehensive insights. - -### DecisionQuery with KG Integration - +### ContextGraph Options ```python -from semantica.context import DecisionQuery - -# Decision query with KG algorithms -query = DecisionQuery( - graph_store=knowledge_graph, - vector_store=vector_store, - enable_advanced_analytics=True, - enable_centrality_analysis=True, - enable_community_detection=True, - enable_node_embeddings=True -) - -print(f"DecisionQuery with {len(query.kg_components)} KG components") -``` - -### Advanced Precedent Search with Custom Weights - -```python -# Find precedents using advanced search with custom similarity weights -precedents = context.find_precedents_advanced( - scenario="Credit limit increase for premium customer", - category="credit_approval", - limit=10, - use_kg_features=True, - similarity_weights={ - "semantic": 0.4, # Vector similarity - "structural": 0.3, # Graph structure similarity - "text": 0.2, # Text overlap - "category": 0.1 # Category matching - } -) - -print(f"Found {len(precedents)} precedents with advanced search") -for precedent in precedents: - print(f" - Score: {precedent.metadata.get('similarity_score', 0):.3f}") - print(f" - Scenario: {precedent.scenario[:100]}...") -``` - -### Decision Influence Analysis - -```python -# Analyze decision influence using KG algorithms -decision_id = "decision_123" -influence_analysis = context.analyze_decision_influence( - decision_id=decision_id, - max_depth=3 -) - -print(f"Decision influence analysis for {decision_id}:") -print(f" - Influence score: {influence_analysis.get('influence_score', 0):.3f}") - -# Centrality measures -centrality = influence_analysis.get('centrality_measures', {}) -print(f" - Degree centrality: {centrality.get('degree_centrality', 0):.3f}") -print(f" - Betweenness centrality: {centrality.get('betweenness_centrality', 0):.3f}") - -# Community information -community = influence_analysis.get('community_info', {}) -if community: - print(f" - Community ID: {community.get('community_id')}") - print(f" - Community size: {community.get('community_size')}") - -# Related decisions -downstream = influence_analysis.get('downstream_decisions', []) -upstream = influence_analysis.get('upstream_decisions', []) -print(f" - Downstream decisions: {len(downstream)}") -print(f" - Upstream decisions: {len(upstream)}") -``` - -### Decision Relationship Prediction - -```python -# Predict potential relationships for decisions -predictions = context.predict_decision_relationships( - decision_id="decision_123", - top_k=5 -) - -print(f"Predicted relationships for decision_123:") -for prediction in predictions: - print(f" - Target: {prediction.get('target', 'unknown')}") - print(f" - Score: {prediction.get('score', 0):.3f}") - print(f" - Type: {prediction.get('type', 'unknown')}") -``` - -### Context Graph Analysis - -```python -# Analyze the entire context graph -graph_analysis = context.analyze_context_graph() - -print("Context graph analysis:") -if 'error' not in graph_analysis: - metrics = graph_analysis.get('graph_metrics', {}) - print(f" - Nodes: {metrics.get('node_count', 0)}") - print(f" - Edges: {metrics.get('edge_count', 0)}") - - centrality = graph_analysis.get('centrality_analysis', {}) - print(f" - Centrality analysis: {len(centrality)} nodes analyzed") - - communities = graph_analysis.get('community_analysis', {}) - print(f" - Communities: {communities.get('num_communities', 0)}") -else: - print(f" - Error: {graph_analysis['error']}") -``` - -### Entity Similarity and Centrality - -```python -# Find similar entities in the context graph -similar_entities = context.find_similar_entities( - entity_id="python_programming", - similarity_type="content", - top_k=10 -) - -print(f"Similar entities to 'python_programming':") -for entity_id, similarity_score in similar_entities: - print(f" - {entity_id}: {similarity_score:.3f}") - -# Get entity centrality measures -entity_centrality = context.get_entity_centrality("python_programming") -print(f"Entity centrality: {entity_centrality}") -``` - -### Comprehensive Context Insights - -```python -# Get comprehensive insights about the context -insights = context.get_context_insights() - -print("Context insights:") -print(f" - Timestamp: {insights.get('timestamp')}") - -# Memory statistics -memory_stats = insights.get('memory_stats', {}) -print(f" - Total memories: {memory_stats.get('total_items', 0)}") -print(f" - Memory usage: {memory_stats.get('memory_usage', {})}") - -# Decision statistics -decision_stats = insights.get('decision_stats', {}) -if decision_stats: - print(f" - Total decisions: {decision_stats.get('total_decisions', 0)}") - print(f" - Decision categories: {decision_stats.get('categories', [])}") - -# Advanced features status -features = insights.get('advanced_features', {}) -print(f" - KG algorithms enabled: {features.get('kg_algorithms_enabled', False)}") -print(f" - Vector store features enabled: {features.get('vector_store_features_enabled', False)}") -print(f" - Decision tracking enabled: {features.get('decision_tracking_enabled', False)}") -``` - -## Production Examples - -### Banking Decision System with KG Analytics - -```python -# Initialize banking decision system -banking_context = AgentContext( - vector_store=VectorStore(backend="faiss", dimension=768), - knowledge_graph=GraphStore(backend="neo4j", uri="bolt://localhost:7687"), - enable_decision_tracking=True, - enable_advanced_analytics=True, - enable_kg_algorithms=True, - enable_vector_store_features=True -) - -# Record banking decisions with full context -decisions = [ - { - "category": "mortgage_approval", - "scenario": "Mortgage application for first-time homebuyer", - "reasoning": "Strong credit score (750), stable employment, 20% down payment", - "outcome": "approved", - "confidence": 0.94, - "decision_maker": "loan_officer_001", - "amount": 350000, - "credit_score": 750, - "risk_level": "low" - }, - { - "category": "credit_card_approval", - "scenario": "Premium credit card application", - "reasoning": "Excellent credit history, high income, existing relationship", - "outcome": "approved", - "confidence": 0.96, - "decision_maker": "credit_analyst_002", - "credit_limit": 25000, - "credit_score": 820, - "risk_level": "very_low" - } -] - -# Process decisions -decision_ids = [] -for decision_data in decisions: - decision_id = banking_context.record_decision(**decision_data) - decision_ids.append(decision_id) - -# Analyze decision influence -for decision_id in decision_ids: - influence = banking_context.analyze_decision_influence(decision_id) - print(f"Decision {decision_id} influence: {influence.get('influence_score', 0):.3f}") - -# Find similar decisions with KG features -similar_decisions = banking_context.find_precedents_advanced( - scenario="High-value credit application", - category="credit_approval", - use_kg_features=True, - similarity_weights={"semantic": 0.5, "structural": 0.3, "category": 0.2} -) - -print(f"Found {len(similar_decisions)} similar decisions with KG analysis") - -# Get comprehensive insights -insights = banking_context.get_context_insights() -print(f"Banking system insights: {insights.get('memory_stats', {})}") -``` - -### Healthcare Decision Support System - -```python -# Healthcare decision system with advanced analytics -healthcare_context = AgentContext( - vector_store=VectorStore(backend="chroma", dimension=1536), - knowledge_graph=GraphStore(backend="neo4j"), - enable_decision_tracking=True, - enable_advanced_analytics=True, - enable_kg_algorithms=True -) - -# Record medical decisions -medical_decisions = [ - { - "category": "treatment_approval", - "scenario": "Approval for experimental cancer treatment", - "reasoning": "Patient meets criteria, no alternative treatments available", - "outcome": "approved", - "confidence": 0.88, - "decision_maker": "dr_smith", - "patient_id": "patient_123", - "condition": "stage_4_lung_cancer", - "treatment_type": "immunotherapy" - }, - { - "category": "diagnostic_test", - "scenario": "MRI scan authorization", - "reasoning": "Symptoms indicate need for detailed imaging", - "outcome": "approved", - "confidence": 0.92, - "decision_maker": "dr_jones", - "patient_id": "patient_456", - "test_type": "brain_mri", - "urgency": "medium" - } -] - -# Process medical decisions -for decision in medical_decisions: - decision_id = healthcare_context.record_decision(**decision) - - # Analyze decision influence in medical context - influence = healthcare_context.analyze_decision_influence(decision_id) - print(f"Medical decision influence: {influence.get('influence_score', 0):.3f}") - -# Find similar treatment decisions -similar_treatments = healthcare_context.find_precedents_advanced( - scenario="Cancer treatment approval", - category="treatment_approval", - use_kg_features=True -) - -print(f"Found {len(similar_treatments)} similar treatment decisions") - -# Analyze healthcare context graph -graph_analysis = healthcare_context.analyze_context_graph() -if 'error' not in graph_analysis: - print(f"Healthcare graph: {graph_analysis.get('graph_metrics', {})}") -``` - -### E-commerce Personalization System - -```python -# E-commerce system with KG recommendations -ecommerce_context = AgentContext( - vector_store=VectorStore(backend="qdrant", dimension=1024), - knowledge_graph=GraphStore(backend="neo4j"), - enable_decision_tracking=True, - enable_advanced_analytics=True, - enable_kg_algorithms=True -) - -# Record personalization decisions -personalization_decisions = [ - { - "category": "product_recommendation", - "scenario": "Premium product recommendation for VIP customer", - "reasoning": "High purchase history, premium segment, similar preferences", - "outcome": "recommended", - "confidence": 0.91, - "decision_maker": "recommendation_engine", - "customer_id": "vip_customer_001", - "product_category": "luxury_goods", - "price_range": "high" - }, - { - "category": "pricing_decision", - "scenario": "Dynamic pricing adjustment", - "reasoning": "High demand, low inventory, competitor pricing", - "outcome": "price_increased", - "confidence": 0.87, - "decision_maker": "pricing_algorithm", - "product_id": "product_789", - "original_price": 99.99, - "new_price": 119.99 - } -] - -# Process e-commerce decisions -for decision in personalization_decisions: - decision_id = ecommerce_context.record_decision(**decision) - - # Find similar customers using KG features - similar_customers = ecommerce_context.find_similar_entities( - entity_id=decision.get('customer_id', ''), - similarity_type="structural", - top_k=5 - ) - print(f"Similar customers: {len(similar_customers)}") - -# Get comprehensive e-commerce insights -insights = ecommerce_context.get_context_insights() -print(f"E-commerce system status: {insights.get('advanced_features', {})}") -``` - -### Backward Compatibility Examples - -All existing code continues to work without changes: - -```python -# Old API still works perfectly -context = AgentContext(vector_store=vector_store) -query = DecisionQuery(graph_store) +# Basic knowledge graph graph = ContextGraph() -# Store and retrieve as before -memory_id = context.store("User message", conversation_id="conv1") -results = context.retrieve("User query") - -# Decision tracking with old API -if hasattr(context, 'record_decision'): - decision_id = context.record_decision( - category="test", - scenario="Test scenario", - reasoning="Test reasoning", - outcome="approved", - confidence=0.8 - ) +# Advanced knowledge graph +graph = ContextGraph( + advanced_analytics=True, # Enable smart algorithms + centrality_analysis=True, # Find important concepts + community_detection=True, # Find groups of related concepts + node_embeddings=True # Understand concept similarity +) ``` -## Summary +--- -The context module provides: +## ๐ŸŽ‰ You're Ready to Build Smart Agents! -- **Backward Compatibility**: All existing code works unchanged -- **KG Algorithm Integration**: Advanced graph analytics with centrality, community detection, embeddings -- **Vector Store Features**: Hybrid search combining semantic and structural similarity -- **Advanced Decision Analytics**: Influence analysis, relationship prediction, comprehensive insights -- **Production Ready**: Scalable architecture for real-world applications +With these examples, you can now: -Users can now build truly comprehensive context graphs with semantica, leveraging all advanced KG algorithms and vector store features while maintaining complete backward compatibility! +โœ… **Build Smart Agents** - That remember and learn from experience +โœ… **Track Decisions** - Make consistent, improving choices over time +โœ… **Find Information** - Quick and relevant memory retrieval +โœ… **Organize Knowledge** - Build intelligent knowledge graphs +โœ… **Make Better Decisions** - Based on past experience and patterns +โœ… **Build Real Applications** - Banking, healthcare, e-commerce, and more + +**Start simple, add power as needed! Your agents will get smarter with every decision.** ๐Ÿš€ + +--- + +## ๐Ÿ“š Need More Help? + +- **Start with AgentContext** for most applications +- **Add ContextGraph** when you need knowledge organization +- **Look at the real-world examples** for your specific use case +- **Check configuration options** to customize your agent + +Happy building smart agents! ๐ŸŽฏ diff --git a/semantica/context/decision_methods.py b/semantica/context/decision_methods.py index 0eae2d40..b68ac50f 100644 --- a/semantica/context/decision_methods.py +++ b/semantica/context/decision_methods.py @@ -549,7 +549,7 @@ def enhance_agent_context_with_decisions(agent_context: AgentContext) -> None: logger = get_logger(__name__) try: - if not agent_context.config.get("enable_decision_tracking"): + if not agent_context.config.get("decision_tracking"): logger.warning("Decision tracking not enabled in AgentContext") return diff --git a/semantica/context/decision_query.py b/semantica/context/decision_query.py index 1a17b941..9ecf1322 100644 --- a/semantica/context/decision_query.py +++ b/semantica/context/decision_query.py @@ -55,10 +55,10 @@ Search Capabilities: Example Usage: >>> from semantica.context import DecisionQuery >>> query = DecisionQuery(graph_store=kg, vector_store=vs, - ... enable_advanced_analytics=True, - ... enable_centrality_analysis=True, - ... enable_community_detection=True, - ... enable_node_embeddings=True) + ... advanced_analytics=True, + ... centrality_analysis=True, + ... community_detection=True, + ... node_embeddings=True) >>> precedents = query.find_precedents_hybrid("Loan application", ... category="approval", ... limit=10) @@ -111,11 +111,11 @@ class DecisionQuery: graph_store: GraphStore, embedding_generator: Optional[EmbeddingGenerator] = None, vector_store: Optional[Any] = None, - enable_advanced_analytics: bool = True, - enable_node_embeddings: bool = True, - enable_centrality_analysis: bool = True, - enable_community_detection: bool = True, - enable_link_prediction: bool = True + advanced_analytics: bool = True, + node_embeddings: bool = True, + centrality_analysis: bool = True, + community_detection: bool = True, + link_prediction: bool = True ): """ Initialize DecisionQuery with optional advanced features. @@ -124,11 +124,11 @@ class DecisionQuery: graph_store: Graph database instance embedding_generator: Optional embedding generator for semantic search vector_store: Optional vector store for hybrid search - enable_advanced_analytics: Enable advanced graph analytics (requires semantica.kg) - enable_node_embeddings: Enable Node2Vec embeddings (requires semantica.kg) - enable_centrality_analysis: Enable centrality measures (requires semantica.kg) - enable_community_detection: Enable community detection (requires semantica.kg) - enable_link_prediction: Enable link prediction (requires semantica.kg) + advanced_analytics: Enable advanced graph analytics (requires semantica.kg) + node_embeddings: Enable Node2Vec embeddings (requires semantica.kg) + centrality_analysis: Enable centrality measures (requires semantica.kg) + community_detection: Enable community detection (requires semantica.kg) + link_prediction: Enable link prediction (requires semantica.kg) """ self.graph_store = graph_store self.embedding_generator = embedding_generator @@ -139,17 +139,17 @@ class DecisionQuery: self.kg_components = {} self.vector_components = {} - if KG_AVAILABLE and enable_advanced_analytics: + if KG_AVAILABLE and advanced_analytics: try: - if enable_centrality_analysis: + if centrality_analysis: self.kg_components["centrality_calculator"] = CentralityCalculator() - if enable_community_detection: + if community_detection: self.kg_components["community_detector"] = CommunityDetector() - if enable_node_embeddings: + if node_embeddings: self.kg_components["node_embedder"] = NodeEmbedder() self.kg_components["path_finder"] = PathFinder() self.kg_components["similarity_calculator"] = SimilarityCalculator() - if enable_link_prediction: + if link_prediction: self.kg_components["link_predictor"] = LinkPredictor() self.logger.info("Advanced KG components initialized successfully") diff --git a/semantica/context/decision_recorder.py b/semantica/context/decision_recorder.py index 63b32381..19093b86 100644 --- a/semantica/context/decision_recorder.py +++ b/semantica/context/decision_recorder.py @@ -149,7 +149,7 @@ class DecisionRecorder: return decision.decision_id except Exception as e: - self.logger.error(f"Failed to record decision: {e}") + self.logger.exception("Failed to record decision") raise def link_entities(self, decision_id: str, entities: List[str]) -> None: @@ -176,7 +176,7 @@ class DecisionRecorder: self.logger.info(f"Linked decision {decision_id} to {len(entities)} entities") except Exception as e: - self.logger.error(f"Failed to link entities: {e}") + self.logger.exception("Failed to link entities") raise def apply_policies(self, decision_id: str, policy_ids: List[str]) -> None: @@ -204,7 +204,7 @@ class DecisionRecorder: self.logger.info(f"Applied {len(policy_ids)} policies to decision {decision_id}") except Exception as e: - self.logger.error(f"Failed to apply policies: {e}") + self.logger.exception("Failed to apply policies") raise def record_exception( @@ -262,7 +262,7 @@ class DecisionRecorder: return exception.exception_id except Exception as e: - self.logger.error(f"Failed to record exception: {e}") + self.logger.exception("Failed to record exception") raise def capture_cross_system_context( @@ -302,7 +302,7 @@ class DecisionRecorder: self.logger.info(f"Captured cross-system context for decision {decision_id}") except Exception as e: - self.logger.error(f"Failed to capture cross-system context: {e}") + self.logger.exception("Failed to capture cross-system context") raise def record_approval_chain( @@ -352,7 +352,7 @@ class DecisionRecorder: self.logger.info(f"Recorded approval chain with {len(approvers)} approvers") except Exception as e: - self.logger.error(f"Failed to record approval chain: {e}") + self.logger.exception("Failed to record approval chain") raise def link_precedents( @@ -389,7 +389,7 @@ class DecisionRecorder: self.logger.info(f"Linked {len(precedent_ids)} precedents to decision {decision_id}") except Exception as e: - self.logger.error(f"Failed to link precedents: {e}") + self.logger.exception("Failed to link precedents") raise def _store_decision_node(self, decision: Decision) -> None: @@ -502,4 +502,4 @@ class DecisionRecorder: ) except Exception as e: - self.logger.warning(f"Failed to track provenance: {e}") + self.logger.exception("Failed to track provenance") diff --git a/semantica/context/policy_engine.py b/semantica/context/policy_engine.py index 9cefaad6..a69830c9 100644 --- a/semantica/context/policy_engine.py +++ b/semantica/context/policy_engine.py @@ -155,7 +155,7 @@ class PolicyEngine: self.logger.info(f"Added policy: {policy.policy_id} version {policy.version}") return policy.policy_id except Exception as e: - self.logger.error(f"Failed to add policy: {e}") + self.logger.exception("Failed to add policy") raise def update_policy( @@ -232,7 +232,7 @@ class PolicyEngine: return new_version except Exception as e: - self.logger.error(f"Failed to update policy: {e}") + self.logger.exception("Failed to update policy") raise def get_applicable_policies( @@ -309,7 +309,7 @@ class PolicyEngine: return policies except Exception as e: - self.logger.error(f"Failed to get applicable policies: {e}") + self.logger.exception("Failed to get applicable policies") raise def check_compliance(self, decision: Decision, policy_id: str) -> bool: @@ -348,7 +348,7 @@ class PolicyEngine: return True except Exception as e: - self.logger.error(f"Failed to check compliance: {e}") + self.logger.exception("Failed to check compliance") return False def record_policy_application( @@ -394,7 +394,7 @@ class PolicyEngine: ) self.logger.info(f"Recorded policy application: {policy_id} v{version} to decision {decision_id}") except Exception as e: - self.logger.error(f"Failed to record policy application: {e}") + self.logger.exception("Failed to record policy application") raise def record_exception( @@ -472,7 +472,7 @@ class PolicyEngine: self.logger.info(f"Recorded policy exception: {exception_id}") return exception_id except Exception as e: - self.logger.error(f"Failed to record exception: {e}") + self.logger.exception("Failed to record exception") raise def get_policy_history(self, policy_id: str) -> List[Policy]: @@ -527,7 +527,7 @@ class PolicyEngine: return versions except Exception as e: - self.logger.error(f"Failed to get policy history: {e}") + self.logger.exception("Failed to get policy history") raise def get_affected_decisions( @@ -578,7 +578,7 @@ class PolicyEngine: return decision_ids except Exception as e: - self.logger.error(f"Failed to get affected decisions: {e}") + self.logger.exception("Failed to get affected decisions") raise def analyze_policy_impact( @@ -679,7 +679,7 @@ class PolicyEngine: return impact_analysis except Exception as e: - self.logger.error(f"Failed to analyze policy impact: {e}") + self.logger.exception("Failed to analyze policy impact") raise def get_policy(self, policy_id: str, version: Optional[str] = None) -> Optional[Policy]: @@ -765,7 +765,7 @@ class PolicyEngine: "metadata": data.get("metadata", {}) }) except Exception as e: - self.logger.error(f"Failed to get policy: {e}") + self.logger.exception("Failed to get policy") return None def _generate_next_version(self, current_version: str) -> str: diff --git a/tests/context/test_agent_context_decisions.py b/tests/context/test_agent_context_decisions.py index 9d275706..4a817451 100644 --- a/tests/context/test_agent_context_decisions.py +++ b/tests/context/test_agent_context_decisions.py @@ -38,7 +38,7 @@ class TestAgentContextDecisions: return AgentContext( vector_store=mock_vector_store, knowledge_graph=mock_knowledge_graph, - enable_decision_tracking=True + decision_tracking=True ) @pytest.fixture @@ -47,7 +47,7 @@ class TestAgentContextDecisions: return AgentContext( vector_store=mock_vector_store, knowledge_graph=mock_knowledge_graph, - enable_decision_tracking=False + decision_tracking=False ) def test_agent_context_initialization_with_decisions(self, mock_vector_store, mock_knowledge_graph): @@ -55,10 +55,10 @@ class TestAgentContextDecisions: context = AgentContext( vector_store=mock_vector_store, knowledge_graph=mock_knowledge_graph, - enable_decision_tracking=True + decision_tracking=True ) - assert context.config["enable_decision_tracking"] is True + assert context.config["decision_tracking"] is True assert context._decision_recorder is not None assert context._decision_query is not None assert context._causal_analyzer is not None @@ -69,10 +69,10 @@ class TestAgentContextDecisions: context = AgentContext( vector_store=mock_vector_store, knowledge_graph=mock_knowledge_graph, - enable_decision_tracking=False + decision_tracking=False ) - assert context.config["enable_decision_tracking"] is False + assert context.config["decision_tracking"] is False assert context._decision_recorder is None assert context._decision_query is None assert context._causal_analyzer is None @@ -255,7 +255,7 @@ class TestAgentContextDecisions: knowledge_graph=mock_knowledge_graph ) - assert context.config["enable_decision_tracking"] is False + assert context.config["decision_tracking"] is False assert context._decision_recorder is None def test_error_handling(self, agent_context_with_decisions): @@ -279,11 +279,11 @@ class TestAgentContextDecisions: context = AgentContext( vector_store=mock_vector_store, knowledge_graph=None, - enable_decision_tracking=True + decision_tracking=True ) # Should initialize but warn about missing knowledge graph - assert context.config["enable_decision_tracking"] is True + assert context.config["decision_tracking"] is True def test_error_handling(self, agent_context_with_decisions): """Test error handling in decision tracking.""" diff --git a/tests/context/test_agent_context_smoke.py b/tests/context/test_agent_context_smoke.py index d019ef20..51b03250 100644 --- a/tests/context/test_agent_context_smoke.py +++ b/tests/context/test_agent_context_smoke.py @@ -11,9 +11,9 @@ def test_agent_context_minimal_decisions_and_chain(): ctx = AgentContext( vector_store=vs, knowledge_graph=graph, - enable_decision_tracking=True, - enable_kg_algorithms=False, - enable_vector_store_features=False, + decision_tracking=True, + kg_algorithms=False, + vector_store_features=False, ) d1 = ctx.record_decision( category="credit_approval", @@ -45,9 +45,9 @@ def test_agent_context_policy_engine_with_graph_backend(): ctx = AgentContext( vector_store=vs, knowledge_graph=graph, - enable_decision_tracking=True, - enable_kg_algorithms=False, - enable_vector_store_features=False, + decision_tracking=True, + kg_algorithms=False, + vector_store_features=False, ) pe = ctx.get_policy_engine() pol = Policy( diff --git a/tests/context/test_banking_context_graphs_e2e.py b/tests/context/test_banking_context_graphs_e2e.py index 84f81af1..097a9beb 100644 --- a/tests/context/test_banking_context_graphs_e2e.py +++ b/tests/context/test_banking_context_graphs_e2e.py @@ -52,10 +52,10 @@ class TestBankingDecisionSystem: return AgentContext( vector_store=mock_vector_store, knowledge_graph=mock_knowledge_graph, - enable_decision_tracking=True, - enable_advanced_analytics=True, - enable_kg_algorithms=True, - enable_vector_store_features=True + decision_tracking=True, + advanced_analytics=True, + kg_algorithms=True, + vector_store_features=True ) def test_banking_decision_lifecycle(self, banking_context): @@ -216,10 +216,10 @@ class TestBankingDecisionSystem: enhanced_query = DecisionQuery( graph_store=mock_knowledge_graph, vector_store=mock_vector_store, - enable_advanced_analytics=True, - enable_centrality_analysis=True, - enable_community_detection=True, - enable_node_embeddings=True + advanced_analytics=True, + centrality_analysis=True, + community_detection=True, + node_embeddings=True ) print(f"[OK] Enhanced DecisionQuery with {len(enhanced_query.kg_components)} KG components") @@ -240,10 +240,10 @@ class TestBankingDecisionSystem: # Test enhanced ContextGraph enhanced_graph = ContextGraph( - enable_advanced_analytics=True, - enable_centrality_analysis=True, - enable_community_detection=True, - enable_node_embeddings=True + advanced_analytics=True, + centrality_analysis=True, + community_detection=True, + node_embeddings=True ) print(f"[OK] Enhanced ContextGraph with {len(enhanced_graph.kg_components)} KG components") diff --git a/tests/context/test_context_graphs_examples.py b/tests/context/test_context_graphs_examples.py index 37fc4e15..8fa2f1c6 100644 --- a/tests/context/test_context_graphs_examples.py +++ b/tests/context/test_context_graphs_examples.py @@ -46,10 +46,10 @@ class TestContextGraphsExamples: # Create context graph with advanced features graph = ContextGraph( - enable_advanced_analytics=True, - enable_centrality_analysis=True, - enable_community_detection=True, - enable_node_embeddings=True + advanced_analytics=True, + centrality_analysis=True, + community_detection=True, + node_embeddings=True ) # Add a decision @@ -127,10 +127,10 @@ class TestContextGraphsExamples: context = AgentContext( vector_store=mock_vector_store, knowledge_graph=mock_knowledge_graph, - enable_decision_tracking=True, - enable_advanced_analytics=True, - enable_kg_algorithms=True, - enable_vector_store_features=True + decision_tracking=True, + advanced_analytics=True, + kg_algorithms=True, + vector_store_features=True ) # Credit decision with precedent search @@ -169,10 +169,10 @@ class TestContextGraphsExamples: context = AgentContext( vector_store=mock_vector_store, knowledge_graph=mock_knowledge_graph, - enable_decision_tracking=True, - enable_advanced_analytics=True, - enable_kg_algorithms=True, - enable_vector_store_features=True + decision_tracking=True, + advanced_analytics=True, + kg_algorithms=True, + vector_store_features=True ) # Treatment decision with policy compliance @@ -216,10 +216,10 @@ class TestContextGraphsExamples: context = AgentContext( vector_store=mock_vector_store, knowledge_graph=mock_knowledge_graph, - enable_decision_tracking=True, - enable_advanced_analytics=True, - enable_kg_algorithms=True, - enable_vector_store_features=True + decision_tracking=True, + advanced_analytics=True, + kg_algorithms=True, + vector_store_features=True ) # Legal decision with precedent analysis @@ -370,21 +370,21 @@ class TestContextGraphsExamples: context = AgentContext( vector_store=mock_vector_store, knowledge_graph=mock_knowledge_graph, - enable_decision_tracking=True, - enable_advanced_analytics=True, - enable_kg_algorithms=True, - enable_vector_store_features=True, - use_graph_expansion=True, + decision_tracking=True, + advanced_analytics=True, + kg_algorithms=True, + vector_store_features=True, + graph_expansion=True, max_expansion_hops=3, hybrid_alpha=0.7 ) # Verify configuration - assert context.config["enable_decision_tracking"] is True - assert context.config["enable_advanced_analytics"] is True - assert context.config["enable_kg_algorithms"] is True - assert context.config["enable_vector_store_features"] is True - assert context.config["use_graph_expansion"] is True + assert context.config["decision_tracking"] is True + assert context.config["advanced_analytics"] is True + assert context.config["kg_algorithms"] is True + assert context.config["vector_store_features"] is True + assert context.config["graph_expansion"] is True assert context.config["max_expansion_hops"] == 3 assert context.config["hybrid_alpha"] == 0.7 print("+ Configuration validation working") diff --git a/tests/context/test_end_to_end_context_integration.py b/tests/context/test_end_to_end_context_integration.py index a4e85347..220dad93 100644 --- a/tests/context/test_end_to_end_context_integration.py +++ b/tests/context/test_end_to_end_context_integration.py @@ -118,7 +118,7 @@ class TestEndToEndContextIntegration: results = retriever.retrieve( query="Credit limit increase for business expansion", max_results=10, - use_graph_expansion=True + graph_expansion=True ) print(f"โœ… Retrieved {len(results)} context items") @@ -286,10 +286,10 @@ class TestEndToEndContextIntegration: # Test different search configurations search_configs = [ - {"use_graph_expansion": False, "max_results": 10}, - {"use_graph_expansion": True, "max_results": 10}, - {"use_graph_expansion": True, "max_results": 20}, - {"use_graph_expansion": False, "max_results": 20}, + {"graph_expansion": False, "max_results": 10}, + {"graph_expansion": True, "max_results": 10}, + {"graph_expansion": True, "max_results": 20}, + {"graph_expansion": False, "max_results": 20}, ] for i, config in enumerate(search_configs): @@ -399,7 +399,7 @@ class TestEndToEndContextIntegration: ) # Should handle KG errors gracefully - results = retriever_broken.retrieve("Test query", max_results=5, use_graph_expansion=True) + results = retriever_broken.retrieve("Test query", max_results=5, graph_expansion=True) assert len(results) > 0, "Should handle KG errors gracefully" print("โœ… Handles KG errors gracefully") @@ -572,7 +572,7 @@ class TestRealWorldContextScenarios: context_results = retriever.retrieve( query="Premium customer investment and fraud assessment", max_results=15, - use_graph_expansion=True + graph_expansion=True ) print(f"โœ… Retrieved {len(context_results)} context items") diff --git a/tests/context/test_healthcare_context_graphs_e2e.py b/tests/context/test_healthcare_context_graphs_e2e.py index b936a0e3..f9b259d7 100644 --- a/tests/context/test_healthcare_context_graphs_e2e.py +++ b/tests/context/test_healthcare_context_graphs_e2e.py @@ -52,10 +52,10 @@ class TestHealthcareDecisionSystem: return AgentContext( vector_store=mock_vector_store, knowledge_graph=mock_knowledge_graph, - enable_decision_tracking=True, - enable_advanced_analytics=True, - enable_kg_algorithms=True, - enable_vector_store_features=True + decision_tracking=True, + advanced_analytics=True, + kg_algorithms=True, + vector_store_features=True ) def test_healthcare_decision_workflow(self, healthcare_context):