mtpx 0.1.0__tar.gz

mtpx-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: mtpx
+Version: 0.1.0
+Summary: MTPX: Model Tool Protocol and agent runtime for Python
+Author: MTPX Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/Godboy/MTP
+Project-URL: Documentation, https://github.com/Godboy/MTP/tree/main/docs
+Project-URL: Repository, https://github.com/Godboy/MTP
+Project-URL: Issues, https://github.com/Godboy/MTP/issues
+Keywords: agent,llm,ai,tool-orchestration,mcp,model-context-protocol,groq,openai
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# MTPX (Model Tool Protocol Extended)
+
+MTPX is a protocol-first Python library for agent tool orchestration, built to support:
+- Lazy tool loading by toolkit/category.
+- Dependency-aware batch tool execution.
+- Policy-aware execution based on tool risk.
+- Multi-round model-tool-model loops.
+- Provider adapters (now including Groq).
+- Transport primitives (stdio + HTTP envelope transport).
+- Experimental MCP JSON-RPC adapter over the same runtime core.
+
+## Quickstart
+
+## Install
+
+### From source (this repo)
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e .
+```
+
+### From PyPI (target usage)
+
+```bash
+pip install mtpx
+```
+
+### Provider SDKs and dotenv (install separately)
+
+```bash
+pip install groq
+pip install python-dotenv
+```
+
+Copy `.env.example` to `.env` and set your key:
+
+```env
+GROQ_API_KEY=your_groq_api_key_here
+```
+
+## Create an agent (local toolkits + Groq)
+
+```python
+from mtp import Agent
+from mtp.providers import Groq
+from mtp.toolkits import CalculatorToolkit, FileToolkit, PythonToolkit, ShellToolkit
+
+Agent.load_dotenv_if_available()
+
+tools = Agent.ToolRegistry()
+tools.register_toolkit_loader("calculator", CalculatorToolkit())
+tools.register_toolkit_loader("file", FileToolkit(base_dir="."))
+tools.register_toolkit_loader("python", PythonToolkit(base_dir="."))
+tools.register_toolkit_loader("shell", ShellToolkit(base_dir="."))
+
+provider = Groq(model="llama-3.3-70b-versatile")
+
+agent = Agent.MTPAgent(
+    provider=provider,
+    tools=tools,
+    instructions="Use tools when needed and return concise answers.",
+    debug_mode=True,
+    strict_dependency_mode=True,
+)
+response = agent.run("Calculate 25*4+10 and list files in current directory.", max_rounds=4)
+print(response)
+
+# Stream final response tokens:
+agent.print_response("Give me a short summary.", max_rounds=4, stream=True)
+
+# Stream structured runtime events (readable terminal logs by default):
+agent.print_response("Give me a short summary.", max_rounds=4, stream=True, stream_events=True)
+# Raw JSON lines:
+agent.print_response("Give me a short summary.", max_rounds=4, stream=True, stream_events=True, event_format="json")
+```
+
+## Persist conversation sessions (JSON database)
+
+```python
+from mtp import Agent, JsonSessionStore
+from mtp.providers import OpenAI
+
+session_store = JsonSessionStore(db_path="tmp/mtp_json_db")
+agent = Agent.MTPAgent(provider=OpenAI(model="gpt-4o"), tools=tools, session_store=session_store)
+
+agent.run("Remember this: project codename is Atlas.", session_id="chat-1", user_id="u1")
+agent.run("What is the project codename?", session_id="chat-1", user_id="u1")
+```
+
+PostgreSQL and MySQL session stores are also available:
+
+```python
+from mtp import PostgresSessionStore, MySQLSessionStore
+
+pg_store = PostgresSessionStore(db_url="postgresql://user:pass@localhost:5432/mtp")
+my_store = MySQLSessionStore(
+    host="localhost",
+    user="root",
+    password="secret",
+    database="mtp",
+    port=3306,
+)
+```
+
+## Run examples
+
+```bash
+python examples/quickstart.py
+python examples/groq_agent.py
+python examples/mcp_stdio_server.py
+```
+
+## Docs map
+- [Quickstart](docs/QUICKSTART.md)
+- [Agent API Reference](docs/AGENT_API.md)
+- [Storage and Sessions](docs/STORAGE.md)
+- [Providers](docs/PROVIDERS.md)
+- [Creating Tools](docs/CREATING_TOOLS.md)
+- [Events Contract](docs/EVENTS.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Protocol Spec](docs/PROTOCOL_SPEC.md)
+- [Local Toolkits](docs/LOCAL_TOOLKITS.md)
+- [Groq Integration](docs/GROQ_INTEGRATION.md)
+- [Transport](docs/TRANSPORT.md)
+- [MCP Interop Adapter](docs/MCP_INTEROP.md)
+- [Publishing](docs/PUBLISHING.md)
+
+## Repository structure
+- `src/mtp/protocol.py`: Core protocol entities (`ToolSpec`, `ToolCall`, `ExecutionPlan`, etc.).
+- `src/mtp/schema.py`: Versioned envelope + execution plan validation.
+- `src/mtp/policy.py`: Risk policy (`allow` / `ask` / `deny`).
+- `src/mtp/runtime.py`: Tool registry, lazy loading, caching, batch execution.
+- `src/mtp/agent.py`: Agent loop around provider + runtime.
+- `src/mtp/toolkits/`: Local toolkits (`calculator`, `file`, `python`, `shell`).
+- `src/mtp/transport/`: Envelope transport over stdio and HTTP.
+- `src/mtp/mcp.py`: MCP-compatible JSON-RPC adapter around `ToolRegistry`.
+- `src/mtp/providers/`: Provider adapters (`MockPlannerProvider` + OpenAI/Groq/OpenRouter/Gemini/Anthropic/SambaNova/Cerebras/DeepSeek/Mistral/Cohere/TogetherAI/FireworksAI).
+- `docs/`: documentation and implementation guides.

mtpx-0.1.0/README.md

@@ -0,0 +1,140 @@
+# MTPX (Model Tool Protocol Extended)
+
+MTPX is a protocol-first Python library for agent tool orchestration, built to support:
+- Lazy tool loading by toolkit/category.
+- Dependency-aware batch tool execution.
+- Policy-aware execution based on tool risk.
+- Multi-round model-tool-model loops.
+- Provider adapters (now including Groq).
+- Transport primitives (stdio + HTTP envelope transport).
+- Experimental MCP JSON-RPC adapter over the same runtime core.
+
+## Quickstart
+
+## Install
+
+### From source (this repo)
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e .
+```
+
+### From PyPI (target usage)
+
+```bash
+pip install mtpx
+```
+
+### Provider SDKs and dotenv (install separately)
+
+```bash
+pip install groq
+pip install python-dotenv
+```
+
+Copy `.env.example` to `.env` and set your key:
+
+```env
+GROQ_API_KEY=your_groq_api_key_here
+```
+
+## Create an agent (local toolkits + Groq)
+
+```python
+from mtp import Agent
+from mtp.providers import Groq
+from mtp.toolkits import CalculatorToolkit, FileToolkit, PythonToolkit, ShellToolkit
+
+Agent.load_dotenv_if_available()
+
+tools = Agent.ToolRegistry()
+tools.register_toolkit_loader("calculator", CalculatorToolkit())
+tools.register_toolkit_loader("file", FileToolkit(base_dir="."))
+tools.register_toolkit_loader("python", PythonToolkit(base_dir="."))
+tools.register_toolkit_loader("shell", ShellToolkit(base_dir="."))
+
+provider = Groq(model="llama-3.3-70b-versatile")
+
+agent = Agent.MTPAgent(
+    provider=provider,
+    tools=tools,
+    instructions="Use tools when needed and return concise answers.",
+    debug_mode=True,
+    strict_dependency_mode=True,
+)
+response = agent.run("Calculate 25*4+10 and list files in current directory.", max_rounds=4)
+print(response)
+
+# Stream final response tokens:
+agent.print_response("Give me a short summary.", max_rounds=4, stream=True)
+
+# Stream structured runtime events (readable terminal logs by default):
+agent.print_response("Give me a short summary.", max_rounds=4, stream=True, stream_events=True)
+# Raw JSON lines:
+agent.print_response("Give me a short summary.", max_rounds=4, stream=True, stream_events=True, event_format="json")
+```
+
+## Persist conversation sessions (JSON database)
+
+```python
+from mtp import Agent, JsonSessionStore
+from mtp.providers import OpenAI
+
+session_store = JsonSessionStore(db_path="tmp/mtp_json_db")
+agent = Agent.MTPAgent(provider=OpenAI(model="gpt-4o"), tools=tools, session_store=session_store)
+
+agent.run("Remember this: project codename is Atlas.", session_id="chat-1", user_id="u1")
+agent.run("What is the project codename?", session_id="chat-1", user_id="u1")
+```
+
+PostgreSQL and MySQL session stores are also available:
+
+```python
+from mtp import PostgresSessionStore, MySQLSessionStore
+
+pg_store = PostgresSessionStore(db_url="postgresql://user:pass@localhost:5432/mtp")
+my_store = MySQLSessionStore(
+    host="localhost",
+    user="root",
+    password="secret",
+    database="mtp",
+    port=3306,
+)
+```
+
+## Run examples
+
+```bash
+python examples/quickstart.py
+python examples/groq_agent.py
+python examples/mcp_stdio_server.py
+```
+
+## Docs map
+- [Quickstart](docs/QUICKSTART.md)
+- [Agent API Reference](docs/AGENT_API.md)
+- [Storage and Sessions](docs/STORAGE.md)
+- [Providers](docs/PROVIDERS.md)
+- [Creating Tools](docs/CREATING_TOOLS.md)
+- [Events Contract](docs/EVENTS.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Protocol Spec](docs/PROTOCOL_SPEC.md)
+- [Local Toolkits](docs/LOCAL_TOOLKITS.md)
+- [Groq Integration](docs/GROQ_INTEGRATION.md)
+- [Transport](docs/TRANSPORT.md)
+- [MCP Interop Adapter](docs/MCP_INTEROP.md)
+- [Publishing](docs/PUBLISHING.md)
+
+## Repository structure
+- `src/mtp/protocol.py`: Core protocol entities (`ToolSpec`, `ToolCall`, `ExecutionPlan`, etc.).
+- `src/mtp/schema.py`: Versioned envelope + execution plan validation.
+- `src/mtp/policy.py`: Risk policy (`allow` / `ask` / `deny`).
+- `src/mtp/runtime.py`: Tool registry, lazy loading, caching, batch execution.
+- `src/mtp/agent.py`: Agent loop around provider + runtime.
+- `src/mtp/toolkits/`: Local toolkits (`calculator`, `file`, `python`, `shell`).
+- `src/mtp/transport/`: Envelope transport over stdio and HTTP.
+- `src/mtp/mcp.py`: MCP-compatible JSON-RPC adapter around `ToolRegistry`.
+- `src/mtp/providers/`: Provider adapters (`MockPlannerProvider` + OpenAI/Groq/OpenRouter/Gemini/Anthropic/SambaNova/Cerebras/DeepSeek/Mistral/Cohere/TogetherAI/FireworksAI).
+- `docs/`: documentation and implementation guides.

mtpx-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mtpx"
+version = "0.1.0"
+description = "MTPX: Model Tool Protocol and agent runtime for Python"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "MTPX Contributors" }]
+keywords = ["agent", "llm", "ai", "tool-orchestration", "mcp", "model-context-protocol", "groq", "openai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Godboy/MTP"
+Documentation = "https://github.com/Godboy/MTP/tree/main/docs"
+Repository = "https://github.com/Godboy/MTP"
+Issues = "https://github.com/Godboy/MTP/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

mtpx-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mtpx-0.1.0/src/mtp/__init__.py

@@ -0,0 +1,132 @@
+from .events import EventStreamContext
+from .config import load_dotenv_if_available
+from .policy import PolicyDecision, RiskPolicy
+from .agent import Agent, AgentAction, ProviderAdapter, RunOutput
+from .session_store import (
+    JsonSessionStore,
+    MySQLSessionStore,
+    PostgresSessionStore,
+    SessionRecord,
+    SessionRun,
+    SessionStore,
+)
+from .exceptions import RetryAgentRun, StopAgentRun
+from .protocol import (
+    ExecutionPlan,
+    ToolOutput,
+    ToolBatch,
+    ToolCall,
+    ToolResult,
+    ToolRiskLevel,
+    ToolSpec,
+)
+from .media import Audio, File, Image, Video
+from .runtime import ExecutionCancelledError, ToolRegistry, ToolkitLoader, ToolRetryError, ToolStopError
+from .schema import (
+    CURRENT_MTP_VERSION,
+    MessageEnvelope,
+    ToolArgumentsValidationError,
+    validate_execution_plan,
+    validate_tool_arguments,
+)
+from .simple_agent import MTPAgent
+from .strict import StrictViolation, validate_strict_dependencies
+from .tools import FunctionToolkit, mtp_tool, tool_spec_from_callable, toolkit_from_functions
+from .toolkits import (
+    CalculatorToolkit,
+    Crawl4aiToolkit,
+    FileToolkit,
+    Newspaper4kToolkit,
+    NewspaperToolkit,
+    PythonToolkit,
+    ShellToolkit,
+    WebsiteToolkit,
+    WikipediaToolkit,
+    register_local_toolkits,
+)
+from .transport import HTTPTransportServer, run_stdio_transport
+from .mcp import MCPJsonRpcServer, MCPServerInfo, run_mcp_stdio
+
+# Convenience aliases for minimal import style:
+# from mtp import Agent
+# tools = Agent.ToolRegistry()
+# helper = Agent.MTPAgent(...)
+Agent.MTPAgent = MTPAgent
+Agent.ToolRegistry = ToolRegistry
+Agent.ToolkitLoader = ToolkitLoader
+Agent.ToolSpec = ToolSpec
+Agent.ToolRiskLevel = ToolRiskLevel
+Agent.Audio = Audio
+Agent.Image = Image
+Agent.Video = Video
+Agent.File = File
+Agent.mtp_tool = staticmethod(mtp_tool)
+Agent.tool_spec_from_callable = staticmethod(tool_spec_from_callable)
+Agent.FunctionToolkit = FunctionToolkit
+Agent.toolkit_from_functions = staticmethod(toolkit_from_functions)
+Agent.RetryAgentRun = RetryAgentRun
+Agent.StopAgentRun = StopAgentRun
+Agent.register_local_toolkits = staticmethod(register_local_toolkits)
+Agent.load_dotenv_if_available = staticmethod(load_dotenv_if_available)
+
+__all__ = [
+    "Agent",
+    "AgentAction",
+    "RunOutput",
+    "SessionStore",
+    "JsonSessionStore",
+    "PostgresSessionStore",
+    "MySQLSessionStore",
+    "SessionRecord",
+    "SessionRun",
+    "ExecutionPlan",
+    "CURRENT_MTP_VERSION",
+    "MTPAgent",
+    "EventStreamContext",
+    "mtp_tool",
+    "tool_spec_from_callable",
+    "FunctionToolkit",
+    "toolkit_from_functions",
+    "MessageEnvelope",
+    "ProviderAdapter",
+    "PolicyDecision",
+    "RiskPolicy",
+    "ToolBatch",
+    "ToolCall",
+    "ToolOutput",
+    "ToolRegistry",
+    "ExecutionCancelledError",
+    "ToolRetryError",
+    "ToolStopError",
+    "ToolResult",
+    "ToolRiskLevel",
+    "ToolSpec",
+    "Audio",
+    "Image",
+    "Video",
+    "File",
+    "ToolkitLoader",
+    "CalculatorToolkit",
+    "Crawl4aiToolkit",
+    "FileToolkit",
+    "NewspaperToolkit",
+    "Newspaper4kToolkit",
+    "PythonToolkit",
+    "ShellToolkit",
+    "WebsiteToolkit",
+    "WikipediaToolkit",
+    "register_local_toolkits",
+    "HTTPTransportServer",
+    "run_stdio_transport",
+    "MCPJsonRpcServer",
+    "MCPServerInfo",
+    "run_mcp_stdio",
+    "StrictViolation",
+    "validate_strict_dependencies",
+    "load_dotenv_if_available",
+    "validate_execution_plan",
+    "validate_tool_arguments",
+    "ToolArgumentsValidationError",
+    "RetryAgentRun",
+    "StopAgentRun",
+]