swiftagentx 0.1.0__py3-none-any.whl

swiftagent/__init__.py

@@ -0,0 +1,69 @@
+"""
+SwiftAgent — Enterprise-grade fast-response Agent framework.
+
+Features:
+- Dual-model strategy (light for classification, heavy for execution)
+- Scenario toolchains (skip ReAct for high-frequency patterns)
+- Three-level cache (KB / tool result / session)
+- SSE streaming with fine-grained events
+- Production-ready (middleware, tracing, exponential backoff)
+"""
+
+from .core.agent import Agent
+from .core.model_client import ModelClient, ModelResponse, DummyModelClient, ModelClientFactory
+from .core.memory import Message, SessionMemory
+from .core.cache import CacheManager
+from .core.prompt import PromptManager, PromptTemplate
+from .core.router import IntentLevel, IntentResult, IntentRouter
+from .core.pipeline import PipelineStage, StageResult, RequestPipeline
+from .tools.base import Tool, ToolOutput, ToolOutputType, AgentContext
+from .tools.registry import ToolRegistry
+from .tools.executor import ToolExecutor
+from .tools.scenario import ScenarioConfig, ToolChainStep, ScenarioEngine
+from .stream.adapter import SSEStreamAdapter
+from .stream.builder import SSEEventBuilder
+from .models.schema import AgentRequest, AgentResponse, SessionContext
+from .models.config import SwiftAgentConfig, ModelTier
+from .middleware.base import Middleware, MiddlewareChain
+from .storage.base import StorageBackend
+from .storage.memory import MemoryStorage
+from .knowledge_base.document import Document, SearchResult
+from .knowledge_base.base import KnowledgeBase
+from .knowledge_base.memory import MemoryKnowledgeBase
+from .knowledge_base.tool import KnowledgeBaseTool
+from .knowledge_base.stage import KnowledgeBaseStage
+from .admin.service import AdminService
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core
+    "Agent",
+    "ModelClient", "ModelResponse", "DummyModelClient", "ModelClientFactory",
+    "Message", "SessionMemory",
+    "CacheManager",
+    "PromptManager", "PromptTemplate",
+    "IntentLevel", "IntentResult", "IntentRouter",
+    "PipelineStage", "StageResult", "RequestPipeline",
+    # Tools
+    "Tool", "ToolOutput", "ToolOutputType", "AgentContext",
+    "ToolRegistry", "ToolExecutor",
+    "ScenarioConfig", "ToolChainStep", "ScenarioEngine",
+    # Stream
+    "SSEStreamAdapter", "SSEEventBuilder",
+    # Models
+    "AgentRequest", "AgentResponse", "SessionContext",
+    "SwiftAgentConfig", "ModelTier",
+    # Middleware
+    "Middleware", "MiddlewareChain",
+    # Storage
+    "StorageBackend", "MemoryStorage",
+    # Knowledge Base
+    "Document", "SearchResult",
+    "KnowledgeBase", "MemoryKnowledgeBase",
+    "KnowledgeBaseTool", "KnowledgeBaseStage",
+    # Admin
+    "AdminService",
+    # Version
+    "__version__",
+]

swiftagent/admin/__init__.py

@@ -0,0 +1,13 @@
+"""
+Admin module — management API for SwiftAgent.
+"""
+
+from .service import AdminService
+from .flask_admin import create_flask_admin_blueprint
+from .fastapi_admin import create_fastapi_admin_router
+
+__all__ = [
+    "AdminService",
+    "create_flask_admin_blueprint",
+    "create_fastapi_admin_router",
+]

swiftagent/admin/fastapi_admin.py

@@ -0,0 +1,96 @@
+"""
+FastAPI Router for the admin API.
+
+Usage::
+
+    from swiftagent.admin import AdminService, create_fastapi_admin_router
+
+    service = AdminService(agent)
+    router = create_fastapi_admin_router(service)
+    app.include_router(router, prefix="/admin")
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:
+    from .service import AdminService
+
+
+def create_fastapi_admin_router(
+    service: "AdminService",
+    prefix: str = "/admin",
+    tags: Optional[List[str]] = None,
+):
+    """
+    Create a FastAPI APIRouter wired to *service*.
+
+    Returns a ``fastapi.APIRouter`` — include it in your FastAPI app.
+    """
+    try:
+        from fastapi import APIRouter
+        from pydantic import BaseModel
+    except ImportError:
+        raise ImportError("FastAPI is required for the admin router: pip install fastapi")
+
+    router = APIRouter(prefix=prefix, tags=tags or ["admin"])
+
+    # -- Request models --
+
+    class CacheClearRequest(BaseModel):
+        level: Optional[str] = None
+
+    class KBSearchRequest(BaseModel):
+        query: str
+        top_k: int = 5
+
+    class KBAddDocumentsRequest(BaseModel):
+        documents: List[Dict[str, Any]]
+
+    class ConfigUpdateRequest(BaseModel):
+        updates: Dict[str, Any] = {}
+
+    # -- Endpoints --
+
+    @router.get("/status")
+    async def status():
+        return service.get_status()
+
+    @router.get("/tools")
+    async def tools():
+        return service.get_tools()
+
+    @router.get("/cache/stats")
+    async def cache_stats():
+        return service.get_cache_stats()
+
+    @router.post("/cache/clear")
+    async def cache_clear(body: CacheClearRequest):
+        return service.clear_cache(body.level)
+
+    @router.get("/config")
+    async def get_config():
+        return service.get_config()
+
+    @router.put("/config")
+    async def update_config(body: ConfigUpdateRequest):
+        return service.update_config(body.updates)
+
+    @router.post("/kb/search")
+    async def kb_search(body: KBSearchRequest):
+        return await service.kb_search_async(body.query, top_k=body.top_k)
+
+    @router.post("/kb/documents")
+    async def kb_add_documents(body: KBAddDocumentsRequest):
+        return await service.kb_add_documents_async(body.documents)
+
+    @router.delete("/kb/documents/{doc_id}")
+    async def kb_delete_document(doc_id: str):
+        return await service.kb_delete_document_async(doc_id)
+
+    @router.get("/kb/stats")
+    async def kb_stats():
+        return await service.kb_stats_async()
+
+    return router

swiftagent/admin/flask_admin.py

@@ -0,0 +1,85 @@
+"""
+Flask Blueprint for the admin API.
+
+Usage::
+
+    from swiftagent.admin import AdminService, create_flask_admin_blueprint
+
+    service = AdminService(agent)
+    bp = create_flask_admin_blueprint(service)
+    app.register_blueprint(bp, url_prefix="/admin")
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .service import AdminService
+
+
+def create_flask_admin_blueprint(
+    service: "AdminService",
+    url_prefix: str = "/admin",
+):
+    """
+    Create a Flask Blueprint wired to *service*.
+
+    Returns a ``flask.Blueprint`` — register it with your Flask app.
+    """
+    try:
+        from flask import Blueprint, jsonify, request
+    except ImportError:
+        raise ImportError("Flask is required for the admin blueprint: pip install flask")
+
+    bp = Blueprint("swiftagent_admin", __name__, url_prefix=url_prefix)
+
+    @bp.route("/status", methods=["GET"])
+    def status():
+        return jsonify(service.get_status())
+
+    @bp.route("/tools", methods=["GET"])
+    def tools():
+        return jsonify(service.get_tools())
+
+    @bp.route("/cache/stats", methods=["GET"])
+    def cache_stats():
+        return jsonify(service.get_cache_stats())
+
+    @bp.route("/cache/clear", methods=["POST"])
+    def cache_clear():
+        body = request.get_json(silent=True) or {}
+        level = body.get("level")
+        return jsonify(service.clear_cache(level))
+
+    @bp.route("/config", methods=["GET"])
+    def get_config():
+        return jsonify(service.get_config())
+
+    @bp.route("/config", methods=["PUT"])
+    def update_config():
+        body = request.get_json(silent=True) or {}
+        return jsonify(service.update_config(body))
+
+    @bp.route("/kb/search", methods=["POST"])
+    def kb_search():
+        body = request.get_json(silent=True) or {}
+        query = body.get("query", "")
+        top_k = body.get("top_k", 5)
+        return jsonify(service.kb_search(query, top_k=top_k))
+
+    @bp.route("/kb/documents", methods=["POST"])
+    def kb_add_documents():
+        body = request.get_json(silent=True) or {}
+        documents = body.get("documents", [])
+        return jsonify(service.kb_add_documents(documents))
+
+    @bp.route("/kb/documents/<doc_id>", methods=["DELETE"])
+    def kb_delete_document(doc_id: str):
+        return jsonify(service.kb_delete_document(doc_id))
+
+    @bp.route("/kb/stats", methods=["GET"])
+    def kb_stats():
+        return jsonify(service.kb_stats())
+
+    return bp

swiftagent/admin/service.py

@@ -0,0 +1,254 @@
+"""
+AdminService — framework-agnostic management logic for a SwiftAgent agent.
+
+Provides status queries, configuration management, cache operations,
+and knowledge base management. Web framework adapters (Flask, FastAPI)
+call into this service layer.
+
+WARNING: Admin endpoints expose agent internals. Always add authentication
+middleware (Flask before_request / FastAPI Depends) in production.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import logging
+import re
+import time
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:
+    from ..core.agent import Agent
+
+logger = logging.getLogger(__name__)
+
+# Fields that may be updated at runtime via the admin API.
+_MUTABLE_CONFIG_FIELDS = frozenset({
+    "max_iterations", "max_retries", "enable_cache",
+    "kb_cache_ttl", "code_cache_ttl", "max_input_length",
+    "sse_heartbeat_interval", "sse_timeout", "log_level",
+    "kb_exact_match_threshold", "debug",
+    "max_cache_entries_per_level", "enable_request_tracing",
+})
+
+
+def _run_sync(coro):
+    """Run a coroutine synchronously, safe in both sync and async contexts."""
+    try:
+        asyncio.get_running_loop()
+        in_async = True
+    except RuntimeError:
+        in_async = False
+
+    if in_async:
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            return pool.submit(asyncio.run, coro).result()
+    else:
+        return asyncio.run(coro)
+
+
+class AdminService:
+    """
+    Stateless admin operations backed by an Agent instance.
+
+    Usage::
+
+        service = AdminService(agent)
+        status = service.get_status()
+    """
+
+    def __init__(self, agent: "Agent") -> None:
+        self.agent = agent
+        self._start_time = time.time()
+
+    # ---- Status ----
+
+    def get_status(self) -> Dict[str, Any]:
+        """Agent name, tool count, cache stats, uptime."""
+        return {
+            "name": self.agent.name,
+            "tools": self.agent.tool_registry.list_tools(),
+            "tool_count": self.agent.tool_registry.count(),
+            "cache_stats": self.agent.cache.get_stats(),
+            "has_knowledge_base": self.agent.knowledge_base is not None,
+            "uptime_seconds": round(time.time() - self._start_time, 1),
+        }
+
+    def get_tools(self) -> List[Dict[str, Any]]:
+        """Return JSON schema for every registered tool."""
+        return [
+            tool.get_schema()
+            for tool in self.agent.tool_registry.get_all().values()
+        ]
+
+    def get_cache_stats(self) -> Dict[str, Any]:
+        return self.agent.cache.get_stats()
+
+    # ---- Configuration ----
+
+    def get_config(self) -> Dict[str, Any]:
+        """Return current config with sensitive values masked."""
+        raw = self.agent.config.model_dump()
+        return self._mask_secrets(raw)
+
+    def update_config(self, updates: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Update config fields at runtime.
+
+        Only whitelisted mutable fields are accepted; values are validated
+        through Pydantic by re-constructing the config model.
+        Returns the full (masked) config after the update.
+        """
+        from ..models.config import SwiftAgentConfig
+
+        filtered = {k: v for k, v in updates.items() if k in _MUTABLE_CONFIG_FIELDS}
+        if not filtered:
+            return self.get_config()
+
+        current = self.agent.config.model_dump()
+        current.update(filtered)
+        try:
+            self.agent.config = SwiftAgentConfig(**current)
+        except Exception as e:
+            logger.warning(f"Config update rejected: {e}")
+            return {"error": f"Invalid config: {e}"}
+
+        return self.get_config()
+
+    # ---- Cache management ----
+
+    def clear_cache(self, level: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Clear cache entries.
+
+        Args:
+            level: One of "level_1", "level_2", "level_3", "scenario", or None (all).
+
+        Returns:
+            Confirmation dict.
+        """
+        if level is None:
+            self.agent.cache.clear_all()
+            return {"cleared": "all"}
+
+        cache = self.agent.cache
+        if level == "level_1":
+            cache.level_1_cache.clear()
+        elif level == "level_2":
+            cache.level_2_cache.clear()
+        elif level == "level_3":
+            cache.level_3_cache.clear()
+        elif level == "scenario":
+            cache.clear_scenario_cache()
+        else:
+            return {"error": f"Unknown cache level: {level}"}
+
+        return {"cleared": level}
+
+    # ---- Knowledge base (sync wrappers) ----
+
+    def kb_search(self, query: str, top_k: int = 5) -> List[Dict[str, Any]]:
+        """Synchronous wrapper — safe in both sync and async contexts."""
+        kb = self.agent.knowledge_base
+        if kb is None:
+            return []
+        results = _run_sync(kb.search(query, top_k=top_k))
+        return self._format_search_results(results)
+
+    def kb_add_documents(self, documents: List[Dict[str, Any]]) -> Dict[str, Any]:
+        kb = self.agent.knowledge_base
+        if kb is None:
+            return {"error": "No knowledge base configured"}
+        from ..knowledge_base.document import Document
+        try:
+            docs = [Document(**d) for d in documents]
+        except Exception as e:
+            return {"error": f"Invalid document data: {e}"}
+        added = _run_sync(kb.add_documents(docs))
+        return {"added": added}
+
+    def kb_delete_document(self, doc_id: str) -> Dict[str, Any]:
+        kb = self.agent.knowledge_base
+        if kb is None:
+            return {"error": "No knowledge base configured"}
+        deleted = _run_sync(kb.delete_document(doc_id))
+        return {"deleted": deleted, "doc_id": doc_id}
+
+    def kb_stats(self) -> Dict[str, Any]:
+        kb = self.agent.knowledge_base
+        if kb is None:
+            return {"error": "No knowledge base configured"}
+        count = _run_sync(kb.count())
+        return {"document_count": count, "provider": type(kb).__name__}
+
+    # ---- Knowledge base (async) ----
+
+    async def kb_search_async(self, query: str, top_k: int = 5) -> List[Dict[str, Any]]:
+        kb = self.agent.knowledge_base
+        if kb is None:
+            return []
+        results = await kb.search(query, top_k=top_k)
+        return self._format_search_results(results)
+
+    async def kb_add_documents_async(self, documents: List[Dict[str, Any]]) -> Dict[str, Any]:
+        kb = self.agent.knowledge_base
+        if kb is None:
+            return {"error": "No knowledge base configured"}
+        from ..knowledge_base.document import Document
+        try:
+            docs = [Document(**d) for d in documents]
+        except Exception as e:
+            return {"error": f"Invalid document data: {e}"}
+        added = await kb.add_documents(docs)
+        return {"added": added}
+
+    async def kb_delete_document_async(self, doc_id: str) -> Dict[str, Any]:
+        kb = self.agent.knowledge_base
+        if kb is None:
+            return {"error": "No knowledge base configured"}
+        deleted = await kb.delete_document(doc_id)
+        return {"deleted": deleted, "doc_id": doc_id}
+
+    async def kb_stats_async(self) -> Dict[str, Any]:
+        kb = self.agent.knowledge_base
+        if kb is None:
+            return {"error": "No knowledge base configured"}
+        count = await kb.count()
+        return {"document_count": count, "provider": type(kb).__name__}
+
+    # ---- Helpers ----
+
+    @staticmethod
+    def _format_search_results(results) -> List[Dict[str, Any]]:
+        return [
+            {
+                "doc_id": r.document.doc_id,
+                "content": r.document.content,
+                "score": r.score,
+                "match_type": r.match_type,
+                "metadata": r.document.metadata,
+            }
+            for r in results
+        ]
+
+    @staticmethod
+    def _mask_secrets(data: Dict[str, Any]) -> Dict[str, Any]:
+        """Mask values that look like API keys or secrets."""
+        masked = {}
+        secret_pattern = re.compile(
+            r"(key|secret|token|password|credential)", re.IGNORECASE
+        )
+        for key, value in data.items():
+            if isinstance(value, str) and secret_pattern.search(key) and len(value) > 4:
+                masked[key] = value[:4] + "***"
+            elif isinstance(value, dict):
+                masked[key] = AdminService._mask_secrets(value)
+            elif isinstance(value, list):
+                masked[key] = [
+                    AdminService._mask_secrets(item) if isinstance(item, dict) else item
+                    for item in value
+                ]
+            else:
+                masked[key] = value
+        return masked

swiftagent/core/__init__.py

@@ -0,0 +1,21 @@
+from .memory import Message, SessionMemory
+from .model_client import ModelResponse, ModelClient, ModelClientFactory
+from .cache import CacheEntry, CacheManager
+from .prompt import PromptTemplate, PromptManager
+from .parameter import ParameterManager, get_parameter_manager
+from .log_context import set_request_id, get_request_id, RequestIdFilter
+from .agent import Agent
+from .router import IntentLevel, IntentResult, IntentRouter
+from .pipeline import PipelineStage, StageResult, RequestPipeline
+
+__all__ = [
+    "Message", "SessionMemory",
+    "ModelResponse", "ModelClient", "ModelClientFactory",
+    "CacheEntry", "CacheManager",
+    "PromptTemplate", "PromptManager",
+    "ParameterManager", "get_parameter_manager",
+    "set_request_id", "get_request_id", "RequestIdFilter",
+    "Agent",
+    "IntentLevel", "IntentResult", "IntentRouter",
+    "PipelineStage", "StageResult", "RequestPipeline",
+]