---
title: ML Plugin Overview
amsdal_docs:
  target: framework/plugins/amsdal-ml/overview.md
  nav_title: Overview
  nav_section: Framework
  nav_path: ["Plugins & Extensions", "ML"]
  nav_order: 1
---

# ML Plugin

`amsdal_ml` is a machine learning plugin for the AMSDAL Framework that adds vector embeddings, semantic search, natural language CRUD operations, AI agents, and MCP server integration.

## Features

- **Embeddings & Search** — generate vector embeddings from your AMSDAL models and search them semantically
- **Natural Language CRUD** — read, create, update, and delete records using plain English queries
- **AI Agents** — ReAct and function-calling agents with pluggable tools
- **MCP Server** — expose your data to AI assistants (Claude Desktop, Chatbox, etc.) via Model Context Protocol
- **OAuth** — authenticated MCP access with full AMSDAL permission checks

## Installation

```bash
pip install amsdal_ml
```

## Plugin Registration

Add the plugin to `AMSDAL_CONTRIBS` in your `.env` file:

```bash
AMSDAL_CONTRIBS=amsdal_ml.app.MLPluginAppConfig
```

Or append to existing contribs:

```bash
AMSDAL_CONTRIBS=amsdal.contrib.auth.app.AuthAppConfig,amsdal_ml.app.MLPluginAppConfig
```

## Configuration

`amsdal_ml` uses `MLConfig` (based on pydantic-settings) for configuration. All settings can be set via environment variables.

### API Keys

| Env Variable | Description |
|-------------|-------------|
| `OPENAI_API_KEY` | OpenAI API key (required for embeddings and LLM) |
| `CLAUDE_API_KEY` | Anthropic API key (optional, for Claude-based models) |

### LLM Settings

| Env Variable | Default | Description |
|-------------|---------|-------------|
| `LLM_MODEL_NAME` | `gpt-4o` | LLM model for NL queries and agents |
| `LLM_TEMPERATURE` | `0.0` | Temperature for LLM responses |

### Embedding Settings

| Env Variable | Default | Description |
|-------------|---------|-------------|
| `EMBED_MODEL_NAME` | `text-embedding-3-small` | Embedding model name |
| `EMBED_DIMENSIONS` | `1536` | Embedding vector dimensions |
| `EMBED_MAX_DEPTH` | `2` | Max depth for recursive model walking |
| `EMBED_MAX_CHUNKS` | `10` | Max chunks per object |
| `EMBED_MAX_TOKENS_PER_CHUNK` | `800` | Max tokens per chunk |

### Retriever Settings

| Env Variable | Default | Description |
|-------------|---------|-------------|
| `RETRIEVER_DEFAULT_K` | `8` | Default number of results for similarity search |
| `RETRIEVER_INCLUDE_TAGS_DEFAULT` | — | Default include tags (comma-separated) |
| `RETRIEVER_EXCLUDE_TAGS_DEFAULT` | — | Default exclude tags (comma-separated) |

### OAuth Settings

| Env Variable | Default | Description |
|-------------|---------|-------------|
| `OAUTH_ENABLED` | `true` | Enable OAuth for MCP server |
| `OAUTH_CLIENT_ID_EXPIRATION_DAYS` | `30` | Client ID expiration (days) |
| `OAUTH_CODE_EXP_MINUTES` | `10` | Authorization code expiration (minutes) |
| `OAUTH_ACCESS_TOKEN_EXP_HOURS` | `24` | Access token expiration (hours) |
| `OAUTH_REFRESH_TOKEN_EXP_DAYS` | `90` | Refresh token expiration (days) |
| `OAUTH_LOGIN_PATH` | `/auth/login` | Login page path |
| `OAUTH_ISSUER` | `http://127.0.0.1:8000` | OAuth issuer URL |

### Class Settings

| Env Variable | Default | Description |
|-------------|---------|-------------|
| `ML_MODEL_CLASS` | `amsdal_ml.ml_models.openai_model.OpenAIModel` | LLM model implementation class |
| `MCP_ML_MODEL_CLASS` | `amsdal_ml.ml_models.openai_model.OpenAIModel` | LLM model class for MCP server |
| `ML_RETRIEVER_CLASS` | `amsdal_ml.ml_retrievers.openai_retriever.OpenAIRetriever` | Retriever implementation class |
| `ML_INGESTING_CLASS` | `amsdal_ml.ml_ingesting.openai_ingesting.OpenAIIngesting` | Ingesting implementation class |

### Other Settings

| Env Variable | Default | Description |
|-------------|---------|-------------|
| `ASYNC_MODE` | `true` | Enable async mode |

## Quick Start

```python
from amsdal_ml.ml_ingesting.openai_ingesting import OpenAIIngesting
from amsdal_ml.ml_retrievers.openai_retriever import OpenAIRetriever

# Index a model object
ingesting = OpenAIIngesting(tags=['my-tag'])
records = await ingesting.agenerate_embeddings(my_object)
await ingesting.asave(records, my_object)

# Search
retriever = OpenAIRetriever()
results = await retriever.asimilarity_search('find documents about payments', k=5)

for chunk in results:
    print(chunk.raw_text, chunk.distance)
```

## Architecture

The plugin is organized into these main modules:

| Module | Description |
|--------|-------------|
| `ml_models` | LLM interfaces (`MLModel`, `OpenAIModel`) |
| `ml_ingesting` | Embedding generation, document ingestion pipeline |
| `ml_retrievers` | Semantic search, NL query/create/update/delete executors |
| `agents` | AI agents (`DefaultQAAgent`, `FunctionalCallingAgent`) with tools |
| `mcp_server` | MCP servers (stdio, HTTP/SSE) with OAuth |
| `mcp_client` | MCP client implementations for connecting to external servers |
| `fileio` | File attachment handling and OpenAI file uploads |
