Upload folder using huggingface_hub

README.md

@@ -13,8 +13,8 @@ sdk_version: 5.30.0
 ![Gemini](https://img.shields.io/badge/Gemini-Flash-purple)
 
 
-
-A powerful AI-assisted tool for querying network fabric documentation using semantic search and large language models. This application allows network engineers and administrators to easily access and retrieve information about their network fabric through natural language queries.
+Queries network documentation with natural languague.
+Recommend ports to users
 
 ## 🚀 Key Features
 

README_AGENTS.md

@@ -0,0 +1,139 @@
+# Network Infrastructure AI Assistant
+
+This project implements an AI-powered network infrastructure assistant with specialized port recommendation capabilities using the OpenAI Agents SDK.
+
+## Architecture Overview
+
+The system follows a modular architecture based on the OpenAI Agents SDK:
+
+### Core Components
+
+1. **`retriever_tool.py`** - Network information retrieval tool
+   - Uses FAISS vector database for semantic search
+   - Searches through network documentation and device configurations
+   - Returns relevant network information with similarity scores
+
+2. **`port_recommnedations.py`** - Specialized port recommendations agent
+   - Expert agent focused on port/interface recommendations
+   - Understands MLAG configurations and redundancy requirements
+   - Provides specific device names and port numbers
+
+3. **`app.py`** - Main orchestrator application
+   - Combines retrieval tool and port recommendations agent
+   - Provides Gradio web interface
+   - Routes queries to appropriate tools based on context
+
+4. **`port_recommendations_standalone.py`** - Standalone port recommendations
+   - Direct access to port recommendations agent
+   - Useful for testing and scripting
+
+## Key Features
+
+### Port Recommendations
+- Automatic redundancy across MLAG pairs (leaf01/leaf02, leaf03/leaf04, etc.)
+- Same port numbers across paired devices when possible
+- Support for single port requests (without redundancy)
+- Detailed responses with device names and specific port identifiers
+
+### Network Information Retrieval
+- Semantic search through network documentation
+- Device-specific configuration lookup
+- Fabric-wide information queries
+
+## Usage Examples
+
+### Port Recommendations
+```python
+# Various ways to request ports
+"I need an unused port"                                    # Returns 2 ports with redundancy
+"I need an unused port without redundancy"                 # Returns 1 port
+"I need to dual connect a server to the network"          # Returns MLAG pair
+"What ports are available on leaf01?"                     # Device-specific query
+```
+
+### General Network Queries
+```python
+"What is the BGP configuration?"
+"Show me the VLAN settings"
+"What's the loopback pool configuration?"
+```
+
+## Running the System
+
+### Web Interface
+```bash
+python app.py
+```
+This launches a Gradio web interface where you can ask questions about the network infrastructure.
+
+### Standalone Port Recommendations
+```bash
+python port_recommendations_standalone.py
+```
+This runs a test suite with various port recommendation queries.
+
+### Testing Individual Components
+```python
+from port_recommnedations import port_recommendations_agent
+from retriever_tool import retrieve_network_information
+
+# Test retrieval tool
+result = retrieve_network_information("unused ports")
+
+# Test port agent (requires async)
+import asyncio
+from agents import Runner
+
+async def test():
+    result = await Runner.run(port_recommendations_agent, "I need a port")
+    print(result.final_output)
+
+asyncio.run(test())
+```
+
+## File Structure
+
+```
+agent-sdk/
+├── retriever_tool.py                 # Network information retrieval
+├── port_recommnedations.py           # Specialized port agent
+├── app.py                            # Main orchestrator with Gradio UI
+├── port_recommendations_standalone.py # Standalone port recommendations
+├── faiss_index/                      # Vector database
+├── prompts.yaml                      # Prompt templates
+└── README_AGENTS.md                  # This file
+```
+
+## Dependencies
+
+- `openai-agents`: OpenAI Agents SDK
+- `langchain-community`: FAISS and embeddings
+- `sentence-transformers`: Text embeddings
+- `gradio`: Web interface
+- `PyYAML`: Configuration files
+
+## Agent Design Principles
+
+Based on the OpenAI Agents SDK documentation:
+
+1. **Function Tools**: The retriever uses `@function_tool` decorator for automatic tool setup
+2. **Agents as Tools**: Port recommendations agent is used as a tool in the main orchestrator
+3. **Specialized Instructions**: Each agent has domain-specific instructions and behaviors
+4. **Tool Routing**: Main agent routes queries to appropriate specialized tools
+
+## Port Recommendation Rules
+
+The port recommendations agent follows these key rules:
+
+1. **Default Redundancy**: Always recommend two ports across different devices unless specifically requested otherwise
+2. **MLAG Pairing**: Recommend ports across MLAG pairs (odd/even leaf switches)
+3. **Port Alignment**: Try to use the same port number across paired devices
+4. **Specific Responses**: Include device names and exact port identifiers
+5. **Query First**: Will return only data from the leaf switches
+
+## Future Enhancements
+
+- Add more specialized agents (security policies, VLAN management, etc.)
+- Implement caching for frequently requested information
+- Add support for configuration changes and validation
+- Integrate with network management systems

analyze_unused.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""
+Analyze where UNUSED interfaces are actually located in the database.
+"""
+
+from langchain_community.embeddings import HuggingFaceEmbeddings
+from langchain_community.vectorstores import FAISS
+
+def analyze_unused_locations():
+    """Find where UNUSED interfaces are actually stored."""
+    
+    print("Analyzing where UNUSED interfaces are located...")
+    print("=" * 80)
+    
+    # Load the FAISS database
+    FAISS_INDEX_PATH = "faiss_index"
+    embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2")
+    db = FAISS.load_local(FAISS_INDEX_PATH, embeddings, allow_dangerous_deserialization=True)
+    
+    # Search for chunks that actually contain UNUSED
+    query = "UNUSED"
+    results_with_scores = db.similarity_search_with_score(query, k=15)
+    
+    print(f"Query: '{query}'")
+    print(f"Found {len(results_with_scores)} results")
+    print("=" * 80)
+    
+    for i, (doc, score) in enumerate(results_with_scores):
+        device_name = doc.metadata.get('device_name', 'Unknown')
+        header_path = doc.metadata.get('header_path', 'No header path')
+        section_title = doc.metadata.get('section_title', 'No section')
+        
+        unused_count = doc.page_content.count('UNUSED')
+        
+        if unused_count > 0:  # Only show chunks with UNUSED
+            print(f"\\nResult {i+1} (Score: {score:.4f}) - {unused_count} UNUSED")
+            print(f"  Device: {device_name}")
+            print(f"  Header Path: {header_path}")
+            print(f"  Section: {section_title}")
+            
+            # Show where UNUSED appears in content
+            lines = doc.page_content.split('\\n')
+            unused_lines = [line for line in lines if 'UNUSED' in line]
+            print(f"  UNUSED interfaces found:")
+            for line in unused_lines[:3]:  # Show first 3
+                print(f"    {line.strip()}")
+            
+            # Show broader context
+            print(f"  Content preview: {doc.page_content[:200]}...")
+            print("-" * 60)
+    
+    print("\\n" + "=" * 80)
+    print("Testing better queries for finding UNUSED interfaces...")
+    
+    # Test different queries
+    test_queries = [
+        "UNUSED interface Ethernet",
+        "Ethernet Interfaces Device Configuration UNUSED", 
+        "interface description UNUSED",
+        "switchport access vlan 50 UNUSED"
+    ]
+    
+    for query in test_queries:
+        print(f"\\nTesting query: '{query}'")
+        results = db.similarity_search_with_score(query, k=3)
+        for i, (doc, score) in enumerate(results):
+            unused_count = doc.page_content.count('UNUSED')
+            if unused_count > 0:
+                print(f"  ✅ Result {i+1}: {unused_count} UNUSED (score: {score:.4f})")
+                print(f"    Device: {doc.metadata.get('device_name', 'Unknown')}")
+                print(f"    Section: {doc.metadata.get('section_title', 'Unknown')}")
+            else:
+                print(f"  ❌ Result {i+1}: No UNUSED (score: {score:.4f})")
+
+if __name__ == "__main__":
+    analyze_unused_locations()

app.py

@@ -5,107 +5,111 @@
 #     "langchain",           # Core Langchain
 #     "faiss-cpu",           # FAISS vector store
 #     "sentence-transformers", # For HuggingFaceEmbeddings
-#     "smolagents",
+#     "openai-agents",       # OpenAI Agents SDK
+#     "gradio[mcp]",        
 #     "gradio",
-#     "einops",
-#     "smolagents[litellm]",
 #     # "unstructured" # Required by loader.py, not directly by app.py but good for environment consistency
 # ]
 # ///
 
 import yaml
-with open("prompts.yaml", 'r') as stream:
-    prompt_templates = yaml.safe_load(stream)
-
-# # OpenTelemetry
-# from opentelemetry import trace
-# from opentelemetry.sdk.trace import TracerProvider
-# from opentelemetry.sdk.trace.export import BatchSpanProcessor
-# from openinference.instrumentation.smolagents import SmolagentsInstrumentor
-# from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
-# from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
-# # Endpoint
-# endpoint = "http://0.0.0.0:6006/v1/traces"
-
-# trace_provider = TracerProvider()
-# trace_provider.add_span_processor(SimpleSpanProcessor(OTLPSpanExporter(endpoint)))
-# SmolagentsInstrumentor().instrument(tracer_provider=trace_provider)
-
-from langchain_community.vectorstores import FAISS
-from langchain_community.embeddings import HuggingFaceEmbeddings
-
-FAISS_INDEX_PATH = "faiss_index"
-EMBEDDING_MODEL_NAME = "sentence-transformers/all-MiniLM-L6-v2" # Must match loader.py
+import gradio as gr
+from agents import Agent, gen_trace_id, Runner, ModelSettings
+import asyncio
+from textwrap import dedent
 
-from smolagents import Tool
+# Import the retriever tool and port recommendations agent
+from retriever_tool import retrieve_network_information
+from port_recomendations import port_recommendations_agent
 
-class RetrieverTool(Tool):
-    name = "retriever"
-    description = "Provide information of our network using semantic search. " 
-    inputs = {
-        "query": {
-            "type": "string",
-            "description": "The query to perform. This should be semantically close to your target documents. Use the affirmative form rather than a question.",
-        }
-    }
-    output_type = "string"
-
-    def __init__(self, **kwargs):
-        super().__init__(**kwargs)
-        self.embeddings = HuggingFaceEmbeddings(model_name=EMBEDDING_MODEL_NAME)
-        # allow_dangerous_deserialization is recommended for FAISS indexes saved by Langchain
-        self.db = FAISS.load_local(
-            FAISS_INDEX_PATH, 
-            self.embeddings, 
-            allow_dangerous_deserialization=True
-        )
+with open("prompts.yaml", 'r') as stream:
+    prompt_templates = yaml.safe_load(stream)
 
-    def forward(self, query: str) -> str:
-        assert isinstance(query, str), "Your search query must be a string"
+# Create the main orchestrator agent with the port recommendations agent as a tool
+main_agent = Agent(
+    name="network_agent",
+    instructions=dedent("""
+        You are a network infrastructure assistant that helps users with various network-related queries.
+        You have access to specialized tools and agents:
+        
+        1. retrieve_network_information: For general network documentation queries
+        2. port_recommendations_tool: For port/interface recommendations and connectivity questions
         
-        results_with_scores = self.db.similarity_search_with_score(query, k=10)
+        Use the appropriate tool based on the user's request:
+        - For port recommendations, unused ports, interface questions, or device connectivity: use port_recommendations_tool
+        - For general network information, configuration details, or documentation queries: use retrieve_network_information
         
-        response = ""
-        if not results_with_scores:
-            return "No relevant information found in the documentation for your query."
+        Always be helpful, precise, and provide detailed responses based on the tools' output.
+    """),
+    model="gpt-4o-mini",
+    model_settings=ModelSettings(tool_choice="required", temperature=0.0),
+    tools=[
+        retrieve_network_information,
+        port_recommendations_agent.as_tool(
+            tool_name="port_recommendations_tool",
+            tool_description="Get port and interface recommendations for connecting devices to the network. Use this for questions about unused ports, interface recommendations, or device connectivity."
+        )
+    ],
+)
+async def run(query: str):
+    """ Run the network query process and return the final result"""
+    try:
+        trace_id = gen_trace_id()
+        print(f"View trace: https://platform.openai.com/traces/trace?trace_id={trace_id}")
+        
+        result = await Runner.run(
+            main_agent,
+            f"Query: {query}",
+            max_turns=5,
+        )
+        return result.final_output
+    except Exception as e:
+        print(f"Error during query processing: {e}")
+        return f"An error occurred during processing: {str(e)}"
+async def main(query: str):
+    result = await run(query)
+    print(result)
+    return result
 
-        for doc, score in results_with_scores:
-            device_name = doc.metadata.get('device_name')
-            source = doc.metadata.get('source', 'Unknown source')
-            
-            if device_name:
-                response += f"Device: {device_name} (Source: {source}, Score: {score:.4f})\n"
-            else:
-                # If not device_name, assume it's global/fabric information
-                response += f"Global/Fabric Info (Source: {source}, Score: {score:.4f})\n"
-            response += f"Result: {doc.page_content}\n\n"
+def sync_run(query: str):
+    """Synchronous wrapper for the async run function for Gradio"""
+    return asyncio.run(run(query))
+
+# Gradio Interface
+with gr.Blocks(theme=gr.themes.Default(primary_hue="blue")) as ui:
+    gr.Markdown("# Network Infrastructure Assistant")
+    gr.Markdown("Ask questions about network infrastructure, port recommendations, or device connectivity.")
+    
+    with gr.Row():
+        with gr.Column():
+            query_textbox = gr.Textbox(
+                label="Your Question",
+                placeholder="e.g., 'I need an unused port for a new server' or 'What's the BGP configuration?'",
+                lines=3
+            )
+            run_button = gr.Button("Ask", variant="primary")
             
-        print(f"Retrieved {len(results_with_scores)} results for query: '{query}'")
-        # print("Full response:\n", response) # For debugging if needed
-        return response
+        with gr.Column():
+            response_textbox = gr.Textbox(
+                label="Response",
+                lines=10,
+                interactive=False
+            )
     
-    # The 'device' method is removed as 'device_name' is now directly in metadata.
-
-retriever_tool = RetrieverTool()
-from smolagents import CodeAgent, HfApiModel, LiteLLMModel
-
-model = LiteLLMModel("gemini/gemini-2.0-flash")
-agent = CodeAgent(
-    model=model,
-    tools=[retriever_tool],
-    max_steps=10,
-    verbosity_level=2,
-    grammar=None,
-    planning_interval=None,
-    name="network_information_agent",
-    description="Have access to the network information of our fabric.",
-    add_base_tools=False)
-
-# # Example usage
-# response = agent.run(
-#     "What is the loopback Pool address used by the fabric, how many ip addresses are in use?"
-# )
-# print(response)
+    # Event handlers
+    run_button.click(fn=sync_run, inputs=query_textbox, outputs=response_textbox)
+    query_textbox.submit(fn=sync_run, inputs=query_textbox, outputs=response_textbox)
+    
+    # Example queries
+    gr.Markdown("### Example Queries:")
+    gr.Markdown("- I need an unused port for a new server")
+    gr.Markdown("- I need to dual connect a server to the network, what ports should I use?")
+    gr.Markdown("- What are the BGP settings for the fabric?")
+    gr.Markdown("- Show me the VLAN configuration")
 
-from smolagents import GradioUI
-GradioUI(agent).launch()
+if __name__ == "__main__":
+    # Test query
+    # test_result = asyncio.run(main("I need to dual connect a server to the network, what ports should I use?"))
+    
+    # Launch Gradio interface
+    ui.launch(inbrowser=True, debug=True, mcp_server=True)

explore_metadata.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""
+Test script to explore all metadata fields available in the FAISS database chunks.
+"""
+
+import os
+from langchain_community.embeddings import HuggingFaceEmbeddings
+from langchain_community.vectorstores import FAISS
+
+# Configuration
+FAISS_INDEX_PATH = "faiss_index"
+EMBEDDINGS_MODEL_NAME = "sentence-transformers/all-MiniLM-L6-v2"
+
+def explore_metadata():
+    """Explore all metadata fields available in the database chunks."""
+    print("EXPLORING METADATA IN FAISS DATABASE")
+    print("=" * 60)
+    
+    if not os.path.exists(FAISS_INDEX_PATH):
+        print(f"❌ Error: FAISS index not found at {FAISS_INDEX_PATH}")
+        return False
+    
+    try:
+        embeddings = HuggingFaceEmbeddings(model_name=EMBEDDINGS_MODEL_NAME)
+        vector_db = FAISS.load_local(FAISS_INDEX_PATH, embeddings, allow_dangerous_deserialization=True)
+        print(f"✅ Successfully loaded FAISS index from {FAISS_INDEX_PATH}")
+    except Exception as e:
+        print(f"❌ Error loading FAISS index: {e}")
+        return False
+    
+    # Get a sample of documents to analyze metadata
+    sample_queries = [
+        "Ethernet Interfaces Summary",
+        "UNUSED",
+        "interface configuration",
+        "device information",
+        "fabric"
+    ]
+    
+    all_metadata_keys = set()
+    metadata_examples = {}
+    
+    print("\nSampling documents to analyze metadata...")
+    print("-" * 40)
+    
+    for query in sample_queries:
+        try:
+            results = vector_db.similarity_search_with_score(query, k=3)
+            
+            for doc, score in results:
+                if doc.metadata:
+                    # Collect all metadata keys
+                    all_metadata_keys.update(doc.metadata.keys())
+                    
+                    # Store examples of each metadata field
+                    for key, value in doc.metadata.items():
+                        if key not in metadata_examples:
+                            metadata_examples[key] = []
+                        if value not in metadata_examples[key]:
+                            metadata_examples[key].append(value)
+                            
+        except Exception as e:
+            print(f"Error with query '{query}': {e}")
+    
+    # Display metadata analysis
+    print(f"\n🔍 METADATA ANALYSIS")
+    print("=" * 60)
+    print(f"Total unique metadata keys found: {len(all_metadata_keys)}")
+    print(f"Metadata keys: {sorted(all_metadata_keys)}")
+    
+    print(f"\n📋 DETAILED METADATA FIELDS:")
+    print("-" * 40)
+    
+    for key in sorted(all_metadata_keys):
+        examples = metadata_examples.get(key, [])
+        print(f"\n🔑 Field: '{key}'")
+        print(f"   Unique values found: {len(examples)}")
+        print(f"   Example values:")
+        for i, example in enumerate(examples[:5]):  # Show max 5 examples
+            print(f"     {i+1}: {repr(example)}")
+        if len(examples) > 5:
+            print(f"     ... and {len(examples) - 5} more")
+    
+    # Show some detailed examples
+    print(f"\n📄 SAMPLE DOCUMENTS WITH FULL METADATA:")
+    print("-" * 40)
+    
+    # Get a few documents to show complete metadata
+    sample_results = vector_db.similarity_search_with_score("Ethernet", k=3)
+    
+    for i, (doc, score) in enumerate(sample_results):
+        print(f"\n[SAMPLE {i+1}]")
+        print(f"Score: {score:.4f}")
+        print(f"Content Length: {len(doc.page_content)} characters")
+        print(f"Content Preview: {doc.page_content[:100].replace(chr(10), ' ')}...")
+        print(f"Complete Metadata:")
+        if doc.metadata:
+            for key, value in sorted(doc.metadata.items()):
+                print(f"  {key}: {repr(value)}")
+        else:
+            print("  No metadata found")
+        print("-" * 30)
+    
+    # Analysis summary
+    print(f"\n📊 SUMMARY:")
+    print("=" * 60)
+    
+    device_docs = len([ex for ex in metadata_examples.get('device_name', []) if ex])
+    source_files = len(metadata_examples.get('source', []))
+    
+    print(f"• Device documents found: {device_docs}")
+    print(f"• Source files found: {source_files}")
+    
+    if 'device_name' in all_metadata_keys:
+        print(f"• Device names: {metadata_examples.get('device_name', [])}")
+    
+    if 'source' in all_metadata_keys:
+        print(f"• Source file types: {set(f.split('.')[-1] if '.' in f else 'unknown' for f in metadata_examples.get('source', []))}")
+    
+    return True
+
+def main():
+    """Run the metadata exploration."""
+    success = explore_metadata()
+    
+    if success:
+        print("\n✅ Metadata exploration completed successfully!")
+        return 0
+    else:
+        print("\n❌ Metadata exploration failed")
+        return 1
+
+if __name__ == "__main__":
+    exit(main())

faiss_index/index.faiss

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:828be1f0d0f7a1249982a3858640ea1164e27a55a68ec7cece4a39ea502c375d
-size 347181
+oid sha256:e2bb0a47cc3c04d9b19379506d84d0d35ba2bdfbdae110574ea79aca0f01ce5f
+size 612909

faiss_index/index.pkl

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:f95e3a8e6e86b6c1df0cc92b569424dbeda0061a2081e21f107156921c10898b
-size 183933
+oid sha256:d712088b22f569606162167cde236f005479c49932000ae661f4d6c0a70da9e2
+size 317433

loader.py

@@ -1,49 +1,139 @@
-#!/usr/bin/env python3
+# /// script
+# dependencies = [
+#     "langchain_community",
+#     "langchain_core",
+# ]
+# ///
 """
-Improved loader script for creating FAISS vector database from Markdown documentation.
+Enhanced loader script for creating FAISS vector database from Markdown documentation
+with improved header metadata extraction.
 """
 
 import os
+import re
 from langchain_community.document_loaders import UnstructuredMarkdownLoader
 from langchain.text_splitter import MarkdownHeaderTextSplitter, RecursiveCharacterTextSplitter
 from langchain_community.embeddings import HuggingFaceEmbeddings
 from langchain_community.vectorstores import FAISS
+from langchain_core.documents import Document
 
-# Define the paths to your documentation folders
 DOCS_DIR = "documentation"
 DEVICE_DOCS_PATH = os.path.join(DOCS_DIR, "devices")
 FABRIC_DOCS_PATH = os.path.join(DOCS_DIR, "fabric")
 FAISS_INDEX_PATH = "faiss_index"
 
-def load_markdown_documents(file_paths):
+def extract_header_context(content, chunk_start_pos):
     """
-    Loads markdown documents from a list of file paths.
-    The filename is stored in the metadata of each document under the 'source' key.
-    Device name is stored in metadata if applicable.
+    Extract the header hierarchy for a given position in the markdown content.
+    Returns a dict with header levels and creates header_path and section_title.
     """
-    docs = []
+    lines = content[:chunk_start_pos].split('\n')
+    headers = {}
+    
+    # Track the current header hierarchy
+    for line in lines:
+        line = line.strip()
+        if line.startswith('#') and not line.startswith('#!'):  # Exclude shebang
+            # Count the number of # to determine header level
+            level = len(line) - len(line.lstrip('#'))
+            if 1 <= level <= 5:  # Only process header levels 1-5
+                header_text = line.lstrip('#').strip()
+                headers[f'header{level}'] = header_text
+                # Clear lower level headers when we encounter a higher level
+                for i in range(level + 1, 6):
+                    if f'header{i}' in headers:
+                        del headers[f'header{i}']
+    
+    return headers
+
+def enhance_chunk_metadata(chunk, original_content, chunk_position, file_metadata):
+    """
+    Enhance a chunk with header metadata and other contextual information.
+    """
+    # Start with file-level metadata
+    enhanced_metadata = file_metadata.copy()
+    
+    # Extract header context for this chunk position
+    header_context = extract_header_context(original_content, chunk_position)
+    enhanced_metadata.update(header_context)
+    
+    # Create header path from all header levels
+    header_path_parts = []
+    for i in range(1, 6):  # header1 through header5
+        if f'header{i}' in enhanced_metadata:
+            header_path_parts.append(enhanced_metadata[f'header{i}'])
+    
+    if header_path_parts:
+        enhanced_metadata['header_path'] = " > ".join(header_path_parts)
+        enhanced_metadata['section_title'] = header_path_parts[-1]  # Most specific header
+    
+    return enhanced_metadata
+
+def load_markdown_documents_with_headers(file_paths):
+    """
+    Loads markdown documents and creates chunks with enhanced header metadata.
+    """
+    all_documents = []
+    
     for file_path in file_paths:
-        loader = UnstructuredMarkdownLoader(file_path)
-        loaded_docs = loader.load()
-        for doc in loaded_docs:
-            # Ensure metadata is initialized
-            if doc.metadata is None:
-                doc.metadata = {}
-            # Add filename to metadata
-            doc.metadata['source'] = os.path.basename(file_path)
-            # Add device_name to metadata if it's a device file
-            if 'DCX-' in os.path.basename(file_path):
-                doc.metadata['device_name'] = os.path.basename(file_path).replace('.md', '')
-            # Removed device name prepending from here
-        docs.extend(loaded_docs)
-    return docs
+        print(f"Processing: {os.path.basename(file_path)}")
+        
+        # Read the raw markdown content
+        with open(file_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+        
+        # Create base metadata for this file
+        file_metadata = {
+            'source': os.path.basename(file_path)
+        }
+        
+        # Add device_name if it's a device file
+        if 'DCX-' in os.path.basename(file_path):
+            file_metadata['device_name'] = os.path.basename(file_path).replace('.md', '')
+        
+        # Split content into chunks using RecursiveCharacterTextSplitter
+        text_splitter = RecursiveCharacterTextSplitter(
+            chunk_size=800, 
+            chunk_overlap=200,
+            separators=["\n## ", "\n### ", "\n#### ", "\n##### ", "\n\n", "\n", " ", ""]
+        )
+        
+        chunks = text_splitter.split_text(content)
+        
+        for chunk in chunks:
+            # Find the position of this chunk in the original content
+            chunk_position = content.find(chunk)
+            if chunk_position == -1:
+                # If exact match not found, try finding a shorter prefix
+                chunk_start = chunk[:min(100, len(chunk))]
+                chunk_position = content.find(chunk_start)
+                if chunk_position == -1:
+                    chunk_position = 0  # Fallback to beginning
+            
+            # Enhance metadata with header context
+            enhanced_metadata = enhance_chunk_metadata(chunk, content, chunk_position, file_metadata)
+            
+            # Add device context to content if it's a device file
+            final_content = chunk
+            if 'device_name' in enhanced_metadata:
+                device_name = enhanced_metadata['device_name']
+                if not chunk.strip().startswith(f"Device: {device_name}"):
+                    final_content = f"Device: {device_name}\\n\\n{chunk}"
+            
+            # Create document with enhanced metadata
+            doc = Document(page_content=final_content, metadata=enhanced_metadata)
+            all_documents.append(doc)
+    
+    return all_documents
 
 def create_vector_db():
     """
-    Scans documentation folders, loads MD files, creates embeddings,
-    and saves a FAISS vector database.
+    Scans documentation folders, loads MD files with enhanced header metadata,
+    creates embeddings, and saves a FAISS vector database.
     """
     markdown_files = []
+    
+    # Collect all markdown files
     for root, _, files in os.walk(DEVICE_DOCS_PATH):
         for file in files:
             if file.endswith(".md"):
@@ -60,64 +150,37 @@ def create_vector_db():
 
     print(f"Found {len(markdown_files)} markdown files to process.")
 
-    # Load documents
-    documents = load_markdown_documents(markdown_files)
-    print(f"Loaded {len(documents)} documents.")
-
-    # Define headers to split on
-    headers_to_split_on = [
-        ("#", "header1"),
-        ("##", "header2"),
-        ("###", "header3"),
-    ]
+    # Load documents with enhanced header metadata
+    documents = load_markdown_documents_with_headers(markdown_files)
+    print(f"Created {len(documents)} document chunks with header metadata.")
     
-    # First split by headers to maintain context
-    header_splitter = MarkdownHeaderTextSplitter(headers_to_split_on=headers_to_split_on)
-    
-    # Split documents by headers first
-    header_split_docs = []
-    for doc in documents:
-        try:
-            header_split = header_splitter.split_text(doc.page_content)
-            for split_doc in header_split:
-                # Copy metadata from original document
-                split_doc.metadata.update(doc.metadata)
-            header_split_docs.extend(header_split)
-        except Exception as e:
-            print(f"Warning: Could not split by headers: {e}")
-            # If header splitting fails, keep the original document
-            header_split_docs.append(doc)
-    
-    # Then do recursive character splitting with smaller chunks and larger overlap
-    text_splitter = RecursiveCharacterTextSplitter(chunk_size=800, chunk_overlap=200)
-    texts = text_splitter.split_documents(header_split_docs)
-    print(f"Split documents into {len(texts)} chunks.")
-
-    # Add device context to each chunk's page_content if it's from a device file
-    for text_chunk in texts:
-        if 'device_name' in text_chunk.metadata:
-            device_name = text_chunk.metadata['device_name']
-            # Prepend device name to the content of the chunk
-            # Ensure it's not already prepended (e.g. if a header itself was the device name)
-            if not text_chunk.page_content.strip().startswith(f"Device: {device_name}"):
-                 text_chunk.page_content = f"Device: {device_name}\\n\\n{text_chunk.page_content}"
+    # Debug: Print sample metadata from first few chunks
+    print("\\nSample metadata from first 3 chunks:")
+    for i, doc in enumerate(documents[:3]):
+        print(f"\\nChunk {i+1}:")
+        print(f"  Source: {doc.metadata.get('source', 'Unknown')}")
+        print(f"  Device: {doc.metadata.get('device_name', 'N/A')}")
+        print(f"  Header Path: {doc.metadata.get('header_path', 'No headers')}")
+        print(f"  Section Title: {doc.metadata.get('section_title', 'No section')}")
+        print(f"  Content Preview: {doc.page_content[:100]}...")
 
-    print("Creating FAISS vector database...")
+    print("\\nCreating FAISS vector database...")
     embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2")
     print("Embeddings model loaded.")
 
     # Create FAISS vector store
-    if not texts:
-        print("No text chunks to process for FAISS index.")
+    if not documents:
+        print("No documents to process for FAISS index.")
         return
         
     print("Creating FAISS index...")
-    vector_db = FAISS.from_documents(texts, embeddings)
+    vector_db = FAISS.from_documents(documents, embeddings)
     print("FAISS index created.")
 
     # Save FAISS index
     vector_db.save_local(FAISS_INDEX_PATH)
     print(f"FAISS index saved to {FAISS_INDEX_PATH}")
+    print(f"Total chunks in database: {len(documents)}")
 
 if __name__ == "__main__":
     create_vector_db()

model.py

@@ -0,0 +1,16 @@
+from openai import AsyncOpenAI
+from dotenv import load_dotenv
+import os
+from agents import OpenAIChatCompletionsModel
+
+load_dotenv(override=True)
+
+google_api_key = os.getenv('GOOGLE_API_KEY')
+GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+gemini_client = AsyncOpenAI(base_url=GEMINI_BASE_URL, api_key=google_api_key)
+gemini_model = OpenAIChatCompletionsModel(model="gemini-2.0-flash", openai_client=gemini_client)
+
+qwen_api_key = "blah"
+qwen_base_url = "http://localhost:11434/v1"
+qwen_client = AsyncOpenAI(base_url=qwen_base_url, api_key=qwen_api_key)
+qwen_model = OpenAIChatCompletionsModel(model="qwen3:14b", openai_client=qwen_client)

port_recomendations.py

@@ -0,0 +1,147 @@
+from agents import Agent, function_tool
+from retriever_tool import db
+from textwrap import dedent
+from agents import Tool
+from model import gemini_model, qwen_model
+
+@function_tool
+def unused_ports() -> str:
+    """Get information about unused Ethernet interfaces across all network devices.
+    
+    This tool specifically queries for unused/available ports in the network infrastructure
+    by filtering documents with 'Ethernet Interfaces Summary' headers and UNUSED interfaces.
+    Only returns results from leaf switches (devices with 'LEAF' in their name).
+    """
+    
+    # Use metadata-based filtering instead of similarity search
+    # Get all documents from the vectorstore
+    all_docs_with_scores = db.similarity_search_with_score("", k=db.index.ntotal)
+    
+    # Filter documents by header metadata and device type
+    target_header = "Ethernet Interfaces Summary"
+    matching_docs = []
+    
+    for doc, score in all_docs_with_scores:
+        # Check if document has the target header
+        section_title = doc.metadata.get('section_title', '')
+        header_path = doc.metadata.get('header_path', '')
+        device_name = doc.metadata.get('device_name', '')
+        
+        # Filter for:
+        # 1. Documents with "Ethernet Interfaces Summary" in header path
+        # 2. Documents from LEAF devices only
+        # 3. Documents that contain UNUSED interfaces
+        is_ethernet_summary = (target_header == section_title or target_header in header_path)
+        is_leaf_device = 'LEAF' in device_name.upper()
+        has_unused = 'UNUSED' in doc.page_content
+        
+        if is_ethernet_summary and is_leaf_device and has_unused:
+            matching_docs.append((doc, score))
+    
+    response = ""
+    if not matching_docs:
+        return "No unused interface information found in Ethernet Interfaces Summary sections of leaf devices."
+
+    # Track devices and their unused interfaces
+    device_unused = {}
+    
+    for doc, score in matching_docs:
+        device_name = doc.metadata.get('device_name')
+        source = doc.metadata.get('source', 'Unknown source')
+        header_path = doc.metadata.get('header_path', 'No header path')
+        section_title = doc.metadata.get('section_title', 'No section title')
+        
+        if device_name:
+            # Count UNUSED interfaces in this chunk
+            unused_count = doc.page_content.count('UNUSED')
+            
+            if unused_count > 0:
+                if device_name not in device_unused:
+                    device_unused[device_name] = {
+                        'total_unused': 0,
+                        'sections': [],
+                        'source': source
+                    }
+                
+                device_unused[device_name]['total_unused'] += unused_count
+                device_unused[device_name]['sections'].append({
+                    'section': section_title,
+                    'header_path': header_path,
+                    'count': unused_count,
+                    'score': score
+                })
+    
+    # Format the response with enhanced metadata
+    if matching_docs:
+        # Attach the actual sections containing UNUSED interfaces from each document
+        for doc, score in matching_docs:
+            device_name = doc.metadata.get('device_name', 'Unknown device')
+            source = doc.metadata.get('source', 'Unknown source')
+            section_title = doc.metadata.get('section_title', 'No section title')
+            header_path = doc.metadata.get('header_path', 'No header path')
+            
+            response += f"---\n"
+            response += f"Device: {device_name} (Source: {source})\n"
+            response += f"Section: {section_title}\n"
+            response += f"Path: {header_path}\n\n"
+            
+            # Extract and attach only the lines that actually contain UNUSED interfaces
+            for line in doc.page_content.splitlines():
+                if 'UNUSED' in line:
+                    response += line + "\n"
+            
+            response += "\n"
+    else:
+        response += "No leaf devices with unused interfaces found in Ethernet Interfaces Summary sections."
+
+    print(f"Retrieved {len(matching_docs)} filtered results from Ethernet Interfaces Summary sections on leaf devices")
+    return response
+
+# Port recommendation specific instructions
+port_recommendation_instructions = dedent("""
+    You are an expert network assistant specialized in port and interface recommendations.
+    Your role is to use the available tools to answer questions about port/interface recommendations for connecting new devices to the network infrastructure.
+    
+    Key responsibilities:
+    - Port and interface are synonymous terms (users may use them interchangeably)
+    - Always use the retrieve_network_information tool to find unused interface ports before making recommendations
+    - Provide specific device names and port numbers in your recommendations
+    - Be detailed and precise in your responses
+    
+    Port Recommendation Rules:
+    1. If not specified otherwise, always recommend TWO ports across different devices for redundancy
+    2. Recommend ports across devices that form a MLAG or LACP group
+    3. Leaf switches are in MLAG pairs: odd-numbered leaf (leaf01, leaf03, etc.) paired with even-numbered leaf (leaf02, leaf04, etc.)
+    4. Try to select the same interface port number across paired devices (e.g., if recommending port 25 on leaf01, also recommend port 25 on leaf02)
+    5. Include device names and specific port identifiers in your response
+    6. If user specifically requests single port or "without redundancy", recommend only one port
+    7. Only recommend ports that have the description "UNUSED".
+                
+    
+    Response Format:
+    - Always query for unused ports first using retrieve_network_information
+    - Provide clear, actionable recommendations with device names and port numbers
+    - Explain the reasoning behind your recommendations when relevant
+    
+    Examples:
+    User: "I need an unused port"
+    Response: After checking available ports, I recommend using Ethernet1/25 on leaf01 and Ethernet1/25 on leaf02 for redundancy.
+    
+    User: "I need an unused port without redundancy"  
+    Response: After checking available ports, I recommend using Ethernet1/26 on leaf01.
+    
+    User: "I need to dual connect a server to the network, what ports should I use?"
+    Response: For dual-connecting a server, I recommend using Ethernet1/27 on leaf01 and Ethernet1/27 on leaf02, which will provide MLAG redundancy.
+    
+    User: "I need to connect two servers to the network, what ports should I use?"
+    Response: For connecting two servers, I recommend using Ethernet1/28-29 on leaf01 and Ethernet1/28-29 on leaf02 for redundancy.
+""")
+
+
+# Create the specialized port recommendations agent
+port_recommendations_agent = Agent(
+    name="port_recommendations_agent",
+    instructions=port_recommendation_instructions,
+    model=qwen_model,
+    tools=[unused_ports],
+)

port_recommendations_standalone.py

@@ -0,0 +1,41 @@
+
+import asyncio
+from agents import Runner, trace, gen_trace_id
+from port_recomendations import port_recommendations_agent
+
+async def get_port_recommendation(query: str):
+    """Get port recommendations using the specialized agent"""
+    trace_id = gen_trace_id()
+    with trace("Port Recommendation", trace_id=trace_id):
+        print(f"View trace: https://platform.openai.com/traces/trace?trace_id={trace_id}")
+        try:
+            result = await Runner.run(
+                port_recommendations_agent,
+                f"Query: {query}",
+                max_turns=5,
+            )
+            return result.final_output
+        except Exception as e:
+            print(f"Error during port recommendation: {e}")
+            return f"An error occurred: {str(e)}"
+
+async def main():
+    """Test the port recommendations agent with various queries"""
+    test_queries = [
+        "I need an unused port",
+        "I need an unused port without redundancy", 
+        "I need to dual connect a server to the network, what ports should I use?",
+        "What ports are available on leaf01?",
+        "I need 4 ports for a new switch connection"
+    ]
+    
+    for query in test_queries:
+        print(f"\n{'='*60}")
+        print(f"Query: {query}")
+        print(f"{'='*60}")
+        result = await get_port_recommendation(query)
+        print(f"Recommendation: {result}")
+        print()
+
+if __name__ == "__main__":
+    asyncio.run(main())

requirements.txt

@@ -8,4 +8,5 @@ einops
 langchain-community
 langchain
 faiss-cpu
-unstructured
+unstructured
+gradio[mcp]

retriever_tool.py

@@ -0,0 +1,49 @@
+
+from langchain_community.vectorstores import FAISS
+try:
+    from langchain_huggingface import HuggingFaceEmbeddings
+except ImportError:
+    # Fallback to deprecated import if langchain-huggingface is not installed
+    from langchain_community.embeddings import HuggingFaceEmbeddings
+from agents import function_tool
+
+FAISS_INDEX_PATH = "faiss_index"
+EMBEDDING_MODEL_NAME = "sentence-transformers/all-MiniLM-L6-v2"  # Must match loader.py
+
+# Initialize embeddings and vector store
+embeddings = HuggingFaceEmbeddings(model_name=EMBEDDING_MODEL_NAME)
+db = FAISS.load_local(
+    FAISS_INDEX_PATH, 
+    embeddings, 
+    allow_dangerous_deserialization=True
+)
+
+@function_tool
+def retrieve_network_information(query: str) -> str:
+    """Provide information of our network using semantic search.
+    
+    Args:
+        query: The query to search for in the network documentation. 
+               This should be semantically close to your target documents.
+               Use the affirmative form rather than a question.
+    """
+    
+    results_with_scores = db.similarity_search_with_score(query, k=10)
+    
+    response = ""
+    if not results_with_scores:
+        return "No relevant information found in the documentation for your query."
+
+    for doc, score in results_with_scores:
+        device_name = doc.metadata.get('device_name')
+        source = doc.metadata.get('source', 'Unknown source')
+        
+        if device_name:
+            response += f"Device: {device_name} (Source: {source}, Score: {score:.4f})\n"
+        else:
+            # If not device_name, assume it's global/fabric information
+            response += f"Global/Fabric Info (Source: {source}, Score: {score:.4f})\n"
+        response += f"Result: {doc.page_content}\n\n"
+            
+    print(f"Retrieved {len(results_with_scores)} results for query: '{query}'")
+    return response

setup.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""
+Setup script for the AI Agent System for Port Recommendations
+Helps configure the environment and run the system.
+"""
+
+import os
+import subprocess
+import sys
+
+def check_dependencies():
+    """Check if required dependencies are installed"""
+    print("🔍 Checking dependencies...")
+    
+    required_packages = [
+        "gradio",
+        "openai-agents", 
+        "faiss-cpu",
+        "langchain",
+        "langchain-community",
+        "sentence-transformers",
+        "PyYAML"
+    ]
+    
+    missing_packages = []
+    
+    for package in required_packages:
+        try:
+            __import__(package.replace("-", "_"))
+            print(f"✅ {package}")
+        except ImportError:
+            print(f"❌ {package} (missing)")
+            missing_packages.append(package)
+    
+    if missing_packages:
+        print(f"\n📦 Missing packages: {', '.join(missing_packages)}")
+        print("Install with: pip install " + " ".join(missing_packages))
+        return False
+    
+    print("✅ All dependencies installed!")
+    return True
+
+def check_environment():
+    """Check environment configuration"""
+    print("\n🔧 Checking environment...")
+    
+    # Check for OpenAI API key
+    if os.getenv("OPENAI_API_KEY"):
+        print("✅ OPENAI_API_KEY is set")
+        api_key_status = True
+    else:
+        print("❌ OPENAI_API_KEY is not set")
+        print("   Set it with: export OPENAI_API_KEY='your-api-key-here'")
+        api_key_status = False
+    
+    # Check for FAISS index
+    if os.path.exists("faiss_index"):
+        print("✅ FAISS index exists")
+        faiss_status = True
+    else:
+        print("❌ FAISS index not found")
+        print("   Run the loader script first to create the index")
+        faiss_status = False
+    
+    return api_key_status and faiss_status
+
+def show_usage_examples():
+    """Show usage examples"""
+    print("\n📖 Usage Examples:")
+    print("=" * 50)
+    
+    examples = [
+        {
+            "query": "I need an unused port for a new server",
+            "description": "Single port recommendation"
+        },
+        {
+            "query": "I need to dual connect a server to the network, what ports should I use?",
+            "description": "MLAG dual connection recommendation"
+        },
+        {
+            "query": "What are the BGP settings for the fabric?",
+            "description": "General network information query"
+        },
+        {
+            "query": "Show me available interfaces on switch01",
+            "description": "Device-specific port query"
+        }
+    ]
+    
+    for i, example in enumerate(examples, 1):
+        print(f"{i}. {example['description']}")
+        print(f"   Query: \"{example['query']}\"")
+        print()
+
+def main():
+    """Main setup function"""
+    print("🚀 AI Agent System Setup")
+    print("=" * 50)
+    
+    deps_ok = check_dependencies()
+    env_ok = check_environment()
+    
+    print("\n📊 Setup Summary:")
+    print("=" * 30)
+    
+    if deps_ok and env_ok:
+        print("✅ System ready to run!")
+        print("\n🎯 To start the system:")
+        print("   python app.py")
+        print("\n🌐 Web interface will be available at:")
+        print("   http://127.0.0.1:7862")
+        
+    else:
+        print("⚠️  Setup incomplete")
+        if not deps_ok:
+            print("   - Install missing dependencies")
+        if not env_ok:
+            print("   - Configure environment variables")
+            print("   - Create FAISS index if needed")
+    
+    show_usage_examples()
+    
+    print("\n🔗 Additional Resources:")
+    print("- README_AGENTS.md - Architecture documentation")
+    print("- IMPLEMENTATION_SUMMARY.md - Implementation details") 
+    print("- validate_system.py - System validation tests")
+    print("- demo.py - Interactive demonstration")
+
+if __name__ == "__main__":
+    main()