mcal-ai 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mcal_ai-0.2.0/.env.example +43 -0
- mcal_ai-0.2.0/LICENSE +21 -0
- mcal_ai-0.2.0/MANIFEST.in +53 -0
- mcal_ai-0.2.0/PKG-INFO +168 -0
- mcal_ai-0.2.0/README.md +96 -0
- mcal_ai-0.2.0/pyproject.toml +151 -0
- mcal_ai-0.2.0/setup.cfg +4 -0
- mcal_ai-0.2.0/src/mcal/__init__.py +165 -0
- mcal_ai-0.2.0/src/mcal/backends/__init__.py +42 -0
- mcal_ai-0.2.0/src/mcal/backends/base.py +383 -0
- mcal_ai-0.2.0/src/mcal/baselines/__init__.py +1 -0
- mcal_ai-0.2.0/src/mcal/core/__init__.py +101 -0
- mcal_ai-0.2.0/src/mcal/core/embeddings.py +266 -0
- mcal_ai-0.2.0/src/mcal/core/extraction_cache.py +398 -0
- mcal_ai-0.2.0/src/mcal/core/goal_retriever.py +539 -0
- mcal_ai-0.2.0/src/mcal/core/intent_tracker.py +734 -0
- mcal_ai-0.2.0/src/mcal/core/models.py +445 -0
- mcal_ai-0.2.0/src/mcal/core/rate_limiter.py +372 -0
- mcal_ai-0.2.0/src/mcal/core/reasoning_store.py +1061 -0
- mcal_ai-0.2.0/src/mcal/core/retry.py +188 -0
- mcal_ai-0.2.0/src/mcal/core/storage.py +456 -0
- mcal_ai-0.2.0/src/mcal/core/streaming.py +254 -0
- mcal_ai-0.2.0/src/mcal/core/unified_extractor.py +1466 -0
- mcal_ai-0.2.0/src/mcal/core/vector_index.py +206 -0
- mcal_ai-0.2.0/src/mcal/evaluation/__init__.py +1 -0
- mcal_ai-0.2.0/src/mcal/integrations/__init__.py +88 -0
- mcal_ai-0.2.0/src/mcal/integrations/autogen.py +95 -0
- mcal_ai-0.2.0/src/mcal/integrations/crewai.py +92 -0
- mcal_ai-0.2.0/src/mcal/integrations/langchain.py +112 -0
- mcal_ai-0.2.0/src/mcal/integrations/langgraph.py +50 -0
- mcal_ai-0.2.0/src/mcal/mcal.py +1697 -0
- mcal_ai-0.2.0/src/mcal/providers/bedrock.py +217 -0
- mcal_ai-0.2.0/src/mcal/storage/__init__.py +1 -0
- mcal_ai-0.2.0/src/mcal_ai.egg-info/PKG-INFO +168 -0
- mcal_ai-0.2.0/src/mcal_ai.egg-info/SOURCES.txt +37 -0
- mcal_ai-0.2.0/src/mcal_ai.egg-info/dependency_links.txt +1 -0
- mcal_ai-0.2.0/src/mcal_ai.egg-info/entry_points.txt +2 -0
- mcal_ai-0.2.0/src/mcal_ai.egg-info/requires.txt +57 -0
- mcal_ai-0.2.0/src/mcal_ai.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# MCAL Environment Configuration
|
|
2
|
+
# Copy this to .env and fill in your values
|
|
3
|
+
|
|
4
|
+
# =============================================================================
|
|
5
|
+
# LLM Provider (Required - choose one)
|
|
6
|
+
# =============================================================================
|
|
7
|
+
|
|
8
|
+
# Anthropic API (Recommended for extraction)
|
|
9
|
+
ANTHROPIC_API_KEY=your_anthropic_api_key_here
|
|
10
|
+
|
|
11
|
+
# OpenAI API (Alternative LLM provider)
|
|
12
|
+
OPENAI_API_KEY=your_openai_api_key_here
|
|
13
|
+
|
|
14
|
+
# AWS Bedrock (Alternative - uses AWS credentials)
|
|
15
|
+
# Configure via: aws configure
|
|
16
|
+
# AWS_PROFILE=your_profile
|
|
17
|
+
# AWS_REGION=us-west-2
|
|
18
|
+
|
|
19
|
+
# =============================================================================
|
|
20
|
+
# Embedding Provider (Required - choose one)
|
|
21
|
+
# =============================================================================
|
|
22
|
+
|
|
23
|
+
# OpenAI Embeddings (Default)
|
|
24
|
+
# Uses OPENAI_API_KEY from above
|
|
25
|
+
|
|
26
|
+
# Bedrock Embeddings (Alternative)
|
|
27
|
+
# Uses AWS credentials from above
|
|
28
|
+
# MCAL_EMBEDDING_PROVIDER=bedrock
|
|
29
|
+
|
|
30
|
+
# =============================================================================
|
|
31
|
+
# Optional Settings
|
|
32
|
+
# =============================================================================
|
|
33
|
+
|
|
34
|
+
# Experiment tracking
|
|
35
|
+
WANDB_API_KEY=your_wandb_api_key_here
|
|
36
|
+
WANDB_PROJECT=mcal-research
|
|
37
|
+
|
|
38
|
+
# Model settings
|
|
39
|
+
DEFAULT_MODEL=claude-3-5-sonnet-20241022
|
|
40
|
+
EMBEDDING_MODEL=text-embedding-3-small
|
|
41
|
+
|
|
42
|
+
# Storage location (default: ~/.mcal)
|
|
43
|
+
# MCAL_STORAGE_PATH=/path/to/storage
|
mcal_ai-0.2.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Shiva
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# MANIFEST.in - Controls what files are included in PyPI distribution package
|
|
2
|
+
|
|
3
|
+
# Include essential documentation
|
|
4
|
+
include README.md
|
|
5
|
+
include LICENSE
|
|
6
|
+
include .env.example
|
|
7
|
+
|
|
8
|
+
# Include package source
|
|
9
|
+
recursive-include src/mcal *.py
|
|
10
|
+
recursive-include src/mcal py.typed
|
|
11
|
+
|
|
12
|
+
# Exclude test files
|
|
13
|
+
recursive-exclude tests *
|
|
14
|
+
recursive-exclude tests/test_integrations *
|
|
15
|
+
|
|
16
|
+
# Exclude development files
|
|
17
|
+
exclude .coverage
|
|
18
|
+
exclude .env
|
|
19
|
+
exclude pyproject.toml.backup
|
|
20
|
+
recursive-exclude * __pycache__
|
|
21
|
+
recursive-exclude * *.pyc
|
|
22
|
+
recursive-exclude * *.pyo
|
|
23
|
+
recursive-exclude * *.egg-info
|
|
24
|
+
|
|
25
|
+
# Exclude experimental and result files
|
|
26
|
+
recursive-exclude experiments *
|
|
27
|
+
recursive-exclude results *
|
|
28
|
+
recursive-exclude benchmarks *
|
|
29
|
+
recursive-exclude backup_* *
|
|
30
|
+
|
|
31
|
+
# Exclude data directories
|
|
32
|
+
recursive-exclude data *
|
|
33
|
+
recursive-exclude mcal_data *
|
|
34
|
+
recursive-exclude logs *
|
|
35
|
+
|
|
36
|
+
# Exclude build artifacts
|
|
37
|
+
recursive-exclude dist *
|
|
38
|
+
recursive-exclude build *
|
|
39
|
+
|
|
40
|
+
# Exclude scripts (dev tools)
|
|
41
|
+
recursive-exclude scripts *
|
|
42
|
+
|
|
43
|
+
# Exclude issue tracking
|
|
44
|
+
recursive-exclude issues *
|
|
45
|
+
|
|
46
|
+
# Exclude API server (separate deployment)
|
|
47
|
+
recursive-exclude api *
|
|
48
|
+
|
|
49
|
+
# Exclude integration packages (separate packages)
|
|
50
|
+
recursive-exclude packages *
|
|
51
|
+
|
|
52
|
+
# Exclude CI/CD
|
|
53
|
+
recursive-exclude .github *
|
mcal_ai-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mcal-ai
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Memory-Context Alignment Layer for Goal-Coherent AI Agents
|
|
5
|
+
Author: MCAL Team
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Shivakoreddi/mcal-ai
|
|
8
|
+
Project-URL: Documentation, https://github.com/Shivakoreddi/mcal-ai#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/Shivakoreddi/mcal-ai.git
|
|
10
|
+
Project-URL: Issues, https://github.com/Shivakoreddi/mcal-ai/issues
|
|
11
|
+
Keywords: llm,memory,agents,context,ai,nlp
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: anthropic>=0.18.0
|
|
24
|
+
Requires-Dist: openai>=1.0.0
|
|
25
|
+
Requires-Dist: boto3>=1.28.0
|
|
26
|
+
Requires-Dist: pydantic>=2.0.0
|
|
27
|
+
Requires-Dist: numpy>=1.24.0
|
|
28
|
+
Requires-Dist: faiss-cpu>=1.7.4
|
|
29
|
+
Requires-Dist: sentence-transformers>=2.2.0
|
|
30
|
+
Requires-Dist: sqlalchemy>=2.0.0
|
|
31
|
+
Requires-Dist: aiosqlite>=0.19.0
|
|
32
|
+
Requires-Dist: tiktoken>=0.5.0
|
|
33
|
+
Requires-Dist: tenacity>=8.2.0
|
|
34
|
+
Requires-Dist: rich>=13.0.0
|
|
35
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
36
|
+
Provides-Extra: langgraph
|
|
37
|
+
Requires-Dist: langgraph>=0.0.40; extra == "langgraph"
|
|
38
|
+
Requires-Dist: langchain-core>=0.1.0; extra == "langgraph"
|
|
39
|
+
Provides-Extra: crewai
|
|
40
|
+
Requires-Dist: crewai>=0.28.0; extra == "crewai"
|
|
41
|
+
Provides-Extra: autogen
|
|
42
|
+
Requires-Dist: pyautogen>=0.2.0; extra == "autogen"
|
|
43
|
+
Provides-Extra: langchain
|
|
44
|
+
Requires-Dist: langchain>=0.1.0; extra == "langchain"
|
|
45
|
+
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
|
|
46
|
+
Provides-Extra: integrations
|
|
47
|
+
Requires-Dist: langgraph>=0.0.40; extra == "integrations"
|
|
48
|
+
Requires-Dist: langchain-core>=0.1.0; extra == "integrations"
|
|
49
|
+
Requires-Dist: crewai>=0.28.0; extra == "integrations"
|
|
50
|
+
Requires-Dist: pyautogen>=0.2.0; extra == "integrations"
|
|
51
|
+
Provides-Extra: mem0
|
|
52
|
+
Requires-Dist: mem0ai>=0.1.0; extra == "mem0"
|
|
53
|
+
Provides-Extra: dev
|
|
54
|
+
Requires-Dist: pytest>=7.4.0; extra == "dev"
|
|
55
|
+
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
|
|
56
|
+
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
|
|
57
|
+
Requires-Dist: black>=23.0.0; extra == "dev"
|
|
58
|
+
Requires-Dist: ruff>=0.1.0; extra == "dev"
|
|
59
|
+
Requires-Dist: mypy>=1.5.0; extra == "dev"
|
|
60
|
+
Requires-Dist: pre-commit>=3.4.0; extra == "dev"
|
|
61
|
+
Requires-Dist: ipykernel>=6.25.0; extra == "dev"
|
|
62
|
+
Requires-Dist: jupyter>=1.0.0; extra == "dev"
|
|
63
|
+
Provides-Extra: eval
|
|
64
|
+
Requires-Dist: pandas>=2.0.0; extra == "eval"
|
|
65
|
+
Requires-Dist: matplotlib>=3.7.0; extra == "eval"
|
|
66
|
+
Requires-Dist: seaborn>=0.12.0; extra == "eval"
|
|
67
|
+
Requires-Dist: wandb>=0.15.0; extra == "eval"
|
|
68
|
+
Requires-Dist: scipy>=1.11.0; extra == "eval"
|
|
69
|
+
Provides-Extra: all
|
|
70
|
+
Requires-Dist: mcal[dev,eval,integrations]; extra == "all"
|
|
71
|
+
Dynamic: license-file
|
|
72
|
+
|
|
73
|
+
# MCAL: Memory-Context Alignment Layer
|
|
74
|
+
|
|
75
|
+
> **Intent-Preserving Memory for Goal-Coherent AI Agents**
|
|
76
|
+
|
|
77
|
+
[](https://pypi.org/project/mcal-ai/)
|
|
78
|
+
[](https://www.python.org/downloads/)
|
|
79
|
+
[](https://opensource.org/licenses/MIT)
|
|
80
|
+
|
|
81
|
+
## Why MCAL?
|
|
82
|
+
|
|
83
|
+
Current AI memory systems store **facts** but lose **meaning**:
|
|
84
|
+
|
|
85
|
+
| What's Stored | What's Lost |
|
|
86
|
+
|---------------|-------------|
|
|
87
|
+
| "User chose PostgreSQL" | **WHY** they chose it over MongoDB |
|
|
88
|
+
| "User wants to visit Japan" | **HOW** this fits their overall travel goals |
|
|
89
|
+
|
|
90
|
+
MCAL preserves the **reasoning behind decisions**, not just the conclusions.
|
|
91
|
+
|
|
92
|
+
## Installation
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
pip install mcal-ai
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
**Framework integrations:**
|
|
99
|
+
```bash
|
|
100
|
+
pip install mcal-ai-langgraph # LangGraph integration
|
|
101
|
+
pip install mcal-ai-crewai # CrewAI integration
|
|
102
|
+
pip install mcal-ai-autogen # AutoGen integration
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## Quick Start
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
import asyncio
|
|
109
|
+
from mcal import MCAL
|
|
110
|
+
|
|
111
|
+
async def main():
|
|
112
|
+
mcal = MCAL(
|
|
113
|
+
llm_provider="anthropic", # or "openai", "bedrock"
|
|
114
|
+
embedding_provider="openai", # or "bedrock"
|
|
115
|
+
)
|
|
116
|
+
|
|
117
|
+
messages = [
|
|
118
|
+
{"role": "user", "content": "I'm building a fraud detection pipeline"},
|
|
119
|
+
{"role": "assistant", "content": "Let's start with data ingestion..."},
|
|
120
|
+
{"role": "user", "content": "I chose PostgreSQL over MongoDB for storage"},
|
|
121
|
+
]
|
|
122
|
+
|
|
123
|
+
# Extract goals, decisions, and reasoning
|
|
124
|
+
result = await mcal.add(messages, user_id="user_123")
|
|
125
|
+
print(f"Extracted {result.unified_graph.node_count} nodes")
|
|
126
|
+
|
|
127
|
+
# Search with goal-aware retrieval
|
|
128
|
+
results = await mcal.search("What database?", user_id="user_123")
|
|
129
|
+
|
|
130
|
+
# Get context for LLM prompts
|
|
131
|
+
context = mcal.get_context("What's next?", user_id="user_123")
|
|
132
|
+
|
|
133
|
+
asyncio.run(main())
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Key Features
|
|
137
|
+
|
|
138
|
+
- **Intent Graph** - Hierarchical goal structures (Mission → Goal → Task)
|
|
139
|
+
- **Reasoning Chains** - Store WHY decisions were made, not just conclusions
|
|
140
|
+
- **Goal-Aware Retrieval** - Retrieve based on objective alignment, not just similarity
|
|
141
|
+
- **Multi-Provider** - Works with Anthropic, OpenAI, and AWS Bedrock
|
|
142
|
+
- **Standalone** - No external dependencies, JSON file persistence
|
|
143
|
+
|
|
144
|
+
## Environment Variables
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
# Choose your LLM provider
|
|
148
|
+
ANTHROPIC_API_KEY=sk-ant-... # For Claude
|
|
149
|
+
OPENAI_API_KEY=sk-... # For GPT-4 / embeddings
|
|
150
|
+
|
|
151
|
+
# Optional: AWS Bedrock
|
|
152
|
+
AWS_ACCESS_KEY_ID=...
|
|
153
|
+
AWS_SECRET_ACCESS_KEY=...
|
|
154
|
+
AWS_DEFAULT_REGION=us-east-1
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## Documentation
|
|
158
|
+
|
|
159
|
+
- [GitHub Repository](https://github.com/Shivakoreddi/mcal-ai)
|
|
160
|
+
- [Design Document](https://github.com/Shivakoreddi/mcal-ai/blob/main/docs/MCAL_DESIGN.md)
|
|
161
|
+
|
|
162
|
+
## License
|
|
163
|
+
|
|
164
|
+
MIT License - see [LICENSE](https://github.com/Shivakoreddi/mcal-ai/blob/main/LICENSE) for details.
|
|
165
|
+
|
|
166
|
+
## Author
|
|
167
|
+
|
|
168
|
+
Created by [Shiva Koreddi](https://github.com/Shivakoreddi)
|
mcal_ai-0.2.0/README.md
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# MCAL: Memory-Context Alignment Layer
|
|
2
|
+
|
|
3
|
+
> **Intent-Preserving Memory for Goal-Coherent AI Agents**
|
|
4
|
+
|
|
5
|
+
[](https://pypi.org/project/mcal-ai/)
|
|
6
|
+
[](https://www.python.org/downloads/)
|
|
7
|
+
[](https://opensource.org/licenses/MIT)
|
|
8
|
+
|
|
9
|
+
## Why MCAL?
|
|
10
|
+
|
|
11
|
+
Current AI memory systems store **facts** but lose **meaning**:
|
|
12
|
+
|
|
13
|
+
| What's Stored | What's Lost |
|
|
14
|
+
|---------------|-------------|
|
|
15
|
+
| "User chose PostgreSQL" | **WHY** they chose it over MongoDB |
|
|
16
|
+
| "User wants to visit Japan" | **HOW** this fits their overall travel goals |
|
|
17
|
+
|
|
18
|
+
MCAL preserves the **reasoning behind decisions**, not just the conclusions.
|
|
19
|
+
|
|
20
|
+
## Installation
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pip install mcal-ai
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
**Framework integrations:**
|
|
27
|
+
```bash
|
|
28
|
+
pip install mcal-ai-langgraph # LangGraph integration
|
|
29
|
+
pip install mcal-ai-crewai # CrewAI integration
|
|
30
|
+
pip install mcal-ai-autogen # AutoGen integration
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Quick Start
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
import asyncio
|
|
37
|
+
from mcal import MCAL
|
|
38
|
+
|
|
39
|
+
async def main():
|
|
40
|
+
mcal = MCAL(
|
|
41
|
+
llm_provider="anthropic", # or "openai", "bedrock"
|
|
42
|
+
embedding_provider="openai", # or "bedrock"
|
|
43
|
+
)
|
|
44
|
+
|
|
45
|
+
messages = [
|
|
46
|
+
{"role": "user", "content": "I'm building a fraud detection pipeline"},
|
|
47
|
+
{"role": "assistant", "content": "Let's start with data ingestion..."},
|
|
48
|
+
{"role": "user", "content": "I chose PostgreSQL over MongoDB for storage"},
|
|
49
|
+
]
|
|
50
|
+
|
|
51
|
+
# Extract goals, decisions, and reasoning
|
|
52
|
+
result = await mcal.add(messages, user_id="user_123")
|
|
53
|
+
print(f"Extracted {result.unified_graph.node_count} nodes")
|
|
54
|
+
|
|
55
|
+
# Search with goal-aware retrieval
|
|
56
|
+
results = await mcal.search("What database?", user_id="user_123")
|
|
57
|
+
|
|
58
|
+
# Get context for LLM prompts
|
|
59
|
+
context = mcal.get_context("What's next?", user_id="user_123")
|
|
60
|
+
|
|
61
|
+
asyncio.run(main())
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Key Features
|
|
65
|
+
|
|
66
|
+
- **Intent Graph** - Hierarchical goal structures (Mission → Goal → Task)
|
|
67
|
+
- **Reasoning Chains** - Store WHY decisions were made, not just conclusions
|
|
68
|
+
- **Goal-Aware Retrieval** - Retrieve based on objective alignment, not just similarity
|
|
69
|
+
- **Multi-Provider** - Works with Anthropic, OpenAI, and AWS Bedrock
|
|
70
|
+
- **Standalone** - No external dependencies, JSON file persistence
|
|
71
|
+
|
|
72
|
+
## Environment Variables
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
# Choose your LLM provider
|
|
76
|
+
ANTHROPIC_API_KEY=sk-ant-... # For Claude
|
|
77
|
+
OPENAI_API_KEY=sk-... # For GPT-4 / embeddings
|
|
78
|
+
|
|
79
|
+
# Optional: AWS Bedrock
|
|
80
|
+
AWS_ACCESS_KEY_ID=...
|
|
81
|
+
AWS_SECRET_ACCESS_KEY=...
|
|
82
|
+
AWS_DEFAULT_REGION=us-east-1
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Documentation
|
|
86
|
+
|
|
87
|
+
- [GitHub Repository](https://github.com/Shivakoreddi/mcal-ai)
|
|
88
|
+
- [Design Document](https://github.com/Shivakoreddi/mcal-ai/blob/main/docs/MCAL_DESIGN.md)
|
|
89
|
+
|
|
90
|
+
## License
|
|
91
|
+
|
|
92
|
+
MIT License - see [LICENSE](https://github.com/Shivakoreddi/mcal-ai/blob/main/LICENSE) for details.
|
|
93
|
+
|
|
94
|
+
## Author
|
|
95
|
+
|
|
96
|
+
Created by [Shiva Koreddi](https://github.com/Shivakoreddi)
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "mcal-ai"
|
|
7
|
+
version = "0.2.0"
|
|
8
|
+
description = "Memory-Context Alignment Layer for Goal-Coherent AI Agents"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = {text = "MIT"}
|
|
11
|
+
authors = [
|
|
12
|
+
{name = "MCAL Team"}
|
|
13
|
+
]
|
|
14
|
+
requires-python = ">=3.11"
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 3 - Alpha",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Intended Audience :: Science/Research",
|
|
19
|
+
"License :: OSI Approved :: MIT License",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
24
|
+
]
|
|
25
|
+
keywords = ["llm", "memory", "agents", "context", "ai", "nlp"]
|
|
26
|
+
|
|
27
|
+
dependencies = [
|
|
28
|
+
"anthropic>=0.18.0",
|
|
29
|
+
"openai>=1.0.0",
|
|
30
|
+
"boto3>=1.28.0",
|
|
31
|
+
"pydantic>=2.0.0",
|
|
32
|
+
"numpy>=1.24.0",
|
|
33
|
+
"faiss-cpu>=1.7.4",
|
|
34
|
+
"sentence-transformers>=2.2.0",
|
|
35
|
+
"sqlalchemy>=2.0.0",
|
|
36
|
+
"aiosqlite>=0.19.0",
|
|
37
|
+
"tiktoken>=0.5.0",
|
|
38
|
+
"tenacity>=8.2.0",
|
|
39
|
+
"rich>=13.0.0",
|
|
40
|
+
"python-dotenv>=1.0.0",
|
|
41
|
+
]
|
|
42
|
+
|
|
43
|
+
[project.optional-dependencies]
|
|
44
|
+
# Framework integrations
|
|
45
|
+
langgraph = [
|
|
46
|
+
"langgraph>=0.0.40",
|
|
47
|
+
"langchain-core>=0.1.0",
|
|
48
|
+
]
|
|
49
|
+
crewai = [
|
|
50
|
+
"crewai>=0.28.0",
|
|
51
|
+
]
|
|
52
|
+
autogen = [
|
|
53
|
+
"pyautogen>=0.2.0",
|
|
54
|
+
]
|
|
55
|
+
langchain = [
|
|
56
|
+
"langchain>=0.1.0",
|
|
57
|
+
"langchain-core>=0.1.0",
|
|
58
|
+
]
|
|
59
|
+
|
|
60
|
+
# All integrations
|
|
61
|
+
integrations = [
|
|
62
|
+
"langgraph>=0.0.40",
|
|
63
|
+
"langchain-core>=0.1.0",
|
|
64
|
+
"crewai>=0.28.0",
|
|
65
|
+
"pyautogen>=0.2.0",
|
|
66
|
+
]
|
|
67
|
+
|
|
68
|
+
# Legacy Mem0 backend (deprecated, Issue #53)
|
|
69
|
+
mem0 = [
|
|
70
|
+
"mem0ai>=0.1.0",
|
|
71
|
+
]
|
|
72
|
+
dev = [
|
|
73
|
+
"pytest>=7.4.0",
|
|
74
|
+
"pytest-asyncio>=0.21.0",
|
|
75
|
+
"pytest-cov>=4.1.0",
|
|
76
|
+
"black>=23.0.0",
|
|
77
|
+
"ruff>=0.1.0",
|
|
78
|
+
"mypy>=1.5.0",
|
|
79
|
+
"pre-commit>=3.4.0",
|
|
80
|
+
"ipykernel>=6.25.0",
|
|
81
|
+
"jupyter>=1.0.0",
|
|
82
|
+
]
|
|
83
|
+
eval = [
|
|
84
|
+
"pandas>=2.0.0",
|
|
85
|
+
"matplotlib>=3.7.0",
|
|
86
|
+
"seaborn>=0.12.0",
|
|
87
|
+
"wandb>=0.15.0",
|
|
88
|
+
"scipy>=1.11.0",
|
|
89
|
+
]
|
|
90
|
+
all = ["mcal[dev,eval,integrations]"]
|
|
91
|
+
|
|
92
|
+
[project.urls]
|
|
93
|
+
Homepage = "https://github.com/Shivakoreddi/mcal-ai"
|
|
94
|
+
Documentation = "https://github.com/Shivakoreddi/mcal-ai#readme"
|
|
95
|
+
Repository = "https://github.com/Shivakoreddi/mcal-ai.git"
|
|
96
|
+
Issues = "https://github.com/Shivakoreddi/mcal-ai/issues"
|
|
97
|
+
|
|
98
|
+
[project.scripts]
|
|
99
|
+
mcal = "mcal.cli:main"
|
|
100
|
+
|
|
101
|
+
[tool.setuptools.packages.find]
|
|
102
|
+
where = ["src"]
|
|
103
|
+
|
|
104
|
+
[tool.setuptools.package-data]
|
|
105
|
+
mcal = ["py.typed"]
|
|
106
|
+
|
|
107
|
+
[tool.black]
|
|
108
|
+
line-length = 100
|
|
109
|
+
target-version = ['py311']
|
|
110
|
+
include = '\.pyi?$'
|
|
111
|
+
exclude = '''
|
|
112
|
+
/(
|
|
113
|
+
\.git
|
|
114
|
+
| \.mypy_cache
|
|
115
|
+
| \.venv
|
|
116
|
+
| build
|
|
117
|
+
| dist
|
|
118
|
+
)/
|
|
119
|
+
'''
|
|
120
|
+
|
|
121
|
+
[tool.ruff]
|
|
122
|
+
line-length = 100
|
|
123
|
+
target-version = "py311"
|
|
124
|
+
select = [
|
|
125
|
+
"E", # pycodestyle errors
|
|
126
|
+
"W", # pycodestyle warnings
|
|
127
|
+
"F", # Pyflakes
|
|
128
|
+
"I", # isort
|
|
129
|
+
"B", # flake8-bugbear
|
|
130
|
+
"C4", # flake8-comprehensions
|
|
131
|
+
"UP", # pyupgrade
|
|
132
|
+
]
|
|
133
|
+
ignore = [
|
|
134
|
+
"E501", # line too long (handled by black)
|
|
135
|
+
"B008", # do not perform function calls in argument defaults
|
|
136
|
+
]
|
|
137
|
+
|
|
138
|
+
[tool.ruff.isort]
|
|
139
|
+
known-first-party = ["mcal"]
|
|
140
|
+
|
|
141
|
+
[tool.mypy]
|
|
142
|
+
python_version = "3.11"
|
|
143
|
+
warn_return_any = true
|
|
144
|
+
warn_unused_ignores = true
|
|
145
|
+
disallow_untyped_defs = true
|
|
146
|
+
plugins = ["pydantic.mypy"]
|
|
147
|
+
|
|
148
|
+
[tool.pytest.ini_options]
|
|
149
|
+
testpaths = ["tests"]
|
|
150
|
+
asyncio_mode = "auto"
|
|
151
|
+
addopts = "-v --cov=src/mcal --cov-report=term-missing"
|
mcal_ai-0.2.0/setup.cfg
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
"""
|
|
2
|
+
MCAL: Memory-Context Alignment Layer
|
|
3
|
+
|
|
4
|
+
A standalone memory architecture for AI agents that preserves:
|
|
5
|
+
- Intent graphs (goal hierarchies)
|
|
6
|
+
- Reasoning chains (decision rationale)
|
|
7
|
+
- Goal-aware retrieval (objective-based context)
|
|
8
|
+
|
|
9
|
+
Usage:
|
|
10
|
+
from mcal import MCAL
|
|
11
|
+
|
|
12
|
+
mcal = MCAL(
|
|
13
|
+
openai_api_key="..." # or anthropic_api_key, or use bedrock
|
|
14
|
+
)
|
|
15
|
+
|
|
16
|
+
# Add conversation
|
|
17
|
+
result = await mcal.add(messages, user_id="user_123")
|
|
18
|
+
|
|
19
|
+
# Search with goal-awareness
|
|
20
|
+
context = await mcal.get_context("What's next?", user_id="user_123")
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
__version__ = "0.1.0"
|
|
24
|
+
|
|
25
|
+
# Main interface
|
|
26
|
+
from .mcal import MCAL, AddResult, SearchResult, TimingMetrics, TieredBedrockProvider
|
|
27
|
+
|
|
28
|
+
# Core models
|
|
29
|
+
from .core.models import (
|
|
30
|
+
DecisionTrail,
|
|
31
|
+
IntentGraph,
|
|
32
|
+
IntentNode,
|
|
33
|
+
IntentStatus,
|
|
34
|
+
IntentType,
|
|
35
|
+
Memory,
|
|
36
|
+
MemoryType,
|
|
37
|
+
RetrievalConfig,
|
|
38
|
+
RetrievalResult,
|
|
39
|
+
Session,
|
|
40
|
+
Turn,
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
# Core components (for advanced usage)
|
|
44
|
+
from .core.intent_tracker import IntentTracker
|
|
45
|
+
from .core.reasoning_store import ReasoningStore
|
|
46
|
+
from .core.goal_retriever import GoalRetriever, ContextAssembler
|
|
47
|
+
|
|
48
|
+
# Streaming API (Issue #10)
|
|
49
|
+
from .core.streaming import (
|
|
50
|
+
StreamEvent,
|
|
51
|
+
StreamEventType,
|
|
52
|
+
ExtractionPhase,
|
|
53
|
+
StreamProgress,
|
|
54
|
+
CacheHitInfo,
|
|
55
|
+
PhaseResult,
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
# Backends (MemoryEntry kept for compatibility)
|
|
59
|
+
from .backends import (
|
|
60
|
+
MemoryBackend,
|
|
61
|
+
MemoryEntry,
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
# Deprecated: Mem0Backend and StandaloneBackend (Issue #53)
|
|
65
|
+
# Use: from mcal.backends import Mem0Backend (requires pip install mcal[mem0])
|
|
66
|
+
|
|
67
|
+
__all__ = [
|
|
68
|
+
# Version
|
|
69
|
+
"__version__",
|
|
70
|
+
# Main interface
|
|
71
|
+
"MCAL",
|
|
72
|
+
"AddResult",
|
|
73
|
+
"SearchResult",
|
|
74
|
+
# Models
|
|
75
|
+
"DecisionTrail",
|
|
76
|
+
"IntentGraph",
|
|
77
|
+
"IntentNode",
|
|
78
|
+
"IntentStatus",
|
|
79
|
+
"IntentType",
|
|
80
|
+
"Memory",
|
|
81
|
+
"MemoryType",
|
|
82
|
+
"RetrievalConfig",
|
|
83
|
+
"RetrievalResult",
|
|
84
|
+
"Session",
|
|
85
|
+
"Turn",
|
|
86
|
+
# Core components
|
|
87
|
+
"IntentTracker",
|
|
88
|
+
"ReasoningStore",
|
|
89
|
+
"GoalRetriever",
|
|
90
|
+
"ContextAssembler",
|
|
91
|
+
# Backends (for advanced usage)
|
|
92
|
+
"MemoryBackend",
|
|
93
|
+
"MemoryEntry",
|
|
94
|
+
# Streaming (Issue #10)
|
|
95
|
+
"StreamEvent",
|
|
96
|
+
"StreamEventType",
|
|
97
|
+
"ExtractionPhase",
|
|
98
|
+
"StreamProgress",
|
|
99
|
+
"CacheHitInfo",
|
|
100
|
+
"PhaseResult",
|
|
101
|
+
# Integrations namespace
|
|
102
|
+
"integrations",
|
|
103
|
+
# Integration shortcuts (lazy loaded)
|
|
104
|
+
"LangGraphMemory",
|
|
105
|
+
"LangGraphStore",
|
|
106
|
+
"CrewAIMemory",
|
|
107
|
+
"AutoGenMemory",
|
|
108
|
+
"LangChainMemory",
|
|
109
|
+
]
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
# Lazy loading for integration shortcuts
|
|
113
|
+
def __getattr__(name: str):
|
|
114
|
+
"""Lazy load integration classes to avoid import errors."""
|
|
115
|
+
import importlib
|
|
116
|
+
|
|
117
|
+
if name == "integrations":
|
|
118
|
+
return importlib.import_module("mcal.integrations")
|
|
119
|
+
|
|
120
|
+
if name == "LangGraphMemory":
|
|
121
|
+
try:
|
|
122
|
+
mod = importlib.import_module("mcal.integrations.langgraph")
|
|
123
|
+
return mod.MCALMemory
|
|
124
|
+
except ImportError:
|
|
125
|
+
raise ImportError(
|
|
126
|
+
"LangGraph integration requires: pip install mcal[langgraph]"
|
|
127
|
+
)
|
|
128
|
+
|
|
129
|
+
if name == "LangGraphStore":
|
|
130
|
+
try:
|
|
131
|
+
mod = importlib.import_module("mcal.integrations.langgraph")
|
|
132
|
+
return mod.MCALStore
|
|
133
|
+
except ImportError:
|
|
134
|
+
raise ImportError(
|
|
135
|
+
"LangGraph integration requires: pip install mcal[langgraph]"
|
|
136
|
+
)
|
|
137
|
+
|
|
138
|
+
if name == "CrewAIMemory":
|
|
139
|
+
try:
|
|
140
|
+
mod = importlib.import_module("mcal.integrations.crewai")
|
|
141
|
+
return mod.MCALCrewMemory
|
|
142
|
+
except ImportError:
|
|
143
|
+
raise ImportError(
|
|
144
|
+
"CrewAI integration requires: pip install mcal[crewai]"
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
if name == "AutoGenMemory":
|
|
148
|
+
try:
|
|
149
|
+
mod = importlib.import_module("mcal.integrations.autogen")
|
|
150
|
+
return mod.MCALMemoryAgent
|
|
151
|
+
except ImportError:
|
|
152
|
+
raise ImportError(
|
|
153
|
+
"AutoGen integration requires: pip install mcal[autogen]"
|
|
154
|
+
)
|
|
155
|
+
|
|
156
|
+
if name == "LangChainMemory":
|
|
157
|
+
try:
|
|
158
|
+
mod = importlib.import_module("mcal.integrations.langchain")
|
|
159
|
+
return mod.MCALChatMemory
|
|
160
|
+
except ImportError:
|
|
161
|
+
raise ImportError(
|
|
162
|
+
"LangChain integration requires: pip install mcal[langchain]"
|
|
163
|
+
)
|
|
164
|
+
|
|
165
|
+
raise AttributeError(f"module 'mcal' has no attribute '{name}'")
|