agent-framework-lib 0.8.1.post8__tar.gz → 0.8.2.post2__tar.gz

{agent_framework_lib-0.8.1.post8/agent_framework_lib.egg-info → agent_framework_lib-0.8.2.post2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.8.1.post8
+Version: 0.8.2.post2
 Summary: A comprehensive Python framework for building and serving conversational AI agents with FastAPI
 Author-email: Sebastian Pavel <sebastian@cinco.ai>, Elliott Girard <elliott.girard@icloud.com>
 Maintainer-email: Sebastian Pavel <sebastian@cinco.ai>
@@ -89,6 +89,8 @@ Provides-Extra: excel
 Requires-Dist: openpyxl>=3.1.0; extra == "excel"
 Provides-Extra: drawio
 Requires-Dist: drawpyo>=0.1.0; extra == "drawio"
+Provides-Extra: gitnexus
+Requires-Dist: httpx>=0.27.0; extra == "gitnexus"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.4.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -186,7 +188,7 @@ uv add agent-framework-lib[llamaindex,mcp]
 uv add agent-framework-lib[all]
 ```
 
-**Available extras:** `llamaindex`, `mcp`, `mongodb`, `elasticsearch`, `postgresql`, `s3`, `minio`, `gcp`, `multimodal`, `memory`, `memori`, `graphiti`, `graphiti-falkordb`, `graphiti-neo4j`, `graphiti-all`, `observability`, `monitoring`, `websearch`, `dev`, `all`
+**Available extras:** `llamaindex`, `mcp`, `gitnexus`, `mongodb`, `elasticsearch`, `postgresql`, `s3`, `minio`, `gcp`, `multimodal`, `memory`, `memori`, `graphiti`, `graphiti-falkordb`, `graphiti-neo4j`, `graphiti-all`, `observability`, `monitoring`, `websearch`, `dev`, `all`
 
 **Optional: System Dependencies**
 
@@ -245,35 +247,74 @@ The framework includes a built-in AI assistant that helps you create agents! Acc
 
 **Features:**
 - 🧠 Deep knowledge of framework documentation, examples, and source code
-- 🔍 Search tools for docs and examples
+- 🔍 **GitNexus-powered code intelligence** - 12937 symbols, 36668 relationships, 300 execution flows
 - 💡 Code generation assistance
 - 📚 Indexed knowledge base (30+ files)
 - 🗄️ Persistent knowledge graph (FalkorDB) - survives server restarts
+- 🔎 Hybrid search (semantic + structural + text fallback)
 
 **Access:** `http://localhost:8000/helper`
 
+### GitNexus Setup (Recommended)
+
+For the best experience, install and run GitNexus to enable semantic code search:
+
+```bash
+# 1. Install and index the codebase
+./scripts/setup_gitnexus.sh
+
+# 2. Start the GitNexus server
+./scripts/start_gitnexus_server.sh
+
+# 3. Verify it's running
+curl http://localhost:4747/health
+```
+
+The helper agent will automatically use GitNexus if available, with graceful fallback to text search if not running.
+
+**What GitNexus enables:**
+- Semantic code search across the entire framework
+- Full symbol context (callers, callees, imports, dependencies)
+- Execution flow tracing (300 end-to-end code paths)
+- Impact analysis and relationship queries
+
+📖 **[User Guide](docs/GITNEXUS_USER_GUIDE.md)** - Complete guide for using GitNexus features with the Helper Agent
+
+**Optional dependencies:**
+```bash
+# Install GitNexus support
+uv add agent-framework-lib[gitnexus]
+```
+
 The helper agent indexes:
 - All documentation (`docs/*.md`)
 - All examples (`examples/*.py`)
+- All builtin skills (`agent_framework/skills/builtin/skills/*/SKILL.md`)
 - Core framework source (tools, storage, memory, session management)
 
 **Re-indexing:** If you update documentation or examples, trigger a re-index:
 ```bash
+# Re-index knowledge base
 curl -X POST http://localhost:8000/helper/reindex
+
+# Re-index GitNexus (after code changes)
+npx gitnexus analyze --embeddings
 ```
 
 **Model Configuration:**
 
-By default, the helper agent uses Claude (if `ANTHROPIC_API_KEY` is set) or GPT-5.2 (if `OPENAI_API_KEY` is set). You can override this with:
+By default, the helper agent uses Claude (if `ANTHROPIC_API_KEY` is set) or GPT-5.4 (if `OPENAI_API_KEY` is set). You can override this with:
 
 ```env
 # Force a specific model (useful if your Anthropic key has reached its limit)
-HELPER_AGENT_MODEL=gpt-5.2
+HELPER_AGENT_MODEL=gpt-5.4
 ```
 
 **Example questions:**
 - "How do I create an agent with memory?"
-- "Show me how to use PDF tools"
+- "Show me the execution flow for skill loading"
+- "What calls the MemoryProvider class?"
+- "Find all code related to authentication"
 - "What's the difference between Memori and Graphiti?"
 - "How do I configure S3 storage?"
 - "Search the web for LlamaIndex best practices"

{agent_framework_lib-0.8.1.post8 → agent_framework_lib-0.8.2.post2}/README.md

@@ -36,7 +36,7 @@ uv add agent-framework-lib[llamaindex,mcp]
 uv add agent-framework-lib[all]
 ```
 
-**Available extras:** `llamaindex`, `mcp`, `mongodb`, `elasticsearch`, `postgresql`, `s3`, `minio`, `gcp`, `multimodal`, `memory`, `memori`, `graphiti`, `graphiti-falkordb`, `graphiti-neo4j`, `graphiti-all`, `observability`, `monitoring`, `websearch`, `dev`, `all`
+**Available extras:** `llamaindex`, `mcp`, `gitnexus`, `mongodb`, `elasticsearch`, `postgresql`, `s3`, `minio`, `gcp`, `multimodal`, `memory`, `memori`, `graphiti`, `graphiti-falkordb`, `graphiti-neo4j`, `graphiti-all`, `observability`, `monitoring`, `websearch`, `dev`, `all`
 
 **Optional: System Dependencies**
 
@@ -95,35 +95,74 @@ The framework includes a built-in AI assistant that helps you create agents! Acc
 
 **Features:**
 - 🧠 Deep knowledge of framework documentation, examples, and source code
-- 🔍 Search tools for docs and examples
+- 🔍 **GitNexus-powered code intelligence** - 12937 symbols, 36668 relationships, 300 execution flows
 - 💡 Code generation assistance
 - 📚 Indexed knowledge base (30+ files)
 - 🗄️ Persistent knowledge graph (FalkorDB) - survives server restarts
+- 🔎 Hybrid search (semantic + structural + text fallback)
 
 **Access:** `http://localhost:8000/helper`
 
+### GitNexus Setup (Recommended)
+
+For the best experience, install and run GitNexus to enable semantic code search:
+
+```bash
+# 1. Install and index the codebase
+./scripts/setup_gitnexus.sh
+
+# 2. Start the GitNexus server
+./scripts/start_gitnexus_server.sh
+
+# 3. Verify it's running
+curl http://localhost:4747/health
+```
+
+The helper agent will automatically use GitNexus if available, with graceful fallback to text search if not running.
+
+**What GitNexus enables:**
+- Semantic code search across the entire framework
+- Full symbol context (callers, callees, imports, dependencies)
+- Execution flow tracing (300 end-to-end code paths)
+- Impact analysis and relationship queries
+
+📖 **[User Guide](docs/GITNEXUS_USER_GUIDE.md)** - Complete guide for using GitNexus features with the Helper Agent
+
+**Optional dependencies:**
+```bash
+# Install GitNexus support
+uv add agent-framework-lib[gitnexus]
+```
+
 The helper agent indexes:
 - All documentation (`docs/*.md`)
 - All examples (`examples/*.py`)
+- All builtin skills (`agent_framework/skills/builtin/skills/*/SKILL.md`)
 - Core framework source (tools, storage, memory, session management)
 
 **Re-indexing:** If you update documentation or examples, trigger a re-index:
 ```bash
+# Re-index knowledge base
 curl -X POST http://localhost:8000/helper/reindex
+
+# Re-index GitNexus (after code changes)
+npx gitnexus analyze --embeddings
 ```
 
 **Model Configuration:**
 
-By default, the helper agent uses Claude (if `ANTHROPIC_API_KEY` is set) or GPT-5.2 (if `OPENAI_API_KEY` is set). You can override this with:
+By default, the helper agent uses Claude (if `ANTHROPIC_API_KEY` is set) or GPT-5.4 (if `OPENAI_API_KEY` is set). You can override this with:
 
 ```env
 # Force a specific model (useful if your Anthropic key has reached its limit)
-HELPER_AGENT_MODEL=gpt-5.2
+HELPER_AGENT_MODEL=gpt-5.4
 ```
 
 **Example questions:**
 - "How do I create an agent with memory?"
-- "Show me how to use PDF tools"
+- "Show me the execution flow for skill loading"
+- "What calls the MemoryProvider class?"
+- "Find all code related to authentication"
 - "What's the difference between Memori and Graphiti?"
 - "How do I configure S3 storage?"
 - "Search the web for LlamaIndex best practices"

{agent_framework_lib-0.8.1.post8 → agent_framework_lib-0.8.2.post2}/agent_framework/__init__.py

@@ -23,16 +23,16 @@ Key Components:
 Example Usage:
     ```python
     from agent_framework import AgentInterface, create_basic_agent_server
-    
+
     class MyAgent(AgentInterface):
         async def handle_message(self, session_id: str, agent_input):
             return StructuredAgentOutput(response_text="Hello!")
-    
+
     # Start server
     create_basic_agent_server(MyAgent, port=8000)
     ```
 
-Version: 0.8.1
+Version: 0.8.2
 Author: Cinco AI Team
 License: MIT
 """
@@ -48,29 +48,29 @@ logger = logging.getLogger(__name__)
 def _auto_setup_dependencies() -> None:
     """
     Automatically check and install required dependencies at import time.
-    
+
     This runs synchronously when the package is first imported, ensuring
     Playwright browsers and Deno are available before any async tools try to use them.
-    
+
     Set AGENT_FRAMEWORK_SKIP_AUTO_SETUP=1 to disable this behavior.
     """
     if os.environ.get("AGENT_FRAMEWORK_SKIP_AUTO_SETUP", "").lower() in ("1", "true", "yes"):
         return
-    
+
     # Only run once per process
     global _AUTO_SETUP_DONE
     if "_AUTO_SETUP_DONE" in globals() and _AUTO_SETUP_DONE:
         return
     _AUTO_SETUP_DONE = True
-    
+
     try:
         from .utils.post_install import ensure_playwright_browsers, ensure_deno
-        
+
         # Check/install Playwright (silent if already installed)
         success, error = ensure_playwright_browsers()
         if not success and error:
             logger.warning(f"Playwright setup: {error}")
-        
+
         # Check/install Deno (silent if already installed)
         success, message, deno_path = ensure_deno()
         if not success and message:
@@ -79,7 +79,7 @@ def _auto_setup_dependencies() -> None:
             # Success but with PATH instructions
             logger.info(f"Deno: {message}")
             logger.info(f"Deno will be available via: {deno_path}")
-            
+
     except Exception as e:
         # Don't fail the import if setup fails - tools will show errors when used
         logger.debug(f"Auto-setup skipped: {e}")
@@ -88,7 +88,7 @@ def _auto_setup_dependencies() -> None:
 # Track if auto-setup has been done
 _AUTO_SETUP_DONE = False
 
-__version__ = "0.8.1"
+__version__ = "0.8.2"
 __author__ = "Cinco AI Team"
 __license__ = "MIT"
 __email__ = "sebastian@cinco.ai"
@@ -157,19 +157,19 @@ from .session.session_storage import (
 
 # File system management (consolidated)
 from .storage.file_system_management import (
-    FileStorageManager, 
-    FileStorageFactory, 
+    FileStorageManager,
+    FileStorageFactory,
     process_file_inputs,
     process_response_file_links,
     get_download_url,
-    get_file_processing_summary, 
-    FileInputMixin
+    get_file_processing_summary,
+    FileInputMixin,
 )
 from .storage.file_storages import (
     FileStorageInterface,
     MetadataStorageInterface,
-    FileMetadata, 
-    LocalFileStorage
+    FileMetadata,
+    LocalFileStorage,
 )
 
 # Optional file storage backends (only available if dependencies are installed)
@@ -196,13 +196,11 @@ __all__ = [
     # Version info
     "__version__",
     "__author__",
-    
     # Core interfaces
     "AgentInterface",
-    "StructuredAgentInput", 
+    "StructuredAgentInput",
     "StructuredAgentOutput",
     "AgentConfig",
-    
     # Base implementations
     "BaseAgent",
     "LlamaIndexAgent",
@@ -210,16 +208,15 @@ __all__ = [
     "StateManager",
     "AgentIdentity",
     "AgentManager",
-    
     # Input/Output types
     "TextInputPart",
-    "ImageUrlInputPart", 
+    "ImageUrlInputPart",
     "FileDataInputPart",
     "AgentInputPartUnion",
     "TextOutputPart",
     "TextOutputStreamPart",
     "JsonOutputPart",
-    "YamlOutputPart", 
+    "YamlOutputPart",
     "FileContentOutputPart",
     "FileReferenceInputPart",
     "FileReferenceOutputPart",
@@ -231,87 +228,77 @@ __all__ = [
     "FileDownloadLinkOutputPart",
     "ImageOutputPart",
     "AgentOutputPartUnion",
-    
     # Utility functions
     "consolidate_text_parts",
     "strip_technical_details",
-    
     # Model configuration
     "ModelConfigManager",
-    "ModelProvider", 
+    "ModelProvider",
     "model_config",
     "ModelClientFactory",
     "client_factory",
-    
     # Session storage
     "SessionStorageInterface",
     "SessionStorageFactory",
     "SessionData",
     "MessageData",
-    "MessageInsight", 
+    "MessageInsight",
     "MessageMetadata",
     "AgentLifecycleData",
     "MemorySessionStorage",
     "MongoDBSessionStorage",
     "history_message_to_message_data",
     "message_data_to_history_message",
-    
     # File storage implementations (consolidated)
     "FileStorageInterface",
     "MetadataStorageInterface",
-    "FileMetadata", 
+    "FileMetadata",
     "LocalFileStorage",
     "S3FileStorage",
     "MinIOFileStorage",
     "S3_AVAILABLE",
     "MINIO_AVAILABLE",
-    
     # File system management (consolidated)
     "FileStorageManager",
-    "FileStorageFactory", 
+    "FileStorageFactory",
     "process_file_inputs",
     "get_file_processing_summary",
     "FileInputMixin",
-    
     # Server
     "app",
     "start_server",
-
     # Utilities
     "get_deno_command",
-
     # Convenience functions
     "create_basic_agent_server",
 ]
 
+
 # Quick start function for convenience
 def create_basic_agent_server(
-    agent_class: type[AgentInterface], 
-    host: str = "0.0.0.0", 
-    port: int = 8000, 
-    reload: bool = False
+    agent_class: type[AgentInterface], host: str = "0.0.0.0", port: int = 8000, reload: bool = False
 ) -> None:
     """
     Quick start function to create and run an agent server.
-    
+
     This function allows external projects to quickly start an agent server
     without needing to create their own server.py file or set environment variables.
-    
+
     Args:
         agent_class: The agent class that implements AgentInterface
         host: Host to bind the server to (default: "0.0.0.0")
         port: Port to run the server on (default: 8000)
         reload: Whether to enable auto-reload for development (default: False)
-                Note: When reload=True, the agent class is temporarily stored in an 
+                Note: When reload=True, the agent class is temporarily stored in an
                 environment variable to survive module reloads.
-    
+
     Returns:
         None (starts the server and blocks)
-    
+
     Raises:
         ImportError: If uvicorn is not available
         ValueError: If agent_class does not implement AgentInterface
-    
+
     Example:
         >>> from agent_framework import create_basic_agent_server, AgentInterface
         >>> from my_agent import MyAgent
@@ -323,17 +310,16 @@ def create_basic_agent_server(
         raise ImportError(
             "uvicorn is required to run the server. Install it with: uv add uvicorn"
         ) from e
-    
+
     # Validate that agent_class implements AgentInterface
     if not issubclass(agent_class, AgentInterface):
-        raise ValueError(
-            f"agent_class must implement AgentInterface, got {agent_class.__name__}"
-        )
-    
+        raise ValueError(f"agent_class must implement AgentInterface, got {agent_class.__name__}")
+
     # Store the agent class globally for immediate use
     from .web import server
+
     server._GLOBAL_AGENT_CLASS = agent_class
-    
+
     # If reload is enabled, also store in environment variable to survive reloads
     # We use the class's module and name to recreate the import path
     if reload:
@@ -341,37 +327,32 @@ def create_basic_agent_server(
         class_name = agent_class.__name__
         agent_class_path = f"{module_name}:{class_name}"
         os.environ["AGENT_CLASS_PATH"] = agent_class_path
-        logger.info(f"[create_basic_agent_server] Reload enabled. Set AGENT_CLASS_PATH={agent_class_path}")
-    
-    logger.info(f"[create_basic_agent_server] Starting server for {agent_class.__name__} on {host}:{port}")
+        logger.info(
+            f"[create_basic_agent_server] Reload enabled. Set AGENT_CLASS_PATH={agent_class_path}"
+        )
+
+    logger.info(
+        f"[create_basic_agent_server] Starting server for {agent_class.__name__} on {host}:{port}"
+    )
     logger.info(f"[create_basic_agent_server] Reload: {reload}")
 
     # Ensure AGENT_HOST and AGENT_PORT are in the environment so that
     # subprocesses (e.g. skill scripts via ShellTool) can reach this server.
     os.environ["AGENT_HOST"] = host
     os.environ["AGENT_PORT"] = str(port)
-    
+
     # When reload=True, uvicorn requires an import string, not the app object directly
     if reload:
         # Use the agent_framework.web.server:app import string for reload mode
-        uvicorn.run(
-            "agent_framework.web.server:app",
-            host=host,
-            port=port,
-            reload=reload
-        )
+        uvicorn.run("agent_framework.web.server:app", host=host, port=port, reload=reload)
     else:
         # Import the app after setting the global variable for non-reload mode
         from .web.server import app
+
         # For non-reload mode, we can pass the app object directly
-        uvicorn.run(
-            app,
-            host=host,
-            port=port,
-            reload=reload
-        )
+        uvicorn.run(app, host=host, port=port, reload=reload)
 
 
 # Run auto-setup when package is imported
 # This ensures Playwright browsers and Deno are installed before any async tools need them
-_auto_setup_dependencies()
+_auto_setup_dependencies()

{agent_framework_lib-0.8.1.post8 → agent_framework_lib-0.8.2.post2}/agent_framework/a2a/base.py

@@ -11,6 +11,7 @@ logger = logging.getLogger(__name__)
 
 class A2ATaskProviderError(Exception):
     """Base exception for task provider errors."""
+
     def __init__(self, message: str, code: int = -32603):
         super().__init__(message)
         self.code = code
@@ -18,6 +19,7 @@ class A2ATaskProviderError(Exception):
 
 class TaskNotFoundError(A2ATaskProviderError):
     """Raised when a task ID is not found."""
+
     def __init__(self, task_id: str):
         super().__init__(f"Task not found: {task_id}", code=-32001)
         self.task_id = task_id
@@ -25,6 +27,7 @@ class TaskNotFoundError(A2ATaskProviderError):
 
 class TaskNotCancelableError(A2ATaskProviderError):
     """Raised when trying to cancel a task in a terminal state."""
+
     def __init__(self, task_id: str, current_state: str):
         super().__init__(
             f"Task {task_id} is in terminal state '{current_state}' and cannot be canceled",
@@ -36,6 +39,7 @@ class TaskNotCancelableError(A2ATaskProviderError):
 
 class TaskTerminalStateError(A2ATaskProviderError):
     """Raised when trying to update a task already in a terminal state."""
+
     def __init__(self, task_id: str, current_state: str):
         super().__init__(
             f"Task {task_id} is in terminal state '{current_state}' and cannot be modified",

{agent_framework_lib-0.8.1.post8 → agent_framework_lib-0.8.2.post2}/agent_framework/a2a/endpoints/agent_card_builder.py

@@ -48,7 +48,6 @@ class AgentCardBuilder:
         }
         return card
 
-
     def _resolve_url(
         self,
         injected_url: str | None = None,

{agent_framework_lib-0.8.1.post8 → agent_framework_lib-0.8.2.post2}/agent_framework/a2a/endpoints/agent_card_skill_builder.py

@@ -9,12 +9,42 @@ from typing import Any
 
 logger = logging.getLogger(__name__)
 
-_STOP_WORDS = frozenset({
-    "the", "and", "for", "with", "from", "that", "this", "are", "was",
-    "will", "can", "has", "have", "been", "not", "but", "all", "any",
-    "each", "more", "also", "into", "over", "such", "than", "its",
-    "about", "between", "through", "during", "before", "after",
-})
+_STOP_WORDS = frozenset(
+    {
+        "the",
+        "and",
+        "for",
+        "with",
+        "from",
+        "that",
+        "this",
+        "are",
+        "was",
+        "will",
+        "can",
+        "has",
+        "have",
+        "been",
+        "not",
+        "but",
+        "all",
+        "any",
+        "each",
+        "more",
+        "also",
+        "into",
+        "over",
+        "such",
+        "than",
+        "its",
+        "about",
+        "between",
+        "through",
+        "during",
+        "before",
+        "after",
+    }
+)
 
 
 class AgentCardSkillBuilder:
@@ -85,12 +115,14 @@ class AgentCardSkillBuilder:
             joined = "; ".join(descriptions)
             description = self._truncate_description(joined, len(framework_skills))
 
-            return [{
-                "id": "framework-capabilities",
-                "name": "Framework Capabilities",
-                "description": description,
-                "tags": names,
-            }]
+            return [
+                {
+                    "id": "framework-capabilities",
+                    "name": "Framework Capabilities",
+                    "description": description,
+                    "tags": names,
+                }
+            ]
         except Exception:
             logger.warning("Failed to build framework skill from registry")
             return [self._make_default_framework_skill()]
@@ -108,12 +140,14 @@ class AgentCardSkillBuilder:
 
         result = []
         for server_key in mcp_params:
-            result.append({
-                "id": f"mcp-{server_key}",
-                "name": f"MCP: {server_key}",
-                "description": f"MCP server: {server_key}",
-                "tags": ["mcp", server_key],
-            })
+            result.append(
+                {
+                    "id": f"mcp-{server_key}",
+                    "name": f"MCP: {server_key}",
+                    "description": f"MCP server: {server_key}",
+                    "tags": ["mcp", server_key],
+                }
+            )
         return result
 
     def _build_tool_skills(self, agent_instance: Any) -> list[dict]:
@@ -128,16 +162,16 @@ class AgentCardSkillBuilder:
         for tool in agent_tools:
             try:
                 tool_name = (
-                    getattr(tool, "__name__", None)
-                    or getattr(tool, "name", None)
-                    or str(tool)
+                    getattr(tool, "__name__", None) or getattr(tool, "name", None) or str(tool)
+                )
+                result.append(
+                    {
+                        "id": f"tool-{tool_name}",
+                        "name": tool_name,
+                        "description": f"Tool: {tool_name}",
+                        "tags": ["tool", tool_name],
+                    }
                 )
-                result.append({
-                    "id": f"tool-{tool_name}",
-                    "name": tool_name,
-                    "description": f"Tool: {tool_name}",
-                    "tags": ["tool", tool_name],
-                })
             except Exception:
                 logger.warning("Failed to build skill for tool %s", tool)
         return result
@@ -192,9 +226,7 @@ class AgentCardSkillBuilder:
                 break
         return tags
 
-    def _truncate_description(
-        self, description: str, total_skills: int = 0
-    ) -> str:
+    def _truncate_description(self, description: str, total_skills: int = 0) -> str:
         """Truncates description to MAX_FRAMEWORK_DESC_LENGTH with suffix.
 
         Args: