Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

matimo-core

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

PyPI Python Docs Tests Coverage

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

Method Description
await matimo.execute(name, params) Execute a tool by name
matimo.list_tools() Return all loaded ToolDefinition objects
matimo.get_tool(name) Get a single ToolDefinition (or None)
matimo.search_tools(query) Text search over tool names + descriptions
await matimo.reload() Hot-reload tools from disk
matimo.list_skills() Return all loaded skill definitions
await matimo.semantic_search_skills(query) TF-IDF search over skills
matimo.has_policy() Whether a policy engine is active

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:

Tool Purpose Requires Approval
matimo_validate_tool Validate YAML definition No
matimo_create_tool Write new tool to disk Yes
matimo_approve_tool Promote draft → approved Yes
matimo_reload_tools Hot-reload registry Yes
matimo_list_user_tools List agent-created tools No
matimo_get_tool_status Check approval state Yes
matimo_create_skill Create a SKILL.md Yes
matimo_list_skills List available skills No
matimo_get_skill Read skill content No
matimo_validate_skill Validate skill spec No

Documentation


Metadata

Release files for matimo-core 0.1.0a14.post2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for matimo-core 0.1.0a14.post2
File Size Uploaded Provenance Actions
matimo_core-0.1.0a14.post2.tar.gz 85.1 kB Without provenance Details for matimo_core-0.1.0a14.post2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for matimo-core 0.1.0a14.post2
File Interpreter ABI Platform Actions
matimo_core-0.1.0a14.post2-py3-none-any.whl Python 3 none any Details for matimo_core-0.1.0a14.post2-py3-none-any.whl

Total release size: 209.9 kB

Release files / matimo_core-0.1.0a14.post2.tar.gz

Download URL matimo_core-0.1.0a14.post2.tar.gz
Size 85.1 kB
Tags Source
SHA-256 checksum
How to use checksums
dacf8eca84a4485161e778f1618dee2faa0cf1af53866f3a8db2f791e4e651c1
BLAKE2b-256 checksum
How to use checksums
f1c30174740f02294c60623b625de62a134940ec9e70f5ea5fe5a026d8f8d6c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.12

Release files / matimo_core-0.1.0a14.post2-py3-none-any.whl

Download URL matimo_core-0.1.0a14.post2-py3-none-any.whl
Size 124.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dd4276107ce97415af657adb8e0e0ed03560b4f2f41d713e4eb006f0c357cee6
BLAKE2b-256 checksum
How to use checksums
fb1fe5b68aa5a29c4d54c15bc2a896e960417eb5583c5e1d8a4e22cba7368d79
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.12

Security for matimo-core 0.1.0a14.post2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page