Merge pull request #1 from gerlaxrex/feat/init

.gitignore

@@ -1,194 +1,11 @@
-# Byte-compiled / optimized / DLL files
+# Python-generated files
 __pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
+*.py[oc]
 build/
-develop-eggs/
 dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
 wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# UV
-#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#uv.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
+.idea/
+*.egg-info
 
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
-.pdm.toml
-.pdm-python
-.pdm-build/
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
+# Virtual environments
 .venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
-
-# Abstra
-# Abstra is an AI-powered process automation framework.
-# Ignore directories containing user credentials, local state, and settings.
-# Learn more at https://abstra.io/docs
-.abstra/
-
-# Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
-#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
-#  you could uncomment the following to ignore the enitre vscode folder
-# .vscode/
-
-# Ruff stuff:
-.ruff_cache/
-
-# PyPI configuration file
-.pypirc
-
-# Cursor
-#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
-#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
-#  refer to https://docs.cursor.com/context/ignore-files
-.cursorignore
-.cursorindexingignore

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.2.0
+    hooks:
+    - id: trailing-whitespace
+    - id: end-of-file-fixer
+    - id: check-yaml
+    - id: check-added-large-files
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.11.10
+    hooks:
+      # Run the linter.
+      - id: ruff-check
+        types_or: [ python, pyi ]
+        args: [ --fix ]
+      # Run the formatter.
+      - id: ruff-format
+        types_or: [ python, pyi ]

.python-version

@@ -0,0 +1 @@
+3.12

app.py

@@ -0,0 +1,271 @@
+import functools
+import os
+import uuid
+import asyncio
+import gradio as gr
+
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain_openai import ChatOpenAI
+from langgraph.prebuilt import ToolNode
+from langgraph.graph import MessagesState, END, StateGraph
+from langchain_core.messages import HumanMessage, SystemMessage, AIMessage
+from langgraph.checkpoint.memory import MemorySaver
+
+SYSTEM_PROMPT = """
+You are an assistant that can manage Trello boards and projects.
+You will be given a set of tools to work with. Each time you decide to use a tool that modifies in any way a Trello board, you MUST ask the user if wants to proceed.
+If the user's answer is negative, then you have to abort everything and end the conversation.
+"""
+
+
+class LangGraphAgent:
+    def __init__(self):
+        self.agent_app = None
+        self.config = {"configurable": {"thread_id": f"{str(uuid.uuid4())}"}}
+        self.memory = MemorySaver()
+
+    def reset_thread(self):
+        """Resets the conversation thread for the agent."""
+        self.config = {"configurable": {"thread_id": f"{str(uuid.uuid4())}"}}
+        print(
+            f"Chat thread reset. New Thread ID: {self.config['configurable']['thread_id']}"
+        )
+
+    async def setup(self):
+        print("Setting up LangGraphAgent...")
+        mcp_client = MultiServerMCPClient(
+            {
+                "trello": {
+                    "url": "http://localhost:8000/sse",
+                    "transport": "sse",
+                }
+            }
+        )
+
+        tools = await mcp_client.get_tools()
+        tool_node = ToolNode(tools)
+
+        # Ensure NEBIUS_API_KEY is set
+        api_key = os.getenv("NEBIUS_API_KEY")
+        if not api_key:
+            raise ValueError("NEBIUS_API_KEY environment variable not set.")
+
+        llm_with_tools = ChatOpenAI(
+            model="meta-llama/Meta-Llama-3.1-8B-Instruct",
+            temperature=0.0,
+            api_key=api_key,
+            base_url="https://api.studio.nebius.com/v1/",
+        )
+        llm_with_tools = llm_with_tools.bind_tools(tools)
+
+        async def call_llm(state: MessagesState):
+            response = await llm_with_tools.ainvoke(
+                state["messages"]
+            )  # Use await for async invoke
+            return {"messages": [response]}
+
+        graph = StateGraph(MessagesState)
+        graph.add_node("llm", functools.partial(call_llm))
+        graph.add_node("tool", tool_node)
+        graph.set_entry_point("llm")
+
+        def should_continue(state: MessagesState):
+            last_message = state["messages"][-1]
+            return (
+                "tool"
+                if hasattr(last_message, "tool_calls") and last_message.tool_calls
+                else END
+            )
+
+        graph.add_conditional_edges("llm", should_continue, {"tool": "tool", END: END})
+        graph.add_edge("tool", "llm")
+
+        self.agent_app = graph.compile(checkpointer=self.memory)
+        print("LangGraphAgent setup complete.")
+
+    async def generate_responses_for_turn(
+        self, user_message_text: str, is_first_turn_in_ui: bool
+    ) -> list[str]:
+        """
+        Generates a list of bot utterances for the current turn based on user input.
+        """
+        langgraph_input_messages = []
+        # The SYSTEM_PROMPT is added to the graph input only if it's the first UI interaction *and*
+        # the checkpointer implies it's the start of a new conversation for the thread_id.
+        # MemorySaver will handle loading history; system prompt is good for first message of a thread.
+
+        # Check current state in memory to decide if SystemMessage is truly needed
+        thread_state = await self.memory.aget(self.config)  # Use aget for async
+        is_new_thread_conversation = (
+            not thread_state
+            or not thread_state.get("values")
+            or not thread_state["values"]["messages"]
+        )
+
+        if is_new_thread_conversation:
+            print("Adding System Prompt for new conversation thread.")
+            langgraph_input_messages.append(
+                SystemMessage(content=SYSTEM_PROMPT.strip())
+            )
+
+        langgraph_input_messages.append(HumanMessage(content=user_message_text))
+
+        bot_responses_this_turn = []
+        processed_message_ids_in_stream = set()
+
+        async for result in self.agent_app.astream(
+            {"messages": langgraph_input_messages},
+            config=self.config,
+            stream_mode="values",
+        ):
+            if not result or "messages" not in result or not result["messages"]:
+                continue
+
+            latest_message_in_graph_state = result["messages"][-1]
+
+            if (
+                isinstance(latest_message_in_graph_state, AIMessage)
+                and latest_message_in_graph_state.id
+                not in processed_message_ids_in_stream
+            ):
+                current_ai_msg = latest_message_in_graph_state
+                # Add message ID to set of processed messages to avoid duplication from multiple stream events
+                # for the same underlying message object.
+                # However, AIMessages can be broken into chunks if streaming content.
+                # For now, with stream_mode="values", we get full messages.
+                # The id check is crucial if the same AIMessage object instance appears multiple times in the stream values.
+
+                newly_generated_content_for_this_step = []
+
+                # 1. Handle AIMessage content
+                if current_ai_msg.content:
+                    # Add content if it's new or different from the last added piece
+                    if (
+                        not bot_responses_this_turn
+                        or bot_responses_this_turn[-1] != current_ai_msg.content
+                    ):
+                        newly_generated_content_for_this_step.append(
+                            str(current_ai_msg.content)
+                        )
+
+                # 2. Handle tool calls
+                if hasattr(current_ai_msg, "tool_calls") and current_ai_msg.tool_calls:
+                    for tool_call in current_ai_msg.tool_calls:
+                        # Check if this specific tool call has been processed (e.g., by ID if available, or by content)
+                        # For simplicity, we assume each tool_call in a new AIMessage is distinct for now
+                        call_str = f"**Tool Call:** `{tool_call['name']}`\n*Arguments:* `{tool_call['args']}`"
+                        newly_generated_content_for_this_step.append(call_str)
+
+                if newly_generated_content_for_this_step:
+                    bot_responses_this_turn.extend(
+                        newly_generated_content_for_this_step
+                    )
+                    processed_message_ids_in_stream.add(
+                        current_ai_msg.id
+                    )  # Mark this AIMessage ID as processed
+
+        # Deduplicate consecutive identical messages that might arise from streaming nuances
+        final_bot_responses = []
+        if bot_responses_this_turn:
+            final_bot_responses.append(bot_responses_this_turn[0])
+            for i in range(1, len(bot_responses_this_turn)):
+                if bot_responses_this_turn[i] != bot_responses_this_turn[i - 1]:
+                    final_bot_responses.append(bot_responses_this_turn[i])
+
+        return final_bot_responses
+
+
+agent = LangGraphAgent()
+
+# Apply a theme
+theme = gr.themes.Soft(
+    primary_hue="blue", secondary_hue="sky", neutral_hue="slate"
+).set(
+    body_background_fill="linear-gradient(to right, #f0f4f8, #e6e9f0)",  # Light gradient background
+    block_background_fill="white",
+    block_border_width="1px",
+    block_shadow="*shadow_drop_lg",
+    button_primary_background_fill="*primary_500",
+    button_primary_text_color="white",
+    button_secondary_background_fill="*secondary_500",
+    button_secondary_text_color="white",
+)
+
+with gr.Blocks(theme=theme, title="Trello AI Assistant") as demo:
+    gr.Markdown(
+        """
+        # Trello AI Assistant
+        Manage your Trello boards and projects with AI assistance.
+        """
+    )
+
+    chatbot = gr.Chatbot(
+        label="Conversation",
+        bubble_full_width=False,
+        height=600,
+        avatar_images=(
+            None,
+            "https://upload.wikimedia.org/wikipedia/commons/thumb/7/72/Brandon_Sanderson_in_2018.jpg/800px-Brandon_Sanderson_in_2018.jpg?20230101015657",
+        ),
+        # (user_avatar, bot_avatar) - replace bot avatar with something better or remove
+    )
+
+    with gr.Row():
+        msg = gr.Textbox(
+            label="Your Message",
+            placeholder="Type your message here and press Enter to send...",
+            scale=4,  # Make textbox take more space
+            autofocus=True,
+        )
+        # submit_button = gr.Button("Send", variant="primary", scale=1) # Optional: if you want an explicit send button
+
+    clear_button = gr.Button("🗑️ Clear Chat & Reset Conversation")
+
+    async def respond(user_message_text, chat_history):
+        if not user_message_text.strip():
+            return (
+                chat_history,
+                "",
+            )  # Ignore empty input, return current history and clear textbox
+
+        is_first_turn = not chat_history
+
+        # Append user message to chat_history optimistically for immediate display
+        # Bot response will fill in the 'None' later or add new [None, bot_msg] rows
+        # This makes UI feel more responsive.
+        # chat_history.append([user_message_text, None]) # Temporarily removed for simpler logic below
+
+        ai_utterances = await agent.generate_responses_for_turn(
+            user_message_text, is_first_turn
+        )
+
+        if ai_utterances:
+            chat_history.append([user_message_text, ai_utterances[0]])
+            for i in range(1, len(ai_utterances)):
+                chat_history.append([None, ai_utterances[i]])
+        else:
+            # If agent provides no utterances (e.g. error or no action)
+            chat_history.append(
+                [user_message_text, "I don't have a response for that right now."]
+            )
+
+        return chat_history, ""  # Return updated history and clear the textbox
+
+    # Event handlers
+    msg.submit(respond, [msg, chatbot], [chatbot, msg])
+
+    # if submit_button: # If you add explicit send button
+    #     submit_button.click(respond, [msg, chatbot], [chatbot, msg])
+
+    def clear_chat_and_reset_agent():
+        agent.reset_thread()
+        return [], ""  # Clears chatbot UI and textbox
+
+    clear_button.click(clear_chat_and_reset_agent, None, [chatbot, msg], queue=False)
+
+    # Load agent setup when the app starts
+    # Using a lambda to ensure asyncio.run is called within the demo's event loop context if needed
+    demo.load(lambda: asyncio.run(agent.setup()))
+
+if __name__ == "__main__":
+    demo.launch()

main.py

@@ -0,0 +1,83 @@
+import os
+import pprint
+import uuid
+
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain_openai import ChatOpenAI
+from langgraph.prebuilt import ToolNode
+from langgraph.graph import MessagesState, END, StateGraph
+from langchain_core.messages import HumanMessage
+from langgraph.checkpoint.memory import MemorySaver
+
+from pmcp.agents.trello_agent import TrelloAgent
+
+
+async def call_llm(llm_with_tools: ChatOpenAI, state: MessagesState):
+    response = llm_with_tools.invoke(state["messages"])
+    return {"messages": [response]}
+
+
+async def main():
+    mcp_client = MultiServerMCPClient(
+        {
+            "trello": {
+                "url": "http://localhost:8000/sse",
+                "transport": "sse",
+            }
+        }
+    )
+
+    memory = MemorySaver()
+
+    tools = await mcp_client.get_tools()
+    tool_node = ToolNode(tools)
+    llm = ChatOpenAI(
+        model="meta-llama/Meta-Llama-3.1-8B-Instruct",
+        temperature=0.0,
+        api_key=os.getenv("NEBIUS_API_KEY"),
+        base_url="https://api.studio.nebius.com/v1/",
+    )
+
+    trello_agent = TrelloAgent(
+        tools=tools,
+        llm=llm,
+    )
+
+    graph = StateGraph(MessagesState)
+
+    graph.add_node("llm", trello_agent.acall_trello_agent)
+    graph.add_node("tool", tool_node)
+    graph.set_entry_point("llm")
+
+    def should_continue(state: MessagesState):
+        last_message = state["messages"][-1]
+        if last_message.tool_calls:
+            return "tool"
+        return END
+
+    graph.add_conditional_edges("llm", should_continue, {"tool": "tool", END: END})
+    graph.add_edge("tool", "llm")
+    app = graph.compile(checkpointer=memory)
+
+    user_input = input("user >")
+    config = {"configurable": {"thread_id": f"{str(uuid.uuid4())}"}}
+
+    while user_input.lower() != "q":
+        async for res in app.astream(
+            {
+                "messages": [
+                    HumanMessage(content=user_input),
+                ]
+            },
+            config=config,
+            stream_mode="values",
+        ):
+            pprint.pprint(res["messages"][-1])
+            pprint.pprint("-------------------------------------")
+        user_input = input("user >")
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(main())

pmcp/agents/agent_base.py

@@ -0,0 +1,64 @@
+import logging
+from typing import List, TypeVar, Optional
+
+from langchain_core.messages import AnyMessage, BaseMessage
+from pydantic import BaseModel
+from langchain_core.tools import BaseTool
+from langchain_openai import ChatOpenAI
+
+OutStruct = TypeVar(name="OutStruct", bound=BaseModel)
+
+
+class AgentBlueprint:
+    def __init__(
+        self,
+        agent_name: str,
+        *,
+        system_prompt: str = "",
+        tools: List[BaseTool] = None,
+        description: str = "",
+        base_url: Optional[str] = None,
+        llm: ChatOpenAI,
+    ):
+        self.agent_name = agent_name
+        self.system_prompt = system_prompt
+        self.llm = llm
+        self.agent_description = description
+        if tools:
+            self.llm = self.llm.bind_tools(tools)
+            self.tools = {tool.name: tool for tool in tools}
+        self.logger = logging.getLogger(self.__class__.__name__)
+
+    def call_agent(self, messages: List[AnyMessage]) -> BaseMessage:
+        response = self.llm.with_retry(stop_after_attempt=2).invoke(input=messages)
+        response.name = self.agent_name
+        return response
+
+    async def acall_agent(self, messages: List[AnyMessage]) -> BaseMessage:
+        response = await self.llm.with_retry(stop_after_attempt=2).ainvoke(
+            input=messages
+        )
+        response.name = self.agent_name
+        return response
+
+    def call_agent_structured(
+        self, messages: List[AnyMessage], clazz: OutStruct
+    ) -> OutStruct:
+        response = (
+            self.llm.with_structured_output(clazz)
+            .with_retry(stop_after_attempt=2)
+            .invoke(input=messages)
+        )
+
+        return response
+
+    async def acall_agent_structured(
+        self, messages: List[AnyMessage], clazz: OutStruct
+    ) -> OutStruct:
+        response = (
+            await self.llm.with_structured_output(clazz)
+            .with_retry(stop_after_attempt=2)
+            .ainvoke(input=messages)
+        )
+
+        return response

pmcp/agents/trello_agent.py

@@ -0,0 +1,36 @@
+from typing import List
+
+from pmcp.agents.agent_base import AgentBlueprint
+from langchain_core.tools import BaseTool
+from langchain_core.messages import SystemMessage
+from langchain_openai import ChatOpenAI
+from langgraph.graph import MessagesState
+
+SYSTEM_PROMPT = """
+You are an assistant that can manage Trello boards and projects.
+You will be given a set of tools to work with. Each time you decide to use a tool that modifies in any way a Trello board, you MUST ask the user if wants to proceed.
+If the user's answer is negative, then you have to abort everything and end the conversation.
+"""
+
+
+class TrelloAgent:
+    def __init__(self, tools: List[BaseTool], llm: ChatOpenAI):
+        self.__agent = AgentBlueprint(
+            agent_name="TRELLO_AGENT",
+            description="The agent that performs actions on Trello",
+            tools=tools,
+            system_prompt=SYSTEM_PROMPT.strip(),
+            llm=llm,
+        )
+
+    def call_trello_agent(self, state: MessagesState):
+        response = self.__agent.call_agent(
+            [SystemMessage(content=self.__agent.system_prompt)] + state.get("messages")
+        )
+        return {"messages": [response]}
+
+    async def acall_trello_agent(self, state: MessagesState):
+        response = await self.__agent.acall_agent(
+            [SystemMessage(content=self.__agent.system_prompt)] + state.get("messages")
+        )
+        return {"messages": [response]}

pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "pmcp"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "gradio[mcp]>=5.32.0",
+    "langchain-mcp-adapters>=0.1.1",
+    "langchain-openai>=0.3.18",
+    "langgraph>=0.4.7",
+    "langgraph-checkpoint-sqlite>=2.0.10",
+    "mcp>=1.9.0",
+    "smolagents[litellm,mcp,toolkit]>=1.17.0",
+]
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.2.0",
+    "ruff>=0.11.12",
+]