Metadata-Version: 2.4
Name: masai_framework
Version: 0.6.8
Summary: Build tool-using agents with native Gemini, Anthropic, and OpenAI SDKs.
Author-email: PILER <mrpolymathematica@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/shaunthecomputerscientist/mas-ai
Project-URL: Documentation, https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/README.md
Project-URL: Issues, https://github.com/shaunthecomputerscientist/mas-ai/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=3.44.0
Requires-Dist: google-genai>=2.34.0
Requires-Dist: anthropic>=2.4.0
Requires-Dist: pydantic>=2.12.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: json-repair>=0.39.1
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: numpy==1.26.4; python_version < "3.13"
Requires-Dist: numpy<3,>=2.1; python_version >= "3.13"
Requires-Dist: redis>=6.4.0
Requires-Dist: qdrant-client>=1.20.0
Provides-Extra: dev
Requires-Dist: pytest>=9.2; extra == "dev"
Requires-Dist: pytest-asyncio>=1.4; extra == "dev"
Requires-Dist: ruff>=0.17.3; extra == "dev"
Requires-Dist: build>=1.6; extra == "dev"
Requires-Dist: twine>=7; extra == "dev"
Requires-Dist: setuptools>=77.0.0; extra == "dev"
Provides-Extra: memory
Requires-Dist: langchain-redis>=0.2.0; extra == "memory"
Requires-Dist: sentence-transformers>=3.0.0; extra == "memory"
Provides-Extra: tools
Requires-Dist: beautifulsoup4>=4.12.0; extra == "tools"
Requires-Dist: langchain>=0.3.0; extra == "tools"
Requires-Dist: langchain-community>=0.3.0; extra == "tools"
Requires-Dist: langchain-core>=0.3.0; extra == "tools"
Provides-Extra: vectorstore
Requires-Dist: langchain-huggingface>=0.1.0; extra == "vectorstore"
Requires-Dist: langchain-milvus>=0.1.0; extra == "vectorstore"
Requires-Dist: langchain-openai>=0.2.0; extra == "vectorstore"
Requires-Dist: langchain-pinecone>=0.2.0; extra == "vectorstore"
Requires-Dist: pinecone>=5.0.0; extra == "vectorstore"
Requires-Dist: pymilvus>=2.4.0; extra == "vectorstore"
Requires-Dist: PyPDF2>=3.0.0; extra == "vectorstore"
Requires-Dist: PyMuPDF>=1.24.0; extra == "vectorstore"
Provides-Extra: documents
Requires-Dist: PyPDF2>=3.0.0; extra == "documents"
Requires-Dist: PyMuPDF>=1.24.0; extra == "documents"
Provides-Extra: mongodb
Requires-Dist: pymongo>=4.8.0; extra == "mongodb"
Provides-Extra: youtube
Requires-Dist: google-api-python-client>=2.140.0; extra == "youtube"
Requires-Dist: youtube-transcript-api>=0.6.0; extra == "youtube"
Provides-Extra: vision
Requires-Dist: pyautogui>=0.9.54; extra == "vision"
Requires-Dist: pygetwindow>=0.0.9; extra == "vision"
Provides-Extra: health
Requires-Dist: scikit-learn>=1.5.0; extra == "health"
Requires-Dist: joblib>=1.4.0; extra == "health"
Requires-Dist: torch>=2.4.0; extra == "health"
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file

# MASAI

![MASAI logo](https://raw.githubusercontent.com/shaunthecomputerscientist/mas-ai/main/docs/assets/logo.png)

A Python framework for agents that use tools, retain context, and work together.
MASAI calls the native Gemini, Anthropic, and OpenAI SDKs.
The core agent workflow does not require LangChain.

This guide describes version 0.6.8.
Read it in order, then use the linked chapters for details.

## Contents

- [Feature map](#feature-map)
- [1. Install](#1-install)
- [2. Configure models](#2-configure-models)
- [3. Run the first agent](#3-run-the-first-agent)
- [4. Use tools and planning](#4-use-tools-and-planning)
- [5. Add context callbacks](#5-add-context-callbacks)
- [6. Cache prompt prefixes](#6-cache-prompt-prefixes)
- [7. Keep memory and sessions](#7-keep-memory-and-sessions)
- [8. Stream results](#8-stream-results)
- [9. Coordinate agents](#9-coordinate-agents)
- [10. Understand the architecture](#10-understand-the-architecture)
- [11. Upgrade and troubleshoot](#11-upgrade-and-troubleshoot)
- [12. Reference and development](#12-reference-and-development)
- [13. License](#13-license)

## Feature map

| Area | Features | Guide |
|---|---|---|
| Agent workflow | Router, evaluator, reflector, optional planner, typed tools, direct return, parallel tool calls, and runtime tool discovery | [Tools and planning](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/agents/tools-and-planning.md) |
| Agent controls | Memory windows, summaries, tool/reflection limits, deadlines, output limits, per-component overrides, and model-specific settings | [Model config](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/configuration/model-config.md) |
| Providers | Gemini, Anthropic, and OpenAI wrappers; native request fields; structured output; client options; model rejection overrides | [Provider settings](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/configuration/providers.md) |
| Prompt context | Context callbacks, constant/dynamic fields, base INFO, history, summaries, tool output, and peer context | [Context callbacks](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/agents/context-callables.md) |
| Caching | Provider prompt-prefix caching and separate synchronous Redis tool-result caching | [Prompt caching](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/caching/prompt-caching.md), [tool cache](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/caching/tool-results.md) |
| Conversation state | Component histories, summaries, retained task state, dump/restore, request identity, and caller isolation | [Agent state](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/agents/state-and-context.md), [sessions](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/memory/memory-and-sessions.md) |
| Data and memory | Documents, embeddings, in-memory store, Qdrant and Redis vector memory, metadata filters, and deduplication | [Memory](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/memory/memory-and-sessions.md), [documents](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/memory/documents.md), [embeddings](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/memory/embeddings.md) |
| Multiple agents | Sequential runs, decentralized delegation, streaming handoffs, hierarchical supervisor, task queue, and result callbacks | [Multi-agent workflows](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/agents/multi-agent.md) |
| Streaming | Graph state updates, provider chunks, structured response events, and server-sent events | [Streaming](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/agents/streaming.md) |
| Framework internals | Manager, graph, prompts, model factory, wrappers, memory adapters, tools, and extension points | [Architecture](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/architecture/framework.md), [API reference](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/reference/api.md) |
| Other modules | OMAN and migration notes for older guide content | [API reference](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/reference/api.md#experimental-modules), [older-guide coverage](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/reference/guide-coverage.md) |

## 1. Install

Use Python 3.11 for the checked release setup.
Install version 0.6.8 or later:

```sh
python -m pip install "masai-framework>=0.6.8"
```

A local wheel or source checkout works before publication.
Create your application in its own folder and name the script `app.py`.
See [installation](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/getting-started/installation.md).

| Provider | Key variable | Alternative |
|---|---|---|
| Gemini | `GOOGLE_API_KEY` | `GEMINI_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` | `CLAUDE_API_KEY` |
| OpenAI | `OPENAI_API_KEY` | |

Set the key for the provider you use.
`load_dotenv()` reads an application's `.env` file.

## 2. Configure models

Save `model_config.json` beside `app.py`.
The `all` block is the fallback for agents without a named block.
Each block defines a router, evaluator, reflector, and optional planner.

```json
{
  "all": {
    "router": {"model_name": "gemini-3.8-flash", "category": "gemini", "max_output_tokens": 4096},
    "evaluator": {"model_name": "gemini-3.8-flash", "category": "gemini", "max_output_tokens": 4096},
    "reflector": {"model_name": "gemini-3.8-flash", "category": "gemini", "max_output_tokens": 4096},
    "planner": {"model_name": "gemini-3.8-flash", "category": "gemini", "max_output_tokens": 4096}
  }
}
```

A named agent block replaces the fallback block; it is not a partial merge.
Use lowercase names and provide all components needed by that agent.
The full [sample config](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/model_config.json) also shows Anthropic and OpenAI.

MASAI uses its own settings internally and forwards native provider parameters.
Flat native fields and `provider_params` both work.
`client_options` configures SDK clients, such as their timeout.
The SDK and selected model decide which native fields are valid.

Read [model config](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/configuration/model-config.md)
and [provider parameters](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/configuration/providers.md).

## 3. Run the first agent

Save this complete script as `app.py`:

```python
import asyncio
from pathlib import Path

from dotenv import load_dotenv
from masai.AgentManager import AgentDetails, AgentManager
from masai.Tools.Tool import tool

load_dotenv()


@tool("add", return_direct=True)
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b


async def main():
    manager = AgentManager(
        model_config_path=str(Path(__file__).with_name("model_config.json")),
        logging=False,
    )
    agent = manager.create_agent(
        agent_name="assistant",
        tools=[add],
        agent_details=AgentDetails(
            capabilities=["arithmetic"],
            description="Use add for addition.",
            style="concise",
        ),
        long_context=False,
        max_total_tool_calls=5,
        run_timeout_seconds=60,
    )
    result = await agent.initiate_agent("Use add to calculate 2 + 2.", passed_from="user")
    print(result["answer"])


if __name__ == "__main__":
    asyncio.run(main())
```

```sh
python app.py
```

The router selects `add` and its inputs.
MASAI validates those inputs, runs the function, and returns its direct result.
Read the [quick-start walkthrough](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/getting-started/quick-start.md).

## 4. Use tools and planning

`Tool` and `@tool` turn typed functions into tools.
`return_direct=True` lets a tool finish a task.
Other tools pass their results to an evaluator.

Set `execute_multiple_tools=True` for independent calls in one turn.
Set `plan=True` to add a planner; the config then needs a planner component.
The planner replaces the router as the graph entry when enabled.
Tool discovery and runtime tool updates rebuild the answer schema.

| Control | Default | Effect |
|---|---:|---|
| `plan` | `False` | Add a planner and use it as the graph entry |
| `execute_multiple_tools` | `False` | Run independent tool calls together |
| `max_total_tool_calls` | 25000 | Hard per-run tool cap; `0` disables it |
| `max_tool_loop` | 3 | Warn on repeated identical calls; advisory only |
| `max_reflection_count` | 3 | Bound reflection attempts |
| `max_recursion_limit` | 100 | Graph recursion ceiling |
| `run_timeout_seconds` | 0 | Deadline between graph steps; `0` disables it |
| `max_tool_output_words` | 3000 | Bound tool text included in prompts |
| `tool_output_similarity_threshold` | 0 | Truncate exact repeats only; positive values enable fuzzy matching |

Other controls include `memory_order`, `long_context`, `shared_memory_order`, `retain_messages_order`, `context_callable`, `callable_config`, `tool_registry`, `long_context_model`, and `character_factor`.
See [all agent and model controls](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/configuration/model-config.md#agent-controls).
Choose a suitable tool cap for your application.
A graph deadline does not interrupt an SDK call already in flight.
Use a client timeout too.
See [tools and planning](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/agents/tools-and-planning.md).

## 5. Add context callbacks

Callbacks fetch context before a model call.
A plain dictionary is fully dynamic.
Use this return type to choose reusable fields:

```python
from masai.GenerativeModel import ContextResult


def context_for_turn(text: str):
    return ContextResult(
        constant={"workflow_guide": "Use add for arithmetic."},
        dynamic={"current_task": text},
    )
```

Pass it as `context_callable` for user-input calls.
Use `callable_config` for later nodes that need fresh context.
The input starts with the current question and adds prior node reasoning when available.
Callback results are local to the call.
See [context callbacks](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/agents/context-callables.md).
Read [agent state](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/agents/state-and-context.md) for base context and conversation lifetime,
and [request context](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/agents/request-context.md) for caller identity in tools.

## 6. Cache prompt prefixes

The default prompt order is:

```text
System + component instructions
Response/tool schema and peers
Callback constant context         <-- one cache boundary
Agent name, time, dynamic INFO, history, long context, question
```

The caller chooses constant fields; MASAI does not guess them.
The wrappers apply each provider's native cache settings.
There is no common `caching=true` switch.

| Provider | Component setting |
|---|---|
| Anthropic | `"cache_control": {"type": "ephemeral", "ttl": "5m"}` |
| OpenAI, on supported models | `"prompt_cache_options": {"mode": "explicit", "ttl": "30m"}` |
| Gemini | Native implicit caching; no enable flag |

A cache marker makes a prefix eligible; it does not guarantee a hit.
A changed word inside that prefix can require a new write.
The name and live context stay after the prefix.
The callback still runs and the request still contains fresh dynamic data.
Read [MASAI prompt caching](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/caching/prompt-caching.md)
for setup, provider behavior, usage checks, and limits.
For synchronous data lookups, [tool-result caching](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/caching/tool-results.md) is a separate Redis feature.

## 7. Keep memory and sessions

Component history, summaries, persistent memory, and provider caching have separate roles.
Agent summaries are enabled by default and can add model calls.
The first example disables them with `long_context=False`.

`dump_session()` exports runtime state; `load_session()` restores it after agent creation.
Clients, credentials, tools, and graphs are not serialized.
Persistent memory supports Qdrant and Redis with a supplied embedding model.
See [memory and sessions](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/memory/memory-and-sessions.md).
Use [Documents](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/memory/documents.md) for text, metadata, and serialization.
Use [embedding adapters](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/memory/embeddings.md) to connect native APIs or local models.

## 8. Stream results

`initiate_agent_astream()` yields graph updates.
Provider token chunks are a separate interface.
A structured Anthropic response is yielded once it is complete.

`EnhancedStreamHandler` converts agent events to server-sent events.
It cancels active stream work when the consumer disconnects.
See [streaming](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/agents/streaming.md).

## 9. Coordinate agents

Create all agents in one manager, then create `MultiAgentSystem`.
Sequential runs pass results in order.
Decentralized runs let agents delegate to peers.
Hierarchical runs use a supervisor and task manager.

Use separate agent/session state for separate callers.
See [multi-agent workflows](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/agents/multi-agent.md).

## 10. Understand the architecture

![MASAI application, manager, graph, provider, tools, and result flow](https://raw.githubusercontent.com/shaunthecomputerscientist/mas-ai/main/docs/assets/diagrams/overview.png)

[Open full-size diagram](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/assets/diagrams/overview.png)

AgentManager chooses config and builds the components.
The provider registry builds each wrapper and client.
During a run, the agent graph calls MASGenerativeModel to render context and send requests.
The model returns a validated decision; MASAI executes local tools.

The framework owns its state and request structure.
Native provider fields remain available to the selected SDK.
Read [architecture and data flow](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/architecture/framework.md), including the detailed [agent graph](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/agents/state-and-context.md) and [multi-agent flows](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/agents/multi-agent.md).

## 11. Upgrade and troubleshoot

Version 0.6.8 rejects incomplete tool calls before dispatch and handles large Anthropic output limits.
Version 0.6.7 fixes Anthropic structured output for recent models and supports Python 3.13+.
Version 0.6.6 changed native parameter forwarding, callback lifetime, and cache placement.
See [migration](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/reference/migration-0.6.6.md)
and [troubleshooting](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/reference/troubleshooting.md).
The [older-guide coverage table](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/reference/guide-coverage.md) maps retained topics and corrects obsolete examples.

## 12. Reference and development

The [documentation book](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/README.md)
links all chapters in reading order.
Use the [API reference](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/docs/reference/api.md)
for exact entry points.

From a source checkout:

```sh
python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check src tests
python -m ruff format --check src tests
python -m build
python -m twine check dist/*
```

Default tests stay offline.
See [contributing](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/CONTRIBUTING.md)
and the [changelog](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/CHANGELOG.md).

## 13. License

[Apache License 2.0](https://github.com/shaunthecomputerscientist/mas-ai/blob/main/LICENSE).
