matimo-core

Matimo core — framework-agnostic SDK with pre-built providers, skills layer, MCP, and a policy engine you control.

Write tools once in YAML, use them everywhere — with LangChain, CrewAI, MCP, and more.

Note: Most users should install matimo (the convenience wrapper) instead of matimo-core directly.

Installation

pip install matimo-core
# with framework extras
pip install "matimo-core[langchain]"
pip install "matimo-core[crewai]"
pip install "matimo-core[mcp]"
pip install "matimo-core[langchain,crewai,mcp]"

Quick Start

Factory pattern

import asyncio
from matimo import Matimo

async def main():
    # Load tools from a directory
    matimo = await Matimo.init('./tools')
    result = await matimo.execute('my_tool', {'param': 'value'})
    print(result)

asyncio.run(main())

Auto-discover installed providers

from matimo import Matimo

matimo = await Matimo.init(auto_discover=True)
tools = matimo.list_tools()
print(f"{len(tools)} tools loaded")

Decorator pattern

from matimo import Matimo, tool, set_global_matimo_instance

matimo = await Matimo.init('./tools')
set_global_matimo_instance(matimo)

class MyAgent:
    @tool('slack_send_channel_message')
    async def send_message(self, channel: str, text: str): ...
    # Decorator handles execution automatically

LangChain

from matimo import Matimo
from matimo.integrations.langchain import convert_tools_to_langchain
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate

matimo = await Matimo.init(auto_discover=True)
lc_tools = convert_tools_to_langchain(
    matimo.list_tools(),
    matimo,
    credentials={'SLACK_BOT_TOKEN': 'xoxb-...'},
)
llm = ChatOpenAI(model='gpt-4o-mini')
prompt = ChatPromptTemplate.from_messages([
    ('system', 'You are a helpful assistant.'),
    ('human', '{input}'),
    ('placeholder', '{agent_scratchpad}'),
])
agent = create_tool_calling_agent(llm, lc_tools, prompt)
executor = AgentExecutor(agent=agent, tools=lc_tools)
result = await executor.ainvoke({'input': 'List all Slack channels'})

CrewAI

from matimo import Matimo
from matimo.integrations.crewai import convert_tools_to_crewai

matimo = await Matimo.init(auto_discover=True)
tools = convert_tools_to_crewai(matimo.list_tools(), matimo)

MCP server

from matimo import Matimo, create_mcp_server, MCPServerOptions

matimo = await Matimo.init(auto_discover=True)
server = await create_mcp_server(matimo, MCPServerOptions(name='my-agent', version='1.0.0'))
await server.start()

Core API

Matimo.init()

from matimo import Matimo, InitOptions

matimo = await Matimo.init(
    tool_paths=['./tools', './agent-tools'],  # or a single string
    auto_discover=False,       # discover installed matimo-* packages
    include_core=True,         # include built-in meta-tools
    policy_file='./policy.yaml',
    untrusted_paths=['./agent-tools'],
    skill_paths=['./skills'],
    log_level='info',          # silent | error | warn | info | debug
    log_format='json',         # json | simple
    on_event=my_event_handler,
    on_hitl=my_approval_callback,
)

Key methods

Tool YAML Format

name: my_api_tool
version: '1.0.0'
description: Fetch data from an API
parameters:
  query:
    type: string
    required: true
    description: Search query
execution:
  type: http
  method: GET
  url: 'https://api.example.com/search?q={query}'
  headers:
    Authorization: 'Bearer {API_KEY}'

Policy Engine

from matimo import Matimo, InitOptions

matimo = await Matimo.init('./tools', InitOptions(
    policy_file='./policy.yaml',
    on_hitl=lambda req: {'approved': True, 'reason': 'auto'},
))

policy.yaml:

allowedDomains:
  - api.github.com
  - api.slack.com
allowedHttpMethods: [GET, POST]
allowCommandTools: false
allowFunctionTools: false

Secrets Management

from matimo.mcp.secrets import create_resolver_chain

resolver = create_resolver_chain([
    {'type': 'env'},
    {'type': 'dotenv', 'path': '.env'},
    {'type': 'vault', 'address': 'http://vault:8200'},
    {'type': 'aws', 'region': 'us-east-1'},
])
token = await resolver.resolve('SLACK_BOT_TOKEN')

Logging

from matimo import Matimo
from matimo.logging import get_global_matimo_logger

matimo = await Matimo.init('./tools', log_level='info', log_format='json')
logger = get_global_matimo_logger()
logger.info('Tool executed', {'tool': 'slack_send_channel_message'})

Meta-Tools (Agent Tool Lifecycle)

Built-in tools that let agents manage other tools at runtime:

Documentation

• Getting Started
• Full API Reference
• LangChain Integration
• CrewAI Integration
• MCP Guide
• Policy & Lifecycle
• Meta-Tools Reference

Links

• PyPI: https://pypi.org/project/matimo-core/
• Docs: https://matimo.dev/docs
• GitHub: https://github.com/tallclub/matimo
• Changelog: https://github.com/tallclub/matimo/blob/main/docs/RELEASES.md