Metadata-Version: 2.4
Name: mcal-ai
Version: 0.2.2
Summary: Memory-Context Alignment Layer for Goal-Coherent AI Agents
Author: MCAL Team
License: MIT
Project-URL: Homepage, https://github.com/Shivakoreddi/mcal-ai
Project-URL: Documentation, https://github.com/Shivakoreddi/mcal-ai#readme
Project-URL: Repository, https://github.com/Shivakoreddi/mcal-ai.git
Project-URL: Issues, https://github.com/Shivakoreddi/mcal-ai/issues
Keywords: llm,memory,agents,context,ai,nlp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
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
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.18.0
Requires-Dist: openai>=1.0.0
Requires-Dist: boto3>=1.28.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: faiss-cpu>=1.7.4
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: tenacity>=8.2.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.0.40; extra == "langgraph"
Requires-Dist: langchain-core>=0.1.0; extra == "langgraph"
Provides-Extra: crewai
Requires-Dist: crewai>=0.28.0; extra == "crewai"
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2.0; extra == "autogen"
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == "langchain"
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: integrations
Requires-Dist: langgraph>=0.0.40; extra == "integrations"
Requires-Dist: langchain-core>=0.1.0; extra == "integrations"
Requires-Dist: crewai>=0.28.0; extra == "integrations"
Requires-Dist: pyautogen>=0.2.0; extra == "integrations"
Provides-Extra: mem0
Requires-Dist: mem0ai>=0.1.0; extra == "mem0"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: pre-commit>=3.4.0; extra == "dev"
Requires-Dist: ipykernel>=6.25.0; extra == "dev"
Requires-Dist: jupyter>=1.0.0; extra == "dev"
Provides-Extra: eval
Requires-Dist: pandas>=2.0.0; extra == "eval"
Requires-Dist: matplotlib>=3.7.0; extra == "eval"
Requires-Dist: seaborn>=0.12.0; extra == "eval"
Requires-Dist: wandb>=0.15.0; extra == "eval"
Requires-Dist: scipy>=1.11.0; extra == "eval"
Provides-Extra: all
Requires-Dist: mcal[dev,eval,integrations]; extra == "all"
Dynamic: license-file

# MCAL: Memory-Context Alignment Layer

> **Intent-Preserving Memory for Goal-Coherent AI Agents**

[![PyPI](https://img.shields.io/pypi/v/mcal-ai.svg)](https://pypi.org/project/mcal-ai/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Why MCAL?

Current AI memory systems store **facts** but lose **meaning**:

| What's Stored | What's Lost |
|---------------|-------------|
| "User chose PostgreSQL" | **WHY** they chose it over MongoDB |
| "User wants to visit Japan" | **HOW** this fits their overall travel goals |

MCAL preserves the **reasoning behind decisions**, not just the conclusions.

## Installation

```bash
pip install mcal-ai
```

**Framework integrations:**
```bash
pip install mcal-ai-langgraph  # LangGraph integration
pip install mcal-ai-crewai     # CrewAI integration  
pip install mcal-ai-autogen    # AutoGen integration
```

## Quick Start

```python
import asyncio
from mcal import MCAL

async def main():
    mcal = MCAL(
        llm_provider="anthropic",     # or "openai", "bedrock"
        embedding_provider="openai",  # or "bedrock"
    )
    
    messages = [
        {"role": "user", "content": "I'm building a fraud detection pipeline"},
        {"role": "assistant", "content": "Let's start with data ingestion..."},
        {"role": "user", "content": "I chose PostgreSQL over MongoDB for storage"},
    ]
    
    # Extract goals, decisions, and reasoning
    result = await mcal.add(messages, user_id="user_123")
    print(f"Extracted {result.unified_graph.node_count} nodes")
    
    # Search with goal-aware retrieval
    results = await mcal.search("What database?", user_id="user_123")
    
    # Get context for LLM prompts
    context = mcal.get_context("What's next?", user_id="user_123")

asyncio.run(main())
```

## Key Features

- **Intent Graph** - Hierarchical goal structures (Mission → Goal → Task)
- **Reasoning Chains** - Store WHY decisions were made, not just conclusions
- **Goal-Aware Retrieval** - Retrieve based on objective alignment, not just similarity
- **Multi-Provider** - Works with Anthropic, OpenAI, and AWS Bedrock
- **Standalone** - No external dependencies, JSON file persistence

## Environment Variables

```bash
# Choose your LLM provider
ANTHROPIC_API_KEY=sk-ant-...    # For Claude
OPENAI_API_KEY=sk-...           # For GPT-4 / embeddings

# Optional: AWS Bedrock
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=us-east-1
```

## Documentation

- [GitHub Repository](https://github.com/Shivakoreddi/mcal-ai)
- [Design Document](https://github.com/Shivakoreddi/mcal-ai/blob/main/docs/MCAL_DESIGN.md)

## License

MIT License - see [LICENSE](https://github.com/Shivakoreddi/mcal-ai/blob/main/LICENSE) for details.

## Author

Created by [Shiva Koreddi](https://github.com/Shivakoreddi)
