flowtic 1.6.0__tar.gz

flowtic-1.6.0/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env

flowtic-1.6.0/.python-version

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

flowtic-1.6.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: flowtic
+Version: 1.6.0
+Summary: A modern Python library for building multi-agent communication systems with LLM integration
+Project-URL: Homepage, https://github.com/PrAsAnNaRePo/Flowtic
+Project-URL: Repository, https://github.com/PrAsAnNaRePo/Flowtic
+Project-URL: Issues, https://github.com/PrAsAnNaRePo/Flowtic/issues
+Project-URL: Documentation, https://github.com/PrAsAnNaRePo/Flowtic#readme
+Author-email: PrAsAnNaRePo <prasannatwenty@gmail.com>
+Maintainer-email: PrAsAnNaRePo <prasannatwenty@gmail.com>
+License: MIT
+Keywords: agents,ai,communication,llm,multi-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.14,>=3.11
+Requires-Dist: litellm>=1.74.7
+Requires-Dist: pillow>=11.3.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=4.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Flowtic
+
+Build agent workflows that actually talk to each other. No complex orchestration, just simple communication patterns that work.
+
+## What it does
+
+- **Agent sessions**: Each agent keeps its own conversation history (text + images)
+- **Tool system**: Write functions once, agents use them automatically
+- **Communication graph**: Tell agents who can talk to whom with simple syntax
+- **Callbacks**: Hook into conversations for logging, user input, whatever you need
+
+## Install
+
+```bash
+pip install git+https://github.com/PrAsAnNaRePo/Flowtic.git
+```
+
+## Quick start
+
+### Single agent with tools
+
+```python
+from flowtic import Agent, Tool, Tools
+
+def calculate(expression: str):
+    return str(eval(expression)), None
+
+calc_tool = Tool(
+    tool_definition={
+        "type": "function",
+        "function": {
+            "name": "calculate", 
+            "description": "Calculate math expressions",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "expression": {"type": "string", "description": "Math expression"}
+                },
+                "required": ["expression"]
+            }
+        }
+    },
+    tool_execution=calculate
+)
+
+agent = Agent(
+    agent_name="calculator",
+    model_name="gpt-4o",  # any litellm model
+    instructions="You help with math problems.",
+    tools=Tools([calc_tool])
+)
+
+result = agent("What's 15 * 23?")
+```
+
+### Multi-agent workflow
+
+```python
+from flowtic import Agent, CommunicationProtocol
+
+# Create agents
+analyst = Agent(
+    agent_name="analyst",
+    model_name="gpt-4o",
+    instructions="Analyze requirements and ask clarifying questions.",
+    allow_user_input=True  # can talk to user
+)
+
+coder = Agent(
+    agent_name="coder", 
+    model_name="gpt-4o",
+    instructions="Write code based on requirements.",
+    allow_user_input=False  # only talks to other agents
+)
+
+# Set up who talks to whom
+protocol = CommunicationProtocol(
+    "analyst<->coder",  # bidirectional
+    [analyst, coder]
+)
+
+# Start the workflow
+protocol.execute("Build a simple todo app")
+```
+
+## Communication patterns
+
+The syntax is dead simple:
+
+- `A->B` means A can send messages to B
+- `A<->B` means they can talk both ways  
+- `A->B, B->C` chains them together
+- `A<->B, A->C` means A talks to both B and C
+
+When agents communicate, they automatically get tools to message each other. No setup needed.
+
+## Images and multimodal
+
+```python
+# Agent automatically handles images
+agent("Here's a screenshot", images=["path/to/image.png"])
+
+# Works with URLs and base64 too
+agent("Analyze this", images=["https://example.com/chart.png"])
+```
+
+## Custom callbacks
+
+```python
+from flowtic import Callback
+
+class MyCallbacks(Callback):
+    def on_user_loop(self, agent_name, message):
+        return input(f"{agent_name}: {message}\n> ")
+    
+    def on_tool_call(self, agent_name, tool_name, args):
+        print(f"{agent_name} is using {tool_name}")
+
+agent = Agent(
+    agent_name="helper",
+    model_name="gpt-4o", 
+    callbacks=MyCallbacks()
+)
+```
+
+## Session management
+
+Each agent keeps its own conversation buffer. Even if multiple agents reuse the same `SessionManager`, their histories stay isolated by agent name:
+
+```python
+from flowtic import SessionManager
+
+session_store = SessionManager()
+
+agent1 = Agent(
+    agent_name="researcher",
+    model_name="gpt-4o",
+    session=session_store
+)
+
+agent2 = Agent(
+    agent_name="writer", 
+    model_name="gpt-4o",
+    session=session_store
+)
+
+# The writer still has its own memory
+agent1("Find info about climate change")
+agent2("Write a summary based on what the researcher found")
+```
+
+If you want agents to share context, use agent-to-agent communication. `CommunicationProtocol` injects `_spin_into`, so one agent can explicitly hand context to another instead of silently sharing history.
+
+Sessions handle images automatically - no extra work needed:
+
+```python
+session = SessionManager()
+
+# Add context manually if needed
+session.add_user_context("my_agent", 
+    text="Here's the data", 
+    images=["chart1.png", "chart2.png"]
+)
+
+# Get the full conversation
+history = session.get_buffer_memory("my_agent")
+```
+
+## That's it
+
+Three main pieces: agents that remember conversations, tools they can use, and simple rules for who talks to whom. Everything else just works.

flowtic-1.6.0/README.md

@@ -0,0 +1,171 @@
+# Flowtic
+
+Build agent workflows that actually talk to each other. No complex orchestration, just simple communication patterns that work.
+
+## What it does
+
+- **Agent sessions**: Each agent keeps its own conversation history (text + images)
+- **Tool system**: Write functions once, agents use them automatically
+- **Communication graph**: Tell agents who can talk to whom with simple syntax
+- **Callbacks**: Hook into conversations for logging, user input, whatever you need
+
+## Install
+
+```bash
+pip install git+https://github.com/PrAsAnNaRePo/Flowtic.git
+```
+
+## Quick start
+
+### Single agent with tools
+
+```python
+from flowtic import Agent, Tool, Tools
+
+def calculate(expression: str):
+    return str(eval(expression)), None
+
+calc_tool = Tool(
+    tool_definition={
+        "type": "function",
+        "function": {
+            "name": "calculate", 
+            "description": "Calculate math expressions",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "expression": {"type": "string", "description": "Math expression"}
+                },
+                "required": ["expression"]
+            }
+        }
+    },
+    tool_execution=calculate
+)
+
+agent = Agent(
+    agent_name="calculator",
+    model_name="gpt-4o",  # any litellm model
+    instructions="You help with math problems.",
+    tools=Tools([calc_tool])
+)
+
+result = agent("What's 15 * 23?")
+```
+
+### Multi-agent workflow
+
+```python
+from flowtic import Agent, CommunicationProtocol
+
+# Create agents
+analyst = Agent(
+    agent_name="analyst",
+    model_name="gpt-4o",
+    instructions="Analyze requirements and ask clarifying questions.",
+    allow_user_input=True  # can talk to user
+)
+
+coder = Agent(
+    agent_name="coder", 
+    model_name="gpt-4o",
+    instructions="Write code based on requirements.",
+    allow_user_input=False  # only talks to other agents
+)
+
+# Set up who talks to whom
+protocol = CommunicationProtocol(
+    "analyst<->coder",  # bidirectional
+    [analyst, coder]
+)
+
+# Start the workflow
+protocol.execute("Build a simple todo app")
+```
+
+## Communication patterns
+
+The syntax is dead simple:
+
+- `A->B` means A can send messages to B
+- `A<->B` means they can talk both ways  
+- `A->B, B->C` chains them together
+- `A<->B, A->C` means A talks to both B and C
+
+When agents communicate, they automatically get tools to message each other. No setup needed.
+
+## Images and multimodal
+
+```python
+# Agent automatically handles images
+agent("Here's a screenshot", images=["path/to/image.png"])
+
+# Works with URLs and base64 too
+agent("Analyze this", images=["https://example.com/chart.png"])
+```
+
+## Custom callbacks
+
+```python
+from flowtic import Callback
+
+class MyCallbacks(Callback):
+    def on_user_loop(self, agent_name, message):
+        return input(f"{agent_name}: {message}\n> ")
+    
+    def on_tool_call(self, agent_name, tool_name, args):
+        print(f"{agent_name} is using {tool_name}")
+
+agent = Agent(
+    agent_name="helper",
+    model_name="gpt-4o", 
+    callbacks=MyCallbacks()
+)
+```
+
+## Session management
+
+Each agent keeps its own conversation buffer. Even if multiple agents reuse the same `SessionManager`, their histories stay isolated by agent name:
+
+```python
+from flowtic import SessionManager
+
+session_store = SessionManager()
+
+agent1 = Agent(
+    agent_name="researcher",
+    model_name="gpt-4o",
+    session=session_store
+)
+
+agent2 = Agent(
+    agent_name="writer", 
+    model_name="gpt-4o",
+    session=session_store
+)
+
+# The writer still has its own memory
+agent1("Find info about climate change")
+agent2("Write a summary based on what the researcher found")
+```
+
+If you want agents to share context, use agent-to-agent communication. `CommunicationProtocol` injects `_spin_into`, so one agent can explicitly hand context to another instead of silently sharing history.
+
+Sessions handle images automatically - no extra work needed:
+
+```python
+session = SessionManager()
+
+# Add context manually if needed
+session.add_user_context("my_agent", 
+    text="Here's the data", 
+    images=["chart1.png", "chart2.png"]
+)
+
+# Get the full conversation
+history = session.get_buffer_memory("my_agent")
+```
+
+## That's it
+
+Three main pieces: agents that remember conversations, tools they can use, and simple rules for who talks to whom. Everything else just works.

flowtic-1.6.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "flowtic"
+version = "1.6.0"
+description = "A modern Python library for building multi-agent communication systems with LLM integration"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "PrAsAnNaRePo", email = "prasannatwenty@gmail.com" }
+]
+maintainers = [
+    { name = "PrAsAnNaRePo", email = "prasannatwenty@gmail.com" }
+]
+requires-python = ">=3.11,<3.14"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+keywords = ["llm", "agents", "communication", "ai", "multi-agent"]
+dependencies = [
+    "litellm>=1.74.7",
+    "pillow>=11.3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/PrAsAnNaRePo/Flowtic"
+Repository = "https://github.com/PrAsAnNaRePo/Flowtic"
+Issues = "https://github.com/PrAsAnNaRePo/Flowtic/issues"
+Documentation = "https://github.com/PrAsAnNaRePo/Flowtic#readme"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.1.0",
+    "mypy>=1.8.0",
+    "twine>=4.0.0",
+    "build>=1.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/tests",
+    "/dist",
+    "/uv.lock",
+]

flowtic-1.6.0/src/flowtic/__init__.py

@@ -0,0 +1,14 @@
+from .agents import Agent
+from .agents.tools import Tool, Tools
+from .session import SessionManager
+from .communication import CommunicationProtocol
+from .communication.callbacks import Callback
+
+__all__ = [
+    "Agent",
+    "SessionManager",
+    "CommunicationProtocol",
+    "Callback",
+    "Tool",
+    "Tools",
+]

flowtic-1.6.0/src/flowtic/agents/__init__.py

@@ -0,0 +1,4 @@
+from .core import Agent, AsyncAgent
+from .tools import Tool, Tools
+
+__all__ = ['Agent', 'AsyncAgent', 'Tool', 'Tools']

flowtic-1.6.0/src/flowtic/agents/base.py

@@ -0,0 +1,141 @@
+from abc import ABC
+import inspect
+from typing import Any, Dict, Optional
+from flowtic.session import SessionManager
+from flowtic.agents.tools import Tool, Tools
+from litellm import completion, acompletion
+from flowtic.communication import Callback
+
+class AgentInterface(ABC):
+    def __init__(
+        self,
+        agent_name: str,
+        model_name: str,
+        instructions: str | None = "You are a helpful assistant.",
+        tools: Tools | None = None,
+        tool_choice: str | None = None,
+        session: Optional[SessionManager] = None,
+        *,
+        allow_user_input: bool = True,
+        max_turns: int = -1,
+        callbacks: Callback | None = None,
+        temperature: float = 1,
+        reasoning_effort=None,
+        verbose: bool = False
+    ):
+        self.agent_name = agent_name
+        self.model_name = model_name
+        self.instructions = instructions or "You are a helpful assistant."
+        self.tools = tools
+        self.tool_choice = tool_choice
+        self.session = session
+        self.allow_user_input = allow_user_input
+        self.max_turns = max_turns
+        self.callbacks = callbacks
+        self.temperature = temperature
+        self.reasoning_effort = reasoning_effort
+        self.verbose = verbose
+
+        if not self.session:
+            print("Session not provided, creating a new one...") if self.verbose else None 
+            self.session = SessionManager()
+        
+        if self.allow_user_input and self.callbacks is None:
+            raise ValueError("Callbacks should be provided if allow_user_input is True")
+
+        if not self.callbacks:
+            self.callbacks = Callback()
+        
+        if not self.allow_user_input:
+            print(f"Restricting user input to Agent {self.name}") if self.verbose else None 
+            self.instructions += '\nYou are STRICTLY NOT allowed to communicate to user directly, contact to any other agents if you are allowed to.'
+        
+        if self.agent_name:
+            self.instructions = f'\nYou are {self.agent_name}. ' + self.instructions
+
+        self._register_session()
+        self.session.add_sys_ins(self.name, self.instructions)
+    
+    @property
+    def name(self) -> str:
+        return self.agent_name
+    
+    def completion(self, **kwargs) -> Any:
+        return completion(
+                model=self.model_name,
+                messages=self.session.get_buffer_memory(tag=self.name),
+                tools=self.tools.get_definitions() if self.tools else None,
+                tool_choice=self.tool_choice if self.tools else None,
+                temperature=self.temperature,
+                reasoning_effort=self.reasoning_effort,
+                **kwargs
+            )
+
+    def acompletion(self, **kwargs) -> Any:
+        return acompletion(
+                model=self.model_name,
+                messages=self.session.get_buffer_memory(tag=self.name),
+                tools=self.tools.get_definitions() if self.tools else None,
+                tool_choice=self.tool_choice if self.tools else None,
+                temperature=self.temperature,
+                reasoning_effort=self.reasoning_effort,
+                **kwargs
+            )
+    
+    def _register_session(self) -> None:
+        self.session._register_buffer(self.name)
+    
+    def add_context(
+        self,
+        input: Optional[Dict[str, Any]] = None,
+        assistant_output: Optional[Any] = None,
+        tool_output: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        if input:
+            self.session.add_user_context(self.name, **input)
+        elif assistant_output:
+            self.session.add_assistant_context(self.name, assistant_output)
+        elif tool_output:
+            self.session.add_tool_context(self.name, **tool_output)
+        else:
+            raise ValueError("No input provided")
+    
+    def add_tool(self, tool: Tool) -> None:
+        if not self.tools:
+            self.tools = Tools([tool])
+        else:
+            self.tools.register_tool(tool)
+
+    def _call_user_loop(self, assistant_message: str):
+        method = self.callbacks.on_user_loop
+        signature = inspect.signature(method)
+        positional_params = [
+            parameter
+            for parameter in signature.parameters.values()
+            if parameter.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+        ]
+
+        if any(parameter.kind == inspect.Parameter.VAR_POSITIONAL for parameter in signature.parameters.values()):
+            return method(self.name, assistant_message)
+
+        if len(positional_params) <= 1:
+            return method(assistant_message)
+
+        return method(self.name, assistant_message)
+
+    def _call_tool_callback(self, function_name: str, arguments: Dict[str, Any]):
+        method = self.callbacks.on_tool_call
+        signature = inspect.signature(method)
+        positional_params = [
+            parameter
+            for parameter in signature.parameters.values()
+            if parameter.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+        ]
+
+        if any(parameter.kind == inspect.Parameter.VAR_POSITIONAL for parameter in signature.parameters.values()):
+            return method(self.name, function_name, arguments)
+
+        if len(positional_params) <= 2:
+            return method(function_name, arguments)
+
+        return method(self.name, function_name, arguments)

flowtic-1.6.0/src/flowtic/agents/core.py

@@ -0,0 +1,226 @@
+import asyncio
+import json
+from typing import Any, List, Optional
+
+from flowtic.agents.base import AgentInterface
+
+
+def _message_content_to_text(content: Any) -> Optional[str]:
+    if content is None:
+        return None
+
+    if isinstance(content, str):
+        return content
+
+    if isinstance(content, list):
+        text_parts = []
+        for item in content:
+            if isinstance(item, dict) and item.get("type") == "text":
+                text_parts.append(item.get("text", ""))
+        text_output = "\n".join(part for part in text_parts if part)
+        return text_output or str(content)
+
+    return str(content)
+
+class Agent(AgentInterface):
+    def __init__(self, **kwargs):
+        """
+        Initialize the agent.
+
+        Args:
+            model_name (str): The litellm compatible model name.
+            instructions (str | None, optional): The instructions for the agent. Defaults to "You are a helpful assistant."
+            tools (Optional[List], optional): The tools to execute for the agent. Defaults to None.
+            tool_choice (str, optional): The tool choice for the agent. Defaults to "none".
+            session (Optional[SessionManager], optional): The session for the agent to keep context. Defaults to None.
+            allow_user_input (bool, optional): Whether to allow the model to take user input. Defaults to True.
+            max_turns (int, optional): The maximum number of turns. Defaults to -1 (unlimited).
+        """
+        super().__init__(**kwargs)
+    
+    def __call__(self, input: str, images: Optional[List] = None):
+        """
+        call the agent
+
+        Args:
+            input (str): The input to the agent.
+            images (Optional[List], optional): List of images as a local file path or url or base64 encoded string. Defaults to None.
+        """
+
+        if self.verbose:
+            print(f">> Staring {self.name} agent execution")
+
+        self.add_context(input={'text': input, 'images': images})
+        
+        turn_count = 0
+        final_output = None
+        while True:
+            if self.max_turns > 0 and turn_count >= self.max_turns:
+                break
+                
+            response = self.completion()
+            response_message = response.choices[0].message
+            self.add_context(assistant_output=response_message)
+            turn_count += 1
+            message_text = _message_content_to_text(response_message.content)
+            if message_text is not None:
+                final_output = message_text
+
+            tool_calls = response_message.tool_calls or []
+
+            if tool_calls:
+                communication_occurred = False
+                for tool_call in tool_calls:
+                    function_name = tool_call.function.name
+                    function_args = json.loads(tool_call.function.arguments)
+                    self._call_tool_callback(function_name, function_args)
+                    if function_name == '_spin_into':
+                        tool_output = self.tools.get_callable(function_name)(self.name, **function_args)
+                        communication_occurred = True
+                    else:
+                        tool_output = self.tools.get_callable(function_name)(**function_args)
+
+                    assert isinstance(tool_output, tuple), "Tool output should return a tuple of (text, images (none if no images))"
+                    if tool_output[0] is not None:
+                        final_output = str(tool_output[0])
+
+                    self.add_context(tool_output={'fn_name': function_name, 'tool_call_id': tool_call.id, 'output': str(tool_output[0])})
+                    if tool_output[1]:
+                        self.add_context(input={'text': 'Here are the tool output images:\n', 'images': tool_output[1] \
+                            if isinstance(tool_output[1], list) else [tool_output[1]]})
+                
+                # If agent communicated to another agent and doesn't allow user input, stop
+                if communication_occurred and not self.allow_user_input:
+                    break
+                    
+            else:
+                if self.allow_user_input:
+                    try:
+                        user_input = self._call_user_loop(message_text or "")
+                        self.add_context(input={'text': user_input})
+                    except NotImplementedError:
+                        break
+                else:
+                    break
+
+        return final_output
+
+
+class AsyncAgent(AgentInterface):
+    def __init__(self, **kwargs):
+        """
+        Initialize the asyncronous agent.
+
+        Args:
+            model_name (str): The litellm compatible model name.
+            instructions (str | None, optional): The instructions for the agent. Defaults to "You are a helpful assistant."
+            tools (Optional[List], optional): The tools to execute for the agent. Defaults to None.
+            tool_choice (str, optional): The tool choice for the agent. Defaults to "none".
+            session (Optional[SessionManager], optional): The session for the agent to keep context. Defaults to None.
+            allow_user_input (bool, optional): Whether to allow the model to take user input. Defaults to True.
+            max_turns (int, optional): The maximum number of turns. Defaults to -1 (unlimited).
+        """
+        super().__init__(**kwargs)
+
+    async def run_async_or_sync(self, func, *args, **kwargs):
+        result = func(*args, **kwargs)
+        if asyncio.iscoroutine(result):
+            return await result
+        return result 
+
+    async def __call__(self, input: str, images: Optional[List] = None):
+        """
+        call the agent
+
+        Args:
+            input (str): The input to the agent.
+            images (Optional[List], optional): List of images as a local file path or url or base64 encoded string. Defaults to None.
+        """
+
+        if self.verbose:
+            print(f">> Staring {self.name} agent execution")
+
+        self.add_context(input={'text': input, 'images': images})
+        
+        turn_count = 0
+        final_output = None
+        while True:
+            if self.max_turns > 0 and turn_count >= self.max_turns:
+                break
+            if self.verbose: 
+                print("Session Buffer:")
+                print(self.session.get_buffer_memory(self.name))
+
+            response = await self.acompletion()
+            response_message = response.choices[0].message
+            
+            if self.verbose:
+                print(response_message)
+
+            self.add_context(assistant_output=response_message)
+            turn_count += 1
+            message_text = _message_content_to_text(response_message.content)
+            if message_text is not None:
+                final_output = message_text
+
+            tool_calls = response_message.tool_calls or []
+
+            if tool_calls:
+                communication_occurred = False
+
+                tasks = []
+                tool_metadata = []
+                for tool_call in tool_calls:
+                    callable_func = self.tools.get_callable(tool_call.function.name)
+                    args = json.loads(tool_call.function.arguments)
+                    self._call_tool_callback(tool_call.function.name, args)
+
+                    if tool_call.function.name == '_async_spin_into':
+                        communication_occurred = True
+                        task = asyncio.create_task(self.run_async_or_sync(callable_func, self.name, **args))
+                    else:
+                        task = asyncio.create_task(self.run_async_or_sync(callable_func, **args))
+
+                    tasks.append(task)
+                    tool_metadata.append({
+                        'function_name': tool_call.function.name,
+                        'tool_call': tool_call
+                    })
+
+                tool_outputs = await asyncio.gather(*tasks)
+
+                for tool_output, metadata in zip(tool_outputs, tool_metadata):
+                    if self.verbose:
+                        print("TOOL OUTPUT: ")
+                        print(tool_output)
+
+                    # if metadata['function_name'] != '_async_spin_into':
+                    assert isinstance(tool_output, tuple), "Tool output should return a tuple of (text, images (none if no images))"
+                    if tool_output[0] is not None:
+                        final_output = str(tool_output[0])
+                    self.add_context(tool_output={
+                        'fn_name': metadata['function_name'],
+                        'tool_call_id': metadata['tool_call'].id,
+                        'output': str(tool_output[0])
+                    })
+
+                    if tool_output[1]:
+                        self.add_context(input={'text': 'Here are the tool output images:\n', 'images': tool_output[1] \
+                            if isinstance(tool_output[1], list) else [tool_output[1]]})
+                
+                # If agent communicated to another agent and doesn't allow user input, stop
+                if communication_occurred and not self.allow_user_input:
+                    break
+                    
+            else:
+                if self.allow_user_input:
+                    try:
+                        user_input = self._call_user_loop(message_text or "")
+                        self.add_context(input={'text': user_input})
+                    except NotImplementedError:
+                        break
+                else:
+                    break
+
+        return final_output
+

flowtic-1.6.0/src/flowtic/agents/tools.py

@@ -0,0 +1,40 @@
+from typing import Dict, Callable, List
+
+class Tool():
+    def __init__(
+        self,
+        tool_definition: Dict,
+        tool_execution: Callable,
+    ) -> None:
+        self.tool_definition = tool_definition
+        self.tool_execution = tool_execution
+
+        assert tool_definition['function']['name'] == tool_execution.__name__, "Tool name mismatch"
+
+    def get_name(self) -> str:
+        return self.tool_definition['function']['name']
+
+class Tools():
+    def __init__(
+        self,
+        tools: List[Tool]
+    ):
+        self.tools = tools
+        self._map = None
+        self._create_map()
+    
+    def _create_map(self):
+        self._map = {tool.get_name(): tool.tool_execution for tool in self.tools}
+    
+    def get_callable(self, tool_name: str) -> Callable:
+        if tool_name not in self._map:
+            raise ValueError(f"Tool {tool_name} not found")
+        return self._map[tool_name]
+    
+    def get_definitions(self) -> List[Dict]:
+        return [tool.tool_definition for tool in self.tools]
+    
+    def register_tool(self, tool: Tool) -> None:
+        self.tools = [existing_tool for existing_tool in self.tools if existing_tool.get_name() != tool.get_name()]
+        self.tools.append(tool)
+        self._create_map()

flowtic-1.6.0/src/flowtic/communication/__init__.py

@@ -0,0 +1,4 @@
+from .callbacks import Callback
+from .channel import CommunicationProtocol
+
+__all__ = ['Callback', 'CommunicationProtocol']

flowtic-1.6.0/src/flowtic/communication/callbacks.py

@@ -0,0 +1,11 @@
+from typing import Dict, Any
+
+class Callback:
+    def __init__(self) -> None:
+        pass
+
+    def on_user_loop(self, agent_name: str, assistant_message: str):
+        raise NotImplementedError
+
+    def on_tool_call(self, agent_name: str, fn_name: str, arguments: Dict[str, Any]):
+        return None

flowtic-1.6.0/src/flowtic/communication/channel/__init__.py

@@ -0,0 +1 @@
+from .core import CommunicationProtocol as CommunicationProtocol

flowtic-1.6.0/src/flowtic/communication/channel/core.py

@@ -0,0 +1,222 @@
+from typing import List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from flowtic.agents import Agent
+import re
+from collections import defaultdict
+from flowtic.agents.tools import Tool
+
+class CommunicationProtocol:
+    def __init__(
+        self,
+        logic_str: str,
+        agents: List['Agent'],
+        async_run_type = False,
+        *,
+        verbose: bool = False,
+    ) -> None:
+        self.logic_str = logic_str
+        self.agents = agents
+        self.verbose = verbose
+        
+        self.mapping = self._parse_communication(logic_str)
+        if not self.mapping:
+            raise ValueError("Communication protocol cannot be empty")
+        
+        self.async_run_type = async_run_type
+        self.agent_map = {agents[i].name: agents[i] for i in range(len(agents))}
+        self._communication_validation()
+        if self.verbose:
+            self.print_graph_as_tree()
+        for item in self.mapping.items():
+            self._inject_handsoff(item[0], item[1])
+
+
+    def _parse_communication(self, sequence: str):
+        pattern = re.compile(r'\s*(\w+)\s*(<->|->)\s*(\w+)\s*')
+        graph = defaultdict(list)
+
+        for fragment in sequence.split(','):
+            m = pattern.fullmatch(fragment.strip())
+            if not m:
+                raise ValueError(f"Un-parsable fragment: {fragment!r}")
+            src, arrow, dst = m.groups()
+
+            graph[src].append(dst)
+            if arrow == '<->':
+                graph[dst].append(src)
+
+        return {n: list(dict.fromkeys(neigh)) for n, neigh in graph.items()}
+    
+    def parse_agents(self):
+        agents = []
+        agents.extend(list(self.mapping.keys()))
+        _vals = [j for i in list(self.mapping.values()) for j in i]
+        agents.extend(_vals)
+        return list(dict.fromkeys(agents))
+    
+    def _communication_validation(self):
+        protocol_agents = set(self.parse_agents())
+        provided_agents = set(self.agent_map)
+
+        if protocol_agents != provided_agents:
+            missing_agents = sorted(protocol_agents - provided_agents)
+            extra_agents = sorted(provided_agents - protocol_agents)
+            errors = []
+            if missing_agents:
+                errors.append(f"Missing agents: {missing_agents}")
+            if extra_agents:
+                errors.append(f"Unexpected agents: {extra_agents}")
+            raise ValueError(". ".join(errors))            
+
+    def print_graph_as_tree(self):
+        targets = {t for vals in self.mapping.values() for t in vals}
+        roots   = [n for n in self.mapping if n not in targets] or list(self.mapping.keys())
+
+        def dfs(node, prefix="", visited=None, is_last=True):
+            if visited is None:
+                visited = set()
+            looped = node in visited
+            branch = "└── " if is_last else "├── "
+            print(prefix + branch + node + (" (↺)" if looped else ""))
+            if looped:
+                return
+            visited.add(node)
+
+            children = self.mapping.get(node, [])
+            for i, child in enumerate(children):
+                dfs(child,
+                    prefix + ("    " if is_last else "│   "),
+                    visited,
+                    i == len(children) - 1)
+
+        visited = set()
+        for i, root in enumerate(roots):
+            dfs(root, "", visited, i == len(roots) - 1)
+            if i != len(roots) - 1:
+                print()
+
+    def get_connected_agents(self, agent_name: str):
+        return self.mapping.get(agent_name, [])
+
+    def _format_handoff_message(self, sender: str, receiver: str, message: str, context: str) -> str:
+        prefix = f"Hey {receiver}, It's {sender} here (not the user, don't get confused)."
+        cleaned_context = context.strip()
+        cleaned_message = message.strip()
+
+        if cleaned_context:
+            return f"{prefix} {cleaned_context}\n\n{cleaned_message}"
+
+        return f"{prefix}\n\n{cleaned_message}"
+
+    def _validate_receiver(self, sender: str, receiver: str) -> None:
+        allowed_receivers = self.get_connected_agents(sender)
+        if receiver not in allowed_receivers:
+            raise ValueError(f"Agent {sender} cannot communicate with {receiver}. Allowed receivers: {allowed_receivers}")
+    
+    def _inject_handsoff(self, agent: str, recievers: List[str]):
+        self.agent_map.get(agent).add_tool(
+            Tool(
+                tool_definition={
+                    "type": "function",
+                    "function": {
+                        "name": f"{self._async_spin_into.__name__ if self.async_run_type else self._spin_into.__name__}",
+                        "description": "Use this tool to communicate with other agents",
+                        "parameters": {
+                            "type": "object",
+                            "properties": {
+                                "receiver": {
+                                    "type": "string",
+                                    "description": f"you must have to mention receiver name clearly as it is. Only allowed to {','.join([i for i in recievers])}",
+                                },
+                                "message": {
+                                    "type": "string",
+                                    "description": "This includes the main task, goal or whatever the important information you want to pass to the receiver",
+                                },
+                                "context": {
+                                    "type": "string",
+                                    "description": "This includes the additional context, your reasoning, etc. of the conversation so far",
+                                },
+                            },
+                            "required": ["receiver", "message", "context"],
+                        },
+                    },
+                },
+                tool_execution=self._async_spin_into if self.async_run_type else self._spin_into,
+                )
+        )
+
+    def _collect_output(self, messages):
+        output_parts = []
+
+        for msg in messages:
+            if isinstance(msg, dict) and msg.get('role') == 'tool':
+                content = msg.get('content', '')
+                if content and content != 'None':
+                    output_parts.append(content)
+            elif hasattr(msg, 'role') and msg.role == 'assistant' and msg.content:
+                output_parts.append(msg.content)
+
+        if output_parts:
+            return output_parts[-1]
+
+        return None
+
+    def _spin_up(self, agent_name: str, input: str, images: Optional[List] = None):
+        agent = self.agent_map.get(agent_name)
+        if agent is None:
+            raise ValueError(f"No agent found called {agent_name}")
+        
+        original_buffer = agent.session.get_buffer_memory(tag=agent.name)
+        original_length = len(original_buffer)
+        
+        output = agent(input, images=images)
+        if output is not None:
+            return output
+        
+        updated_buffer = agent.session.get_buffer_memory(tag=agent.name)
+        new_messages = updated_buffer[original_length:]
+
+        return self._collect_output(new_messages) or f"{agent_name} completed the request"
+
+    async def _async_spin_up(self, agent_name: str, input: str, images: Optional[List] = None):
+        agent = self.agent_map.get(agent_name)
+
+        if agent is None:
+            raise ValueError(f"No agent found called {agent_name}")
+
+        original_buffer = agent.session.get_buffer_memory(tag=agent.name)
+        original_length = len(original_buffer)
+
+        output = await agent(input, images=images)
+        if output is not None:
+            return output
+
+        updated_buffer = agent.session.get_buffer_memory(tag=agent.name)
+        new_messages = updated_buffer[original_length:]
+
+        return self._collect_output(new_messages) or f"{agent_name} completed the request"
+        
+    def _spin_into(self, sender: str, receiver: str, message: str, context: str):
+        self._validate_receiver(sender, receiver)
+        return self._spin_up(receiver, self._format_handoff_message(sender, receiver, message, context)), None
+
+    async def _async_spin_into(self, sender: str, receiver: str, message: str, context: str):
+        self._validate_receiver(sender, receiver)
+        return await self._async_spin_up(
+            receiver,
+            self._format_handoff_message(sender, receiver, message, context),
+        ), None
+
+    def execute(self, input: str, images: Optional[List] = None, start_agent: Optional[str] = None):
+        prior_agent_name = start_agent or list(self.mapping.keys())[0]
+
+        return self._spin_up(prior_agent_name, input, images=images)
+
+    async def async_execute(self, input: str, images: Optional[List] = None, start_agent: Optional[str] = None):
+        prior_agent_name = start_agent or list(self.mapping.keys())[0]
+
+        return await self._async_spin_up(prior_agent_name, input, images=images)
+
+    async def asyn_execute(self, input: str, images: Optional[List] = None, start_agent: Optional[str] = None):
+        return await self.async_execute(input, images=images, start_agent=start_agent)

flowtic-1.6.0/src/flowtic/session/__init__.py

@@ -0,0 +1 @@
+from .core import SessionManager as SessionManager

flowtic-1.6.0/src/flowtic/session/base.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, List, Optional
+
+class SessionInterface(ABC):
+    def __init__(self, ctx_size: int = 4):
+        self._buffer_memory = dict()
+        self._ctx_size = ctx_size
+
+    @property
+    def ctx_size(self) -> int:
+        return self._ctx_size
+    
+    @ctx_size.setter
+    def ctx_size(self, value: int):
+        self._ctx_size = value
+    
+    def get_buffer_memory(self, tag: str) -> List:
+        return self._buffer_memory[tag]
+    
+    def add_sys_ins(self, tag: str, instruction: str):
+        self._buffer_memory[tag].append(
+            {
+                'role': 'system',
+                'content': instruction
+            }
+        )
+
+    @abstractmethod
+    def add_user_context(self, tag: str, text: Optional[str] = None, images: Optional[List] = None): ...
+    
+    @abstractmethod
+    def add_assistant_context(self, tag: str, ass_out: Any): ...
+    
+    @abstractmethod
+    def add_tool_context(self, tag: str, fn_name: str, tool_call_id: str, output: Any): ...
+
+    def _register_buffer(self, tag: str):
+        if tag not in self._buffer_memory:
+            self._buffer_memory[tag] = []
+        else:
+            raise ValueError(f"Tag {tag} already exists")

flowtic-1.6.0/src/flowtic/session/core.py

@@ -0,0 +1,101 @@
+import base64
+import binascii
+import io
+import mimetypes
+import os
+from typing import Any, List, Optional
+
+from PIL import Image
+
+from flowtic.session.base import SessionInterface
+
+class SessionManager(SessionInterface):
+    def __init__(self, *args, **kwargs): 
+        super().__init__(*args, **kwargs)
+    
+    def _encode_image_bytes(self, image_bytes: bytes, mime_type: str) -> str:
+        encoded = base64.b64encode(image_bytes).decode("utf-8")
+        return f"data:{mime_type};base64,{encoded}"
+
+    def _handle_image(self, image: Any):
+        if isinstance(image, Image.Image):
+            buffered = io.BytesIO()
+            image_format = (image.format or "PNG").upper()
+            image.save(buffered, format=image_format)
+            return self._encode_image_bytes(buffered.getvalue(), f"image/{image_format.lower()}")
+
+        if isinstance(image, bytes):
+            return self._encode_image_bytes(image, "image/jpeg")
+
+        if not isinstance(image, str):
+            raise TypeError("Images must be file paths, URLs, base64 strings, bytes, or PIL images")
+
+        normalized_image = image.strip()
+
+        if normalized_image.startswith(("http://", "https://", "data:image/")):
+            return normalized_image
+
+        if os.path.exists(normalized_image):
+            mime_type = mimetypes.guess_type(normalized_image)[0] or "image/jpeg"
+            with open(normalized_image, "rb") as file_handle:
+                return self._encode_image_bytes(file_handle.read(), mime_type)
+
+        try:
+            base64.b64decode(normalized_image, validate=True)
+        except (binascii.Error, ValueError) as exc:
+            raise ValueError(
+                "Images must be valid local paths, URLs, data URLs, or raw base64 strings"
+            ) from exc
+
+        return f"data:image/jpeg;base64,{normalized_image}"
+            
+    def add_user_context(self, tag: str, text: Optional[str] = None, images: Optional[List] = None):
+        if text and images:
+            self._buffer_memory[tag].append(
+                {
+                    'role': 'user',
+                    'content':[
+                        {'type': 'text', 'text': text},
+                    ]
+                }
+            )
+            for img in images:
+                self._buffer_memory[tag][-1]['content'].append(
+                    {'type': 'image_url', 'image_url': {'url': self._handle_image(img)}}
+                )
+
+        elif text:
+            self._buffer_memory[tag].append(
+                {
+                    'role': 'user',
+                    'content':[
+                        {'type': 'text', 'text': text},
+                    ]
+                }
+            )
+        elif images:
+            self._buffer_memory[tag].append(
+                {
+                    'role': 'user',
+                    'content':[
+                        {'type': 'image_url', 'image_url': {'url': self._handle_image(img)}} for img in images
+                    ]
+                }
+            )
+        else:
+            raise ValueError("No input provided")
+    
+    def add_assistant_context(self, tag: str, ass_out: Any):
+        self._buffer_memory[tag].append(
+            ass_out
+        )
+    
+    def add_tool_context(self, tag: str, fn_name, tool_call_id, output):
+        self._buffer_memory[tag].append(
+            {
+                'tool_call_id': tool_call_id,
+                'role': 'tool',
+                'name': fn_name,
+                'content': output
+            }
+        )