[FEATURE] Agno Framework Integration

[KaifAhmad1]

Problem Statement

Semantica provides semantic intelligence with knowledge graphs and provenance tracking, but lacks native integration with Agno framework. Developers building agentic systems with Agno must write custom wrapper code to integrate Semantica's semantic capabilities, leading to inconsistent implementations and duplicated effort.

Proposed Solution

Create an optional integration package at integrations/agno/ in the Semantica monorepo, providing adapter layers that make Semantica components compatible with Agno's interfaces.

Why This Approach:

• No Core Bloat - Agno dependencies only installed when needed
• Maintainable - Integration updates don't require core releases
• Drop-in Replacement - Implements Agno's MemoryManager interface perfectly
• Clean Separation - Integration code isolated from core semantic logic

Implementation Approach: Monorepo with Optional Dependencies

This integration will live in the same repository as Semantica core but as a completely separate, optional package.

Structure:

semantica/
├── semantica/              # Core package (no framework deps)
├── integrations/           # Optional integrations
│   └── agno/
│       ├── semantica_agno/
│       │   ├── __init__.py
│       │   ├── memory.py       # SemanticaMemory (MemoryManager impl)
│       │   ├── retriever.py    # SemanticaRetriever
│       │   └── utils.py
│       ├── tests/
│       ├── examples/
│       ├── setup.py
│       └── README.md
└── setup.py                # Root setup with extras_require

Installation:

# Core only (default) - no Agno dependencies
pip install semantica

# With Agno integration (optional) - includes agno
pip install semantica[agno]

What Needs to Be Added to Root setup.py:

# In semantica/setup.py
setup(
    name="semantica",
    version="0.2.3",
    packages=find_packages(exclude=["integrations*"]),  # Exclude integration packages
    install_requires=[
        # Core dependencies only (no framework deps)
        "numpy>=1.21.0",
        "spacy>=3.0.0",
        # ... other core deps
    ],
    extras_require={
        # Add this new optional dependency group
        "agno": ["agno"],
        # Can combine with other extras
        "all-integrations": ["google-adk", "claude-agent-sdk", "agno"]
    }
)

Core Integration Components

SemanticaMemory — Wraps AgentContext to implement Agno's MemoryManager interface
SemanticaKnowledgeBase — Wraps ContextGraph for graph-based agent memory
SemanticaRetriever — Wraps ContextRetriever for hybrid vector+graph retrieval

Features

• Drop-in replacement for Agno's default memory manager
• Semantic context with knowledge graph expansion
• Multi-hop reasoning and graph traversal
• Provenance tracking for all agent interactions
• Hybrid search (vector + graph)
• Zero breaking changes to core

Use Cases

Agentic Memory Systems

• Replace Agno's default memory with semantic knowledge graphs
• Enable multi-hop reasoning across agent conversations
• Track provenance for all agent decisions

Explainable Agents

• Build agents with transparent reasoning paths
• Trace decisions back to source documents
• Validate outputs against domain knowledge

GraphRAG Workflows

• Combine vector similarity with graph reasoning
• Perform entity linking and relationship discovery
• Build dynamic knowledge graphs from conversations

Example Usage

from agno import Agent
from semantica_agno import SemanticaMemory
from semantica.context import AgentContext, ContextGraph
from semantica.vector_store import VectorStore

# Initialize Semantica components
vector_store = VectorStore(backend="faiss", dimension=768)
context = AgentContext(
    vector_store=vector_store,
    knowledge_graph=ContextGraph(),
    use_graph_expansion=True,
    hybrid_alpha=0.6
)

# Create Semantica memory manager for Agno
memory = SemanticaMemory(
    context=context,
    enable_provenance=True,
    max_hops=3
)

# Create Agno agent with Semantica memory
agent = Agent(
    name="SemanticAgent",
    memory_manager=memory,
    enable_agentic_memory=True
)

# Agent now uses semantic knowledge graphs
response = agent.run("What did we discuss about the project timeline?")
print(response)

# Access provenance
provenance = memory.get_provenance(response)
print(f"Sources: {provenance['sources']}")

Implementation Plan

Step 0: Create Integrations Folder (First Time Only)

IMPORTANT: Before implementing any integration, create the integrations/ folder in the repository root:

# In the semantica repository root
mkdir integrations
touch integrations/__init__.py  # Empty file or integration registry

This folder will house ALL framework integrations (Google ADK, Claude Agent, Agno, etc.) and is separate from the core semantica/ package.

Step 1: Create Directory Structure

integrations/agno/
├── semantica_agno/
│   ├── __init__.py
│   ├── memory.py         # SemanticaMemory (MemoryManager impl)
│   ├── retriever.py      # SemanticaRetriever
│   └── utils.py          # Helper functions
├── tests/
│   ├── test_memory.py
│   ├── test_retriever.py
│   └── test_integration.py
├── examples/
│   ├── basic_usage.py
│   ├── multi_hop_reasoning.py
│   └── graphrag_workflow.py
├── setup.py              # Integration-specific setup
├── README.md             # Integration documentation
└── requirements.txt      # Integration dependencies

Step 2: Implement MemoryManager

memory.py - SemanticaMemory:

• Implements Agno's MemoryManager interface
• Uses Semantica's AgentContext for storage
• Methods: store(), retrieve(), update(), delete()
• Supports graph expansion and provenance tracking
• Hybrid vector + graph retrieval

Step 3: Implement Retriever

retriever.py - SemanticaRetriever:

• Implements Agno's RetrieverInterface
• Uses Semantica's hybrid search
• Supports multi-hop graph traversal
• Batch retrieval capability

Step 4: Create Integration Setup File

integrations/agno/setup.py:

from setuptools import setup, find_packages

setup(
    name="semantica-agno",
    version="0.1.0",
    description="Agno framework integration for Semantica",
    packages=find_packages(),
    install_requires=[
        "semantica",
        "agno",
    ],
    python_requires=">=3.8",
)

Step 5: Update Root Setup.py

Add to semantica/setup.py:

extras_require={
    "agno": ["agno"],
}

Step 6: Add Documentation

Create integrations/agno/README.md with installation, usage examples, and API reference.

Dependencies

• agno (only when installing with extras)
• Existing Semantica components (no changes to core needed)

Benefits

• Drop-in Replacement - Seamless integration with existing Agno agents
• Semantic Memory - Knowledge graphs instead of simple vector storage
• Multi-hop Reasoning - Graph traversal for complex queries
• Provenance - Track all agent decisions to sources
• Maintainable - Integration issues don't block core releases
• No Core Bloat - Optional dependencies keep core lean
• Zero Breaking Changes - Existing APIs unchanged

Additional Context

• Integration guide and examples will be provided
• Unit and integration tests required

Labels

enhancement integration agno explainable-ai