Metadata-Version: 2.4
Name: matimo-core
Version: 0.1.0
Summary: Matimo core — framework-agnostic SDK: pre-built providers, skills layer, MCP, and a policy engine you control
Project-URL: Homepage, https://matimo.dev
Project-URL: Documentation, https://matimo.dev/docs
Project-URL: Repository, https://github.com/tallclub/matimo
Project-URL: Issues, https://github.com/tallclub/matimo/issues
License: MIT
Keywords: agents,ai,crewai,langchain,matimo,mcp,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: anyio>=4.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: typing-extensions>=4.9
Provides-Extra: all
Requires-Dist: crewai>=0.80; extra == 'all'
Requires-Dist: hvac>=2.0; extra == 'all'
Requires-Dist: langchain-core>=0.3; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: python-dotenv>=1.0; extra == 'all'
Provides-Extra: aws
Requires-Dist: boto3>=1.34; extra == 'aws'
Provides-Extra: crewai
Requires-Dist: crewai>=0.80; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: boto3>=1.34; extra == 'dev'
Requires-Dist: crewai>=0.80; extra == 'dev'
Requires-Dist: hvac>=2.0; extra == 'dev'
Requires-Dist: langchain-core>=0.3; extra == 'dev'
Requires-Dist: mcp>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: dotenv
Requires-Dist: python-dotenv>=1.0; extra == 'dotenv'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: vault
Requires-Dist: hvac>=2.0; extra == 'vault'
Description-Content-Type: text/markdown

# matimo-core

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

[![PyPI](https://img.shields.io/pypi/v/matimo-core)](https://pypi.org/project/matimo-core/)
[![Python](https://img.shields.io/pypi/pyversions/matimo-core)](https://pypi.org/project/matimo-core/)
[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
[![Tests](https://img.shields.io/badge/tests-658%20passing-brightgreen)](https://github.com/tallclub/matimo)
[![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen)](https://github.com/tallclub/matimo)

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

> **Note:** Most users should install [`matimo`](https://pypi.org/project/matimo/) (the convenience wrapper) instead of `matimo-core` directly.

---

## Installation

```bash
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

```python
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

```python
from matimo import Matimo

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

### Decorator pattern

```python
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

```python
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

```python
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

```python
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()`

```python
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

```yaml
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

```python
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`:
```yaml
allowedDomains:
  - api.github.com
  - api.slack.com
allowedHttpMethods: [GET, POST]
allowCommandTools: false
allowFunctionTools: false
```

---

## Secrets Management

```python
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

```python
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

- [Getting Started](https://matimo.dev/docs/getting-started/QUICK_START)
- [Full API Reference](https://matimo.dev/docs/api-reference/SDK)
- [LangChain Integration](https://matimo.dev/docs/framework-integrations/LANGCHAIN)
- [CrewAI Integration](https://matimo.dev/docs/framework-integrations/CREWAI)
- [MCP Guide](https://matimo.dev/docs/MCP)
- [Policy & Lifecycle](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE)
- [Meta-Tools Reference](https://matimo.dev/docs/api-reference/META_TOOLS)

---

## 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

