agent-framework-lib 0.8.1.post7__tar.gz → 0.8.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.8.1.post7
+Version: 0.8.2
 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.post7 → agent_framework_lib-0.8.2}/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.post7 → agent_framework_lib-0.8.2}/agent_framework/__init__.py

@@ -32,7 +32,7 @@ Example Usage:
     create_basic_agent_server(MyAgent, port=8000)
     ```
 
-Version: 0.8.1
+Version: 0.8.2
 Author: Cinco AI Team
 License: MIT
 """
@@ -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"

{agent_framework_lib-0.8.1.post7 → agent_framework_lib-0.8.2}/agent_framework/skills/builtin/scripts/create_and_register.py

@@ -174,7 +174,7 @@ def main() -> None:
 
     upload_result = _upload_file(filepath)
 
-    local_cleaned = _cleanup(filepath)
+    local_cleaned = False
 
     mime = _guess_mime(filepath)
     size_bytes = upload_result.get("size_bytes", 0)

{agent_framework_lib-0.8.1.post7 → agent_framework_lib-0.8.2}/agent_framework/skills/builtin/skills/file_access/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: file_access
-description: "Get file paths and URLs for embedding files in documents"
+description: "Get file paths, download files from storage to local disk, and resolve URLs for embedding"
 display_name: "Accès aux fichiers"
 metadata:
   config:
@@ -13,6 +13,10 @@ metadata:
       - embed image
       - image path
       - file reference
+      - download file
+      - retrieve file
+      - get file
+      - file to local
     requires:
       bins:
         - uv
@@ -20,6 +24,56 @@ metadata:
 
 ## File Access Instructions
 
+This skill provides two capabilities:
+1. **Resolve file paths** on the local filesystem
+2. **Download files from storage** to the local disk (works with any backend: local, S3, MinIO, GCP)
+
+---
+
+## 1. Download File from Storage to Local Disk
+
+Download a file from the agent's file storage to a local directory. Use this when you have a `file_id` (e.g. from a previously generated file) and need the file on disk.
+
+### Usage
+
+```bash
+uv run python -m agent_framework.skills.builtin.skills.file_access.download_to_local --file-id "8e0e7208-ad96-4815-b1d4-5387f58dc526" --target-dir "/tmp"
+```
+
+### Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--file-id` | Yes | The file ID to download (UUID from storage) |
+| `--target-dir` | No | Local directory to save the file (default: `/tmp`) |
+
+### Output Format (stdout)
+
+```json
+{"status": "success", "file": "/tmp/bonnes_pratiques.pdf", "size_bytes": 45321}
+```
+
+### Error Handling (stderr)
+
+```json
+{"status": "error", "message": "Failed to download 8e0e7208-...: HTTP 404 — File not found"}
+```
+
+### Common Use Cases
+
+#### Re-downloading a generated file to upload to workspace
+
+```bash
+# 1. Download the file from storage to /tmp
+uv run python -m agent_framework.skills.builtin.skills.file_access.download_to_local --file-id "8e0e7208-..." --target-dir "/tmp"
+
+# 2. Then use upload_workspace_artefact("/tmp/filename.pdf") to share it
+```
+
+---
+
+## 2. Resolve File Path
+
 Resolve absolute file paths by running the `get_file_path.py` script via `shell_exec`.
 
 ### Usage

agent_framework_lib-0.8.2/agent_framework/skills/builtin/skills/file_access/download_to_local.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Download a file from the agent's storage to a local directory.
+
+Uses the server's /files/{file_id}/download endpoint, which delegates to
+FileStorageManager.retrieve_file() — so it works transparently with any
+backend (local, S3, MinIO, GCP).
+
+Reads AGENT_HOST and AGENT_PORT from environment variables (injected by
+ShellTool). Auth headers are added automatically when REQUIRE_AUTH is set.
+"""
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+
+def _get_auth_headers() -> dict[str, str]:
+    """Return auth headers if REQUIRE_AUTH is enabled."""
+    require_auth = os.environ.get("REQUIRE_AUTH", "false").lower() == "true"
+    if not require_auth:
+        return {}
+    api_keys_str = os.environ.get("API_KEYS", "").strip()
+    if not api_keys_str:
+        return {}
+    first_key = next((k.strip() for k in api_keys_str.split(",") if k.strip()), "")
+    if not first_key:
+        return {}
+    return {"X-API-Key": first_key}
+
+
+def download_to_local(file_id: str, target_dir: str) -> str:
+    """Download a file from storage to a local directory.
+
+    Args:
+        file_id: The file ID in the storage system.
+        target_dir: Local directory where the file will be saved.
+
+    Returns:
+        Absolute path to the downloaded file.
+
+    Raises:
+        ValueError: If file_id is empty.
+        RuntimeError: If the download or save fails.
+    """
+    if not file_id or not file_id.strip():
+        raise ValueError("file_id cannot be empty")
+
+    host = os.environ.get("AGENT_HOST", "localhost")
+    port = os.environ.get("AGENT_PORT", "8203")
+
+    # First, get metadata to know the filename
+    meta_url = f"http://{host}:{port}/files/{file_id}/metadata"
+    meta_req = urllib.request.Request(meta_url, method="GET")
+    for key, value in _get_auth_headers().items():
+        meta_req.add_header(key, value)
+
+    try:
+        with urllib.request.urlopen(meta_req, timeout=30) as resp:
+            metadata = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        err = e.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"Failed to get metadata for {file_id}: HTTP {e.code} — {err}")
+    except urllib.error.URLError as e:
+        raise RuntimeError(f"Cannot connect to server at http://{host}:{port}: {e.reason}")
+
+    filename = metadata.get("filename", f"{file_id}.bin")
+
+    # Download the file content
+    download_url = f"http://{host}:{port}/files/{file_id}/download"
+    dl_req = urllib.request.Request(download_url, method="GET")
+    for key, value in _get_auth_headers().items():
+        dl_req.add_header(key, value)
+
+    try:
+        with urllib.request.urlopen(dl_req, timeout=60) as resp:
+            content = resp.read()
+    except urllib.error.HTTPError as e:
+        err = e.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"Failed to download {file_id}: HTTP {e.code} — {err}")
+    except urllib.error.URLError as e:
+        raise RuntimeError(f"Cannot connect to server at http://{host}:{port}: {e.reason}")
+
+    # Save to local directory
+    os.makedirs(target_dir, exist_ok=True)
+    filepath = os.path.join(target_dir, filename)
+    filepath = os.path.abspath(filepath)
+
+    with open(filepath, "wb") as f:
+        f.write(content)
+
+    return filepath
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Download a file from storage to a local directory."
+    )
+    parser.add_argument(
+        "--file-id",
+        required=True,
+        help="The file ID to download (e.g. '8e0e7208-ad96-4815-b1d4-5387f58dc526')",
+    )
+    parser.add_argument(
+        "--target-dir",
+        default="/tmp",
+        help="Local directory to save the file (default: /tmp)",
+    )
+    args = parser.parse_args()
+
+    try:
+        filepath = download_to_local(args.file_id, args.target_dir)
+        print(json.dumps({
+            "status": "success",
+            "file": filepath,
+            "size_bytes": os.path.getsize(filepath),
+        }))
+    except Exception as e:
+        print(
+            json.dumps({"status": "error", "message": str(e)}),
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()