gitlab-api 25.14.5__py3-none-any.whl

gitlab_api/__init__.py

@@ -0,0 +1,78 @@
+# gitlab_api/__init__.py
+
+import importlib
+import inspect
+from typing import List
+
+__all__: List[str] = []
+
+# Core modules – always available (part of base dependencies)
+CORE_MODULES = [
+    "gitlab_api.decorators",
+    "gitlab_api.exceptions",
+    "gitlab_api.gitlab_input_models",
+    "gitlab_api.gitlab_response_models",
+    "gitlab_api.gitlab_api",
+    "gitlab_api.utils",
+]
+
+# Optional modules – only import if their dependencies are installed
+OPTIONAL_MODULES = {
+    "gitlab_api.gitlab_gql": "gql",  # Requires gql
+}
+
+
+def _import_module_safely(module_name: str):
+    """Try to import a module and return it, or None if not available."""
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        # Optional: log at debug level why it failed
+        # import logging
+        # logging.debug(f"Optional module {module_name} not imported: {e}")
+        return None
+
+
+def _expose_members(module):
+    """Expose public classes and functions from a module into globals and __all__."""
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            __all__.append(name)
+
+
+# Always import core modules
+for module_name in CORE_MODULES:
+    module = importlib.import_module(module_name)
+    _expose_members(module)
+
+# Conditionally import optional modules
+for module_name, extra_name in OPTIONAL_MODULES.items():
+    module = _import_module_safely(module_name)
+    if module is not None:
+        _expose_members(module)
+        # Optional: add a marker so users can check what's available
+        globals()[f"_{extra_name.upper()}_AVAILABLE"] = True
+    else:
+        globals()[f"_{extra_name.upper()}_AVAILABLE"] = False
+
+# Optional: expose availability flags
+_MCP_AVAILABLE = OPTIONAL_MODULES.get("gitlab_api.gitlab_mcp") in [
+    m.__name__ for m in globals().values() if hasattr(m, "__name__")
+]
+_A2A_AVAILABLE = "gitlab_api.gitlab_agent" in globals()
+_GQL_AVAILABLE = "gitlab_api.gitlab_gql" in globals()
+
+__all__.extend(["_MCP_AVAILABLE", "_A2A_AVAILABLE", "_GQL_AVAILABLE"])
+
+"""
+GitLab API - A Python Wrapper for GitLab
+
+Features are conditionally loaded based on installed extras:
+- base: core API client and models
+- [mcp]: FastMCP server and tools
+- [a2a]: Agent-to-Agent multi-agent system with Graphiti knowledge graph
+- [gql]: GraphQL support
+"""

gitlab_api/__main__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/python
+# coding: utf-8
+
+from gitlab_api.gitlab_mcp import gitlab_mcp
+
+if __name__ == "__main__":
+    gitlab_mcp()

gitlab_api/decorators.py

@@ -0,0 +1,20 @@
+#!/usr/bin/python
+# coding: utf-8
+
+import functools
+from gitlab_api.exceptions import LoginRequiredError
+
+
+def require_auth(function):
+    """
+    Wraps API calls in function that ensures headers are passed
+    with a token
+    """
+
+    @functools.wraps(function)
+    def wrapper(self, *args, **kwargs):
+        if not self.headers:
+            raise LoginRequiredError
+        return function(self, *args, **kwargs)
+
+    return wrapper

gitlab_api/exceptions.py

@@ -0,0 +1,42 @@
+#!/usr/bin/python
+# coding: utf-8
+
+
+class AuthError(Exception):
+    """
+    Authentication error
+    """
+
+    pass
+
+
+class UnauthorizedError(AuthError):
+    """
+    Unauthorized error
+    """
+
+    pass
+
+
+class MissingParameterError(Exception):
+    """
+    Missing Parameter error
+    """
+
+    pass
+
+
+class ParameterError(Exception):
+    """
+    Parameter error
+    """
+
+    pass
+
+
+class LoginRequiredError(Exception):
+    """
+    Authentication error
+    """
+
+    pass

gitlab_api/gitlab_agent.py

@@ -0,0 +1,362 @@
+#!/usr/bin/python
+# coding: utf-8
+import json
+import os
+import argparse
+import logging
+import uvicorn
+from contextlib import asynccontextmanager
+from typing import Optional, Any, List
+
+from fastmcp import Client
+from pydantic_ai import Agent, ModelSettings
+from pydantic_ai.mcp import load_mcp_servers
+from pydantic_ai.toolsets.fastmcp import FastMCPToolset
+from pydantic_ai_skills import SkillsToolset
+from pydantic_ai.models.openai import OpenAIChatModel
+from pydantic_ai.models.anthropic import AnthropicModel
+from pydantic_ai.models.google import GoogleModel
+from pydantic_ai.models.huggingface import HuggingFaceModel
+from fasta2a import Skill
+from gitlab_api.utils import (
+    to_integer,
+    to_boolean,
+    load_skills_from_directory,
+    get_skills_path,
+    get_mcp_config_path,
+)
+
+from fastapi import FastAPI, Request
+from starlette.responses import Response, StreamingResponse
+from pydantic import ValidationError
+from pydantic_ai.ui import SSE_CONTENT_TYPE
+from pydantic_ai.ui.ag_ui import AGUIAdapter
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    handlers=[logging.StreamHandler()],  # Output to console
+)
+logging.getLogger("pydantic_ai").setLevel(logging.INFO)
+logging.getLogger("fastmcp").setLevel(logging.INFO)
+logging.getLogger("httpx").setLevel(logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_HOST = os.getenv("HOST", "0.0.0.0")
+DEFAULT_PORT = to_integer(string=os.getenv("PORT", "9000"))
+DEFAULT_DEBUG = to_boolean(string=os.getenv("DEBUG", "False"))
+DEFAULT_PROVIDER = os.getenv("PROVIDER", "openai")
+DEFAULT_MODEL_ID = os.getenv("MODEL_ID", "qwen/qwen3-8b")
+DEFAULT_OPENAI_BASE_URL = os.getenv("OPENAI_BASE_URL", "http://127.0.0.1:1234/v1")
+DEFAULT_OPENAI_API_KEY = os.getenv("OPENAI_API_KEY", "ollama")
+DEFAULT_MCP_URL = os.getenv("MCP_URL", None)
+DEFAULT_MCP_CONFIG = os.getenv("MCP_CONFIG", get_mcp_config_path())
+DEFAULT_SKILLS_DIRECTORY = os.getenv("SKILLS_DIRECTORY", get_skills_path())
+DEFAULT_ENABLE_WEB_UI = to_boolean(os.getenv("ENABLE_WEB_UI", "False"))
+
+AGENT_NAME = "GitLab"
+AGENT_DESCRIPTION = "An agent built with Agent Skills and GitLab MCP tools to maximize GitLab interactivity."
+AGENT_SYSTEM_PROMPT = (
+    "You are the GitLab Agent.\n"
+    "You have access to all GitLab skills and toolsets to interact with the API.\n"
+    "Your responsibilities:\n"
+    "1. Analyze the user's request.\n"
+    "2. Identify the domain (e.g., branches, commits, MRs) and select the appropriate skills.\n"
+    "3. Use the skills to reference the tools you will need to search for using the tool_search skill.\n"
+    "4. If a complicated task requires multiple skills (e.g. 'check out branch X and verify the last commit'), "
+    "   orchestrate them sequentially: call the Branch skill, then the Commit skill.\n"
+    "5. Always be warm, professional, and helpful.\n"
+    "6. Explain your plan in detail before executing."
+)
+
+
+def create_model(
+    provider: str = DEFAULT_PROVIDER,
+    model_id: str = DEFAULT_MODEL_ID,
+    base_url: Optional[str] = DEFAULT_OPENAI_BASE_URL,
+    api_key: Optional[str] = DEFAULT_OPENAI_API_KEY,
+):
+    if provider == "openai":
+        target_base_url = base_url or DEFAULT_OPENAI_BASE_URL
+        target_api_key = api_key or DEFAULT_OPENAI_API_KEY
+        if target_base_url:
+            os.environ["OPENAI_BASE_URL"] = target_base_url
+        if target_api_key:
+            os.environ["OPENAI_API_KEY"] = target_api_key
+        return OpenAIChatModel(model_id, provider="openai")
+
+    elif provider == "anthropic":
+        if api_key:
+            os.environ["ANTHROPIC_API_KEY"] = api_key
+        return AnthropicModel(model_id)
+
+    elif provider == "google":
+        if api_key:
+            os.environ["GEMINI_API_KEY"] = api_key
+            os.environ["GOOGLE_API_KEY"] = api_key
+        return GoogleModel(model_id)
+
+    elif provider == "huggingface":
+        if api_key:
+            os.environ["HF_TOKEN"] = api_key
+        return HuggingFaceModel(model_id)
+
+
+def create_agent(
+    provider: str = DEFAULT_PROVIDER,
+    model_id: str = DEFAULT_MODEL_ID,
+    base_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    mcp_url: str = DEFAULT_MCP_URL,
+    mcp_config: str = DEFAULT_MCP_CONFIG,
+    skills_directory: Optional[str] = DEFAULT_SKILLS_DIRECTORY,
+) -> Agent:
+    agent_toolsets = []
+
+    if mcp_config:
+        mcp_toolset = load_mcp_servers(mcp_config)
+        agent_toolsets.extend(mcp_toolset)
+        logger.info(f"Connected to MCP Config JSON: {mcp_toolset}")
+    elif mcp_url:
+        fastmcp_toolset = FastMCPToolset(Client[Any](mcp_url, timeout=3600))
+        agent_toolsets.append(fastmcp_toolset)
+        logger.info(f"Connected to MCP Server: {mcp_url}")
+
+    if skills_directory and os.path.exists(skills_directory):
+        logger.debug(f"Loading skills {skills_directory}")
+        skills = SkillsToolset(directories=[str(skills_directory)])
+        agent_toolsets.append(skills)
+        logger.info(f"Loaded Skills at {skills_directory}")
+
+    # Create the Model
+    model = create_model(provider, model_id, base_url, api_key)
+
+    logger.info("Initializing Agent...")
+
+    settings = ModelSettings(timeout=3600.0)
+
+    return Agent(
+        model=model,
+        system_prompt=AGENT_SYSTEM_PROMPT,
+        name="GitLab_Agent",
+        toolsets=agent_toolsets,
+        deps_type=Any,
+        model_settings=settings,
+    )
+
+
+async def chat(agent: Agent, prompt: str):
+    result = await agent.run(prompt)
+    print(f"Response:\n\n{result.output}")
+
+
+async def node_chat(agent: Agent, prompt: str) -> List:
+    nodes = []
+    async with agent.iter(prompt) as agent_run:
+        async for node in agent_run:
+            nodes.append(node)
+            print(node)
+    return nodes
+
+
+async def stream_chat(agent: Agent, prompt: str) -> None:
+    # Option A: Easiest & most common - just stream the final text output
+    async with agent.run_stream(prompt) as result:
+        async for text_chunk in result.stream_text(
+            delta=True
+        ):  # ← streams partial text deltas
+            print(text_chunk, end="", flush=True)
+        print("\nDone!")  # optional
+
+
+def create_agent_server(
+    provider: str = DEFAULT_PROVIDER,
+    model_id: str = DEFAULT_MODEL_ID,
+    base_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    mcp_url: str = DEFAULT_MCP_URL,
+    mcp_config: str = DEFAULT_MCP_CONFIG,
+    skills_directory: Optional[str] = DEFAULT_SKILLS_DIRECTORY,
+    debug: Optional[bool] = DEFAULT_DEBUG,
+    host: Optional[str] = DEFAULT_HOST,
+    port: Optional[int] = DEFAULT_PORT,
+    enable_web_ui: bool = DEFAULT_ENABLE_WEB_UI,
+):
+    print(
+        f"Starting {AGENT_NAME} with provider={provider}, model={model_id}, mcp={mcp_url} | {mcp_config}"
+    )
+    agent = create_agent(
+        provider=provider,
+        model_id=model_id,
+        base_url=base_url,
+        api_key=api_key,
+        mcp_url=mcp_url,
+        mcp_config=mcp_config,
+        skills_directory=skills_directory,
+    )
+
+    # Define Skills for Agent Card (High-level capabilities)
+    if skills_directory and os.path.exists(skills_directory):
+        skills = load_skills_from_directory(skills_directory)
+        logger.info(f"Loaded {len(skills)} skills from {skills_directory}")
+    else:
+        skills = [
+            Skill(
+                id="gitlab_agent",
+                name="GitLab Agent",
+                description="This GitLab skill grants access to all GitLab tools provided by the GitLab MCP Server",
+                tags=["gitlab"],
+                input_modes=["text"],
+                output_modes=["text"],
+            )
+        ]
+    # Create A2A app explicitly before main app to bind lifespan
+    a2a_app = agent.to_a2a(
+        name=AGENT_NAME,
+        description=AGENT_DESCRIPTION,
+        version="25.14.5",
+        skills=skills,
+        debug=debug,
+    )
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        # Trigger A2A (sub-app) startup/shutdown events
+        # This is critical for TaskManager initialization in A2A
+        if hasattr(a2a_app, "router"):
+            async with a2a_app.router.lifespan_context(a2a_app):
+                yield
+        else:
+            yield
+
+    # Create main FastAPI app
+    app = FastAPI(
+        title=f"{AGENT_NAME} - A2A + AG-UI Server",
+        description=AGENT_DESCRIPTION,
+        debug=debug,
+        lifespan=lifespan,
+    )
+
+    # Mount A2A as sub-app at /a2a
+    app.mount("/a2a", a2a_app)
+
+    # Add AG-UI endpoint (POST to /ag-ui)
+    @app.post("/ag-ui")
+    async def ag_ui_endpoint(request: Request) -> Response:
+        accept = request.headers.get("accept", SSE_CONTENT_TYPE)
+        try:
+            # Parse incoming AG-UI RunAgentInput from request body
+            run_input = AGUIAdapter.build_run_input(await request.body())
+        except ValidationError as e:
+            return Response(
+                content=json.dumps(e.json()),
+                media_type="application/json",
+                status_code=422,
+            )
+
+        # Create adapter and run the agent → stream AG-UI events
+        adapter = AGUIAdapter(agent=agent, run_input=run_input, accept=accept)
+        event_stream = adapter.run_stream()  # Runs agent, yields events
+        sse_stream = adapter.encode_stream(event_stream)  # Encodes to SSE
+
+        return StreamingResponse(
+            sse_stream,
+            media_type=accept,
+        )
+
+    # Mount Web UI if enabled
+    if enable_web_ui:
+        web_ui = agent.to_web(instructions=AGENT_SYSTEM_PROMPT)
+        app.mount("/", web_ui)
+        logger.info(
+            "Starting server on %s:%s (A2A at /a2a, AG-UI at /ag-ui, Web UI: %s)",
+            host,
+            port,
+            "Enabled at /" if enable_web_ui else "Disabled",
+        )
+
+    uvicorn.run(
+        app,
+        host=host,
+        port=port,
+        timeout_keep_alive=1800,  # 30 minute timeout
+        timeout_graceful_shutdown=60,
+        log_level="debug" if debug else "info",
+    )
+
+
+def agent_server():
+    parser = argparse.ArgumentParser(
+        description=f"Run the {AGENT_NAME} A2A + AG-UI Server"
+    )
+    parser.add_argument(
+        "--host", default=DEFAULT_HOST, help="Host to bind the server to"
+    )
+    parser.add_argument(
+        "--port", type=int, default=DEFAULT_PORT, help="Port to bind the server to"
+    )
+    parser.add_argument("--debug", type=bool, default=DEFAULT_DEBUG, help="Debug mode")
+    parser.add_argument("--reload", action="store_true", help="Enable auto-reload")
+
+    parser.add_argument(
+        "--provider",
+        default=DEFAULT_PROVIDER,
+        choices=["openai", "anthropic", "google", "huggingface"],
+        help="LLM Provider",
+    )
+    parser.add_argument("--model-id", default=DEFAULT_MODEL_ID, help="LLM Model ID")
+    parser.add_argument(
+        "--base-url",
+        default=DEFAULT_OPENAI_BASE_URL,
+        help="LLM Base URL (for OpenAI compatible providers)",
+    )
+    parser.add_argument("--api-key", default=DEFAULT_OPENAI_API_KEY, help="LLM API Key")
+    parser.add_argument("--mcp-url", default=DEFAULT_MCP_URL, help="MCP Server URL")
+    parser.add_argument(
+        "--mcp-config", default=DEFAULT_MCP_CONFIG, help="MCP Server Config"
+    )
+    parser.add_argument(
+        "--web",
+        action="store_true",
+        default=DEFAULT_ENABLE_WEB_UI,
+        help="Enable Pydantic AI Web UI",
+    )
+    args = parser.parse_args()
+
+    if args.debug:
+        # Force reconfiguration of logging
+        for handler in logging.root.handlers[:]:
+            logging.root.removeHandler(handler)
+
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            handlers=[logging.StreamHandler()],  # Output to console
+            force=True,
+        )
+        logging.getLogger("pydantic_ai").setLevel(logging.DEBUG)
+        logging.getLogger("fastmcp").setLevel(logging.DEBUG)
+        logging.getLogger("httpcore").setLevel(logging.DEBUG)
+        logging.getLogger("httpx").setLevel(logging.DEBUG)
+        logger.setLevel(logging.DEBUG)
+        logger.debug("Debug mode enabled")
+
+    # Create the agent with CLI args
+    # Create the agent with CLI args
+    create_agent_server(
+        provider=args.provider,
+        model_id=args.model_id,
+        base_url=args.base_url,
+        api_key=args.api_key,
+        mcp_url=args.mcp_url,
+        mcp_config=args.mcp_config,
+        debug=args.debug,
+        host=args.host,
+        port=args.port,
+        enable_web_ui=args.web,
+    )
+
+
+if __name__ == "__main__":
+    agent_server()