memra 0.2.3__tar.gz → 0.2.5__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.
- memra-0.2.5/CHANGELOG.md +63 -0
- memra-0.2.5/LICENSE +21 -0
- memra-0.2.5/PKG-INFO +319 -0
- memra-0.2.5/README.md +280 -0
- memra-0.2.5/mcp_bridge_server.py +1178 -0
- memra-0.2.5/memra/__init__.py +45 -0
- memra-0.2.5/memra/cli.py +286 -0
- memra-0.2.5/memra/discovery.py +15 -0
- memra-0.2.5/memra/discovery_client.py +49 -0
- memra-0.2.5/memra/execution.py +662 -0
- memra-0.2.5/memra/models.py +100 -0
- memra-0.2.5/memra/tool_registry.py +351 -0
- memra-0.2.5/memra/tool_registry_client.py +106 -0
- memra-0.2.5/memra-ops/app.py +808 -0
- memra-0.2.5/memra-ops/config/config.py +25 -0
- memra-0.2.5/memra-ops/config.py +34 -0
- memra-0.2.5/memra-ops/logic/__init__.py +1 -0
- memra-0.2.5/memra-ops/logic/file_tools.py +43 -0
- memra-0.2.5/memra-ops/logic/invoice_tools.py +668 -0
- memra-0.2.5/memra-ops/logic/invoice_tools_fix.py +66 -0
- memra-0.2.5/memra-ops/mcp_bridge_server.py +1178 -0
- memra-0.2.5/memra-ops/scripts/check_database.py +37 -0
- memra-0.2.5/memra-ops/scripts/clear_database.py +48 -0
- memra-0.2.5/memra-ops/scripts/monitor_database.py +67 -0
- memra-0.2.5/memra-ops/scripts/release.py +133 -0
- memra-0.2.5/memra-ops/scripts/reset_database.py +65 -0
- memra-0.2.5/memra-ops/scripts/start_memra.py +334 -0
- memra-0.2.5/memra-ops/scripts/stop_memra.py +132 -0
- memra-0.2.5/memra-ops/server_tool_registry.py +190 -0
- memra-0.2.5/memra-ops/tests/test_llm_text_to_sql.py +115 -0
- memra-0.2.5/memra-ops/tests/test_llm_vs_pattern.py +130 -0
- memra-0.2.5/memra-ops/tests/test_mcp_schema_aware.py +124 -0
- memra-0.2.5/memra-ops/tests/test_schema_aware_sql.py +139 -0
- memra-0.2.5/memra-ops/tests/test_schema_aware_sql_simple.py +66 -0
- memra-0.2.5/memra-ops/tests/test_text_to_sql_demo.py +140 -0
- memra-0.2.5/memra-ops/tools/mcp_bridge_server.py +851 -0
- memra-0.2.5/memra-sdk/examples/accounts_payable.py +215 -0
- memra-0.2.5/memra-sdk/examples/accounts_payable_client.py +217 -0
- memra-0.2.5/memra-sdk/examples/accounts_payable_mcp.py +200 -0
- memra-0.2.5/memra-sdk/examples/ask_questions.py +123 -0
- memra-0.2.5/memra-sdk/examples/invoice_processing.py +116 -0
- memra-0.2.5/memra-sdk/examples/propane_delivery.py +87 -0
- memra-0.2.5/memra-sdk/examples/simple_text_to_sql.py +158 -0
- {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/__init__.py +1 -1
- memra-0.2.5/memra-sdk/scripts/release.py +133 -0
- {memra-0.2.3 → memra-0.2.5/memra-sdk}/setup.py +1 -1
- memra-0.2.5/memra-workflows/accounts_payable/accounts_payable.py +215 -0
- memra-0.2.5/memra-workflows/accounts_payable/accounts_payable_client.py +216 -0
- memra-0.2.5/memra-workflows/accounts_payable/accounts_payable_mcp.py +200 -0
- memra-0.2.5/memra-workflows/accounts_payable/accounts_payable_smart.py +221 -0
- memra-0.2.5/memra-workflows/invoice_processing/invoice_processing.py +116 -0
- memra-0.2.5/memra-workflows/invoice_processing/smart_invoice_processor.py +220 -0
- memra-0.2.5/memra-workflows/logic/__init__.py +1 -0
- memra-0.2.5/memra-workflows/logic/file_tools.py +50 -0
- memra-0.2.5/memra-workflows/logic/invoice_tools.py +501 -0
- memra-0.2.5/memra-workflows/logic/propane_agents.py +52 -0
- memra-0.2.5/memra-workflows/mcp_bridge_server.py +230 -0
- memra-0.2.5/memra-workflows/propane_delivery/propane_delivery.py +87 -0
- memra-0.2.5/memra-workflows/text_to_sql/complete_invoice_workflow_with_queries.py +208 -0
- memra-0.2.5/memra-workflows/text_to_sql/complete_text_to_sql_system.py +266 -0
- memra-0.2.5/memra-workflows/text_to_sql/file_discovery_demo.py +156 -0
- memra-0.2.5/memra.egg-info/SOURCES.txt +70 -0
- {memra-0.2.3 → memra-0.2.5}/pyproject.toml +2 -2
- memra-0.2.5/requirements.txt +6 -0
- memra-0.2.5/setup.py +52 -0
- memra-0.2.3/PKG-INFO +0 -101
- memra-0.2.3/README.md +0 -64
- memra-0.2.3/memra.egg-info/SOURCES.txt +0 -11
- {memra-0.2.3 → memra-0.2.5}/MANIFEST.in +0 -0
- {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/discovery.py +0 -0
- {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/discovery_client.py +0 -0
- {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/execution.py +0 -0
- {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/models.py +0 -0
- {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/tool_registry.py +0 -0
- {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/tool_registry_client.py +0 -0
- {memra-0.2.3 → memra-0.2.5}/setup.cfg +0 -0
memra-0.2.5/CHANGELOG.md
ADDED
@@ -0,0 +1,63 @@
|
|
1
|
+
# Changelog
|
2
|
+
|
3
|
+
All notable changes to the Memra SDK will be documented in this file.
|
4
|
+
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
7
|
+
|
8
|
+
## [0.2.2] - 2025-05-28
|
9
|
+
|
10
|
+
### Fixed
|
11
|
+
- **MCP Integration**: Fixed broken MCP tool execution after repository separation
|
12
|
+
- **Tool Registry**: Updated MCP tool routing to use correct endpoints
|
13
|
+
- **Bridge Server**: Added working MCP bridge server implementation
|
14
|
+
- **Real Work Detection**: Improved detection of real vs mock work for MCP tools
|
15
|
+
|
16
|
+
### Added
|
17
|
+
- Complete MCP bridge server with DataValidator and PostgresInsert tools
|
18
|
+
- Health check endpoint for MCP bridge monitoring
|
19
|
+
- Better error handling and fallback for MCP tool execution
|
20
|
+
|
21
|
+
### Changed
|
22
|
+
- MCP tools now perform real database operations instead of mock responses
|
23
|
+
- Improved logging and debugging for MCP tool execution flow
|
24
|
+
|
25
|
+
## [0.2.1] - 2025-05-27
|
26
|
+
|
27
|
+
## [0.2.0] - 2024-01-17
|
28
|
+
|
29
|
+
### Added
|
30
|
+
- **MCP (Model Context Protocol) Integration**: Execute operations on local infrastructure while leveraging cloud AI processing
|
31
|
+
- New `mcp_bridge_server.py` for local resource bridging
|
32
|
+
- HMAC authentication for secure cloud-to-local communication
|
33
|
+
- Support for `hosted_by: "mcp"` in agent tool configurations
|
34
|
+
- PostgreSQL integration via MCP bridge
|
35
|
+
- Tool-level configuration support in execution engine
|
36
|
+
- New MCP tools: `PostgresInsert`, `DataValidator`
|
37
|
+
|
38
|
+
### Enhanced
|
39
|
+
- **Execution Engine**: Updated to support tool-level configuration and MCP routing
|
40
|
+
- **Tool Registry Client**: Enhanced API client with better error handling and MCP support
|
41
|
+
- **Agent Configuration**: Added support for tool-specific configuration alongside agent-level config
|
42
|
+
|
43
|
+
### Examples
|
44
|
+
- `examples/accounts_payable_mcp.py` - Complete invoice processing with MCP database integration
|
45
|
+
- `test_mcp_success.py` - Simple MCP integration test
|
46
|
+
|
47
|
+
### Documentation
|
48
|
+
- `docs/mcp_integration.md` - Comprehensive MCP integration guide
|
49
|
+
- Updated README with MCP overview and quick start
|
50
|
+
|
51
|
+
### Dependencies
|
52
|
+
- Added `aiohttp>=3.8.0` for MCP bridge server
|
53
|
+
- Added `aiohttp-cors>=0.7.0` for CORS support
|
54
|
+
- Added `psycopg2-binary>=2.9.0` for PostgreSQL integration
|
55
|
+
|
56
|
+
## [0.1.0] - 2024-01-01
|
57
|
+
|
58
|
+
### Added
|
59
|
+
- Initial release of Memra SDK
|
60
|
+
- Core agent and department framework
|
61
|
+
- API client for Memra cloud services
|
62
|
+
- Basic tool registry and execution engine
|
63
|
+
- Examples for accounts payable and propane delivery workflows
|
memra-0.2.5/LICENSE
ADDED
@@ -0,0 +1,21 @@
|
|
1
|
+
MIT License
|
2
|
+
|
3
|
+
Copyright (c) 2025 Memra
|
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.
|
memra-0.2.5/PKG-INFO
ADDED
@@ -0,0 +1,319 @@
|
|
1
|
+
Metadata-Version: 2.4
|
2
|
+
Name: memra
|
3
|
+
Version: 0.2.5
|
4
|
+
Summary: Declarative framework for enterprise workflows with MCP integration - Client SDK
|
5
|
+
Home-page: https://github.com/memra/memra-sdk
|
6
|
+
Author: Memra
|
7
|
+
Author-email: Memra <support@memra.com>
|
8
|
+
License: MIT
|
9
|
+
Project-URL: Homepage, https://memra.co
|
10
|
+
Project-URL: Repository, https://github.com/memra-platform/memra-sdk
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
12
|
+
Classifier: Intended Audience :: Developers
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
14
|
+
Classifier: Operating System :: OS Independent
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
16
|
+
Classifier: Programming Language :: Python :: 3.8
|
17
|
+
Classifier: Programming Language :: Python :: 3.9
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
20
|
+
Requires-Python: >=3.8
|
21
|
+
Description-Content-Type: text/markdown
|
22
|
+
License-File: LICENSE
|
23
|
+
Requires-Dist: pydantic>=1.8.0
|
24
|
+
Requires-Dist: httpx>=0.24.0
|
25
|
+
Requires-Dist: typing-extensions>=4.0.0
|
26
|
+
Requires-Dist: aiohttp>=3.8.0
|
27
|
+
Requires-Dist: aiohttp-cors>=0.7.0
|
28
|
+
Provides-Extra: dev
|
29
|
+
Requires-Dist: pytest>=6.0; extra == "dev"
|
30
|
+
Requires-Dist: pytest-asyncio; extra == "dev"
|
31
|
+
Requires-Dist: black; extra == "dev"
|
32
|
+
Requires-Dist: flake8; extra == "dev"
|
33
|
+
Provides-Extra: mcp
|
34
|
+
Requires-Dist: psycopg2-binary>=2.9.0; extra == "mcp"
|
35
|
+
Dynamic: author
|
36
|
+
Dynamic: home-page
|
37
|
+
Dynamic: license-file
|
38
|
+
Dynamic: requires-python
|
39
|
+
|
40
|
+
# Memra SDK
|
41
|
+
|
42
|
+
**The declarative framework for building enterprise-grade AI workflows with MCP integration.**
|
43
|
+
|
44
|
+
[](https://badge.fury.io/py/memra)
|
45
|
+
[](https://opensource.org/licenses/MIT)
|
46
|
+
[](https://www.python.org/downloads/)
|
47
|
+
|
48
|
+
## 🎯 Why Memra?
|
49
|
+
|
50
|
+
Building AI-powered business workflows is hard. You need to:
|
51
|
+
- **Orchestrate multiple AI agents** with different roles and responsibilities
|
52
|
+
- **Integrate with external tools** (databases, APIs, file systems)
|
53
|
+
- **Handle complex business logic** with validation and error recovery
|
54
|
+
- **Scale from prototypes to production** without rewriting everything
|
55
|
+
- **Maintain consistency** across different workflows and teams
|
56
|
+
|
57
|
+
**Memra solves these challenges** by providing a declarative framework that lets you focus on *what* you want to accomplish, not *how* to wire everything together.
|
58
|
+
|
59
|
+
## 🚀 Quick Start (5 minutes!)
|
60
|
+
|
61
|
+
**Want to see Memra in action immediately?** Check out our [Quick Start Guide](QUICK_START.md) to run the ETL demo in minutes!
|
62
|
+
|
63
|
+
### Installation
|
64
|
+
|
65
|
+
```bash
|
66
|
+
pip install memra
|
67
|
+
```
|
68
|
+
|
69
|
+
**📖 New to Memra?** For a complete beginner-friendly setup with step-by-step instructions, see our [Detailed Installation Guide](INSTALLATION_GUIDE.md) or run our automated setup script:
|
70
|
+
|
71
|
+
```bash
|
72
|
+
# Automated setup for new users
|
73
|
+
bash scripts/setup_newbie.sh
|
74
|
+
```
|
75
|
+
|
76
|
+
**🔧 Repository Structure:** This repo uses git submodules with sparse checkout to provide minimal access to infrastructure and workflow templates while keeping private content secure.
|
77
|
+
|
78
|
+
### Basic Example
|
79
|
+
|
80
|
+
```python
|
81
|
+
from memra import Agent, Department, LLM, ExecutionEngine
|
82
|
+
|
83
|
+
# Define an agent
|
84
|
+
agent = Agent(
|
85
|
+
role="Data Analyst",
|
86
|
+
job="Analyze customer data",
|
87
|
+
llm=LLM(model="llama-3.2-11b-vision-preview"),
|
88
|
+
sops=["Load data", "Perform analysis", "Generate report"],
|
89
|
+
output_key="analysis_result"
|
90
|
+
)
|
91
|
+
|
92
|
+
# Create a department
|
93
|
+
department = Department(
|
94
|
+
name="Analytics",
|
95
|
+
mission="Provide data insights",
|
96
|
+
agents=[agent],
|
97
|
+
workflow_order=["Data Analyst"]
|
98
|
+
)
|
99
|
+
|
100
|
+
# Execute the workflow
|
101
|
+
engine = ExecutionEngine()
|
102
|
+
result = engine.execute_department(department, {"data": "customer_data.csv"})
|
103
|
+
```
|
104
|
+
|
105
|
+
## 🏗️ Core Architecture
|
106
|
+
|
107
|
+
### Agent
|
108
|
+
An AI worker that performs specific tasks using LLMs and tools. Agents have:
|
109
|
+
- **Role**: What they do (e.g., "Data Analyst", "Invoice Processor")
|
110
|
+
- **Job**: Specific task description
|
111
|
+
- **LLM**: Language model configuration
|
112
|
+
- **Tools**: External tools they can use
|
113
|
+
- **SOPs**: Standard operating procedures
|
114
|
+
|
115
|
+
### Department
|
116
|
+
A team of agents working together to accomplish a mission. Departments:
|
117
|
+
- **Coordinate multiple agents** in a workflow
|
118
|
+
- **Handle dependencies** between agents
|
119
|
+
- **Provide execution policies** (retries, timeouts, error handling)
|
120
|
+
- **Manage context** and data flow
|
121
|
+
|
122
|
+
### ExecutionEngine
|
123
|
+
Orchestrates the execution of departments and their workflows with:
|
124
|
+
- **Automatic agent coordination**
|
125
|
+
- **Tool integration** via MCP (Model Context Protocol)
|
126
|
+
- **Error handling and retries**
|
127
|
+
- **Execution tracing and monitoring**
|
128
|
+
|
129
|
+
### LLM
|
130
|
+
Configuration for language models used by agents, supporting:
|
131
|
+
- **Multiple model providers** (OpenAI, Anthropic, local models)
|
132
|
+
- **Custom parameters** (temperature, max tokens, etc.)
|
133
|
+
- **Model-specific configurations**
|
134
|
+
|
135
|
+
## 🔥 Real-World Examples
|
136
|
+
|
137
|
+
### ETL Invoice Processing Demo
|
138
|
+
**Complete end-to-end workflow** that processes PDF invoices using vision models and stores data in PostgreSQL:
|
139
|
+
|
140
|
+
```bash
|
141
|
+
# Run the ETL demo
|
142
|
+
python demos/etl_invoice_processing/etl_invoice_demo.py
|
143
|
+
```
|
144
|
+
|
145
|
+
This demo showcases:
|
146
|
+
- **Vision model integration** for PDF processing
|
147
|
+
- **Multi-agent workflow** (Extractor, Validator, Database Engineer)
|
148
|
+
- **MCP tool integration** (PostgreSQL, SQL execution)
|
149
|
+
- **Data validation and error handling**
|
150
|
+
- **Production-ready patterns**
|
151
|
+
|
152
|
+
### Smart File Discovery
|
153
|
+
Automatically discover and process files with intelligent routing:
|
154
|
+
|
155
|
+
```python
|
156
|
+
from memra import Agent
|
157
|
+
|
158
|
+
# Smart agent that discovers and processes files automatically
|
159
|
+
smart_parser = Agent(
|
160
|
+
role="Smart Invoice Parser",
|
161
|
+
job="Discover and process invoice files intelligently",
|
162
|
+
tools=[
|
163
|
+
{"name": "FileDiscovery", "hosted_by": "memra"},
|
164
|
+
{"name": "FileCopy", "hosted_by": "memra"},
|
165
|
+
{"name": "InvoiceExtractionWorkflow", "hosted_by": "memra"}
|
166
|
+
]
|
167
|
+
)
|
168
|
+
|
169
|
+
# Three modes of operation:
|
170
|
+
# 1. Auto-discovery: Scan invoices/ directory
|
171
|
+
# 2. External file: Copy from Downloads to invoices/
|
172
|
+
# 3. Specific file: Process exact file path
|
173
|
+
```
|
174
|
+
|
175
|
+
### Accounts Payable Workflow
|
176
|
+
Complete accounts payable processing with validation and database integration:
|
177
|
+
|
178
|
+
```python
|
179
|
+
# See examples/accounts_payable_smart.py for full implementation
|
180
|
+
from memra import Department, Agent
|
181
|
+
|
182
|
+
ap_department = Department(
|
183
|
+
name="Accounts Payable",
|
184
|
+
mission="Process and validate vendor invoices",
|
185
|
+
agents=[
|
186
|
+
Agent(role="Invoice Extractor", ...),
|
187
|
+
Agent(role="Data Validator", ...),
|
188
|
+
Agent(role="Database Engineer", ...)
|
189
|
+
],
|
190
|
+
workflow_order=["Invoice Extractor", "Data Validator", "Database Engineer"]
|
191
|
+
)
|
192
|
+
```
|
193
|
+
|
194
|
+
## 🛠️ Key Features
|
195
|
+
|
196
|
+
### 🔌 MCP Integration
|
197
|
+
Built-in support for Model Context Protocol (MCP) tools:
|
198
|
+
- **Database operations** (PostgreSQL, MySQL, etc.)
|
199
|
+
- **File system operations** (discovery, copying, processing)
|
200
|
+
- **API integrations** (REST, GraphQL, custom APIs)
|
201
|
+
- **Custom tool development** with simple Python functions
|
202
|
+
|
203
|
+
### 🎯 Declarative Workflows
|
204
|
+
Define workflows in terms of **what** you want to accomplish:
|
205
|
+
|
206
|
+
```python
|
207
|
+
# Instead of writing procedural code, declare your workflow
|
208
|
+
department = Department(
|
209
|
+
name="Invoice Processing",
|
210
|
+
mission="Extract, validate, and store invoice data",
|
211
|
+
agents=[
|
212
|
+
Agent(role="Extractor", job="Extract data from PDFs"),
|
213
|
+
Agent(role="Validator", job="Validate extracted data"),
|
214
|
+
Agent(role="Database Engineer", job="Store data in database")
|
215
|
+
],
|
216
|
+
workflow_order=["Extractor", "Validator", "Database Engineer"]
|
217
|
+
)
|
218
|
+
```
|
219
|
+
|
220
|
+
### 🔄 Error Handling & Recovery
|
221
|
+
Built-in resilience with:
|
222
|
+
- **Automatic retries** with configurable policies
|
223
|
+
- **Fallback agents** for critical workflows
|
224
|
+
- **Validation at each step**
|
225
|
+
- **Comprehensive error reporting**
|
226
|
+
|
227
|
+
### 📊 Monitoring & Observability
|
228
|
+
Track workflow execution with:
|
229
|
+
- **Execution traces** showing agent and tool usage
|
230
|
+
- **Performance metrics** (timing, costs)
|
231
|
+
- **Error logs** with context
|
232
|
+
- **Audit trails** for compliance
|
233
|
+
|
234
|
+
### 🚀 Production Ready
|
235
|
+
Scale from prototype to production:
|
236
|
+
- **Async execution** for high throughput
|
237
|
+
- **Resource management** and connection pooling
|
238
|
+
- **Configuration management** for different environments
|
239
|
+
- **Security best practices** for API keys and credentials
|
240
|
+
|
241
|
+
## 📚 Documentation
|
242
|
+
|
243
|
+
- **[Quick Start Guide](QUICK_START.md)** - Get up and running in 5 minutes
|
244
|
+
- **[Detailed Installation Guide](INSTALLATION_GUIDE.md)** - Complete beginner-friendly setup instructions
|
245
|
+
- **[System Architecture](memra_system_architecture.md)** - Deep dive into Memra's design
|
246
|
+
- **[Text-to-SQL Guide](TEXT_TO_SQL_USAGE_GUIDE.md)** - Building database query workflows
|
247
|
+
- **[Examples Directory](examples/)** - Complete working examples
|
248
|
+
- **[Demos Directory](demos/)** - Advanced workflow demonstrations
|
249
|
+
|
250
|
+
## 🏢 Use Cases
|
251
|
+
|
252
|
+
### Financial Services
|
253
|
+
- **Invoice processing** and accounts payable automation
|
254
|
+
- **Document classification** and routing
|
255
|
+
- **Compliance monitoring** and reporting
|
256
|
+
- **Risk assessment** and fraud detection
|
257
|
+
|
258
|
+
### Healthcare
|
259
|
+
- **Medical record processing** and data extraction
|
260
|
+
- **Claims processing** and validation
|
261
|
+
- **Patient data analysis** and insights
|
262
|
+
- **Regulatory compliance** workflows
|
263
|
+
|
264
|
+
### Manufacturing
|
265
|
+
- **Quality control** and inspection workflows
|
266
|
+
- **Supply chain** optimization and monitoring
|
267
|
+
- **Equipment maintenance** scheduling
|
268
|
+
- **Production planning** and optimization
|
269
|
+
|
270
|
+
### Retail & E-commerce
|
271
|
+
- **Order processing** and fulfillment
|
272
|
+
- **Customer service** automation
|
273
|
+
- **Inventory management** and forecasting
|
274
|
+
- **Market analysis** and trend detection
|
275
|
+
|
276
|
+
## 🤝 Contributing
|
277
|
+
|
278
|
+
We welcome contributions! Please see our [contributing guide](CONTRIBUTING.md) for details.
|
279
|
+
|
280
|
+
### Development Setup
|
281
|
+
|
282
|
+
```bash
|
283
|
+
# Clone the repository
|
284
|
+
git clone https://github.com/memra-platform/memra-sdk.git
|
285
|
+
cd memra-sdk
|
286
|
+
|
287
|
+
# Install in development mode
|
288
|
+
pip install -e .
|
289
|
+
|
290
|
+
# Run tests
|
291
|
+
pytest tests/
|
292
|
+
```
|
293
|
+
|
294
|
+
## 📄 License
|
295
|
+
|
296
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
297
|
+
|
298
|
+
### MIT License Summary
|
299
|
+
- ✅ **Commercial use** - Use in proprietary software
|
300
|
+
- ✅ **Modification** - Modify and distribute
|
301
|
+
- ✅ **Distribution** - Distribute copies
|
302
|
+
- ✅ **Private use** - Use privately
|
303
|
+
- ❌ **Liability** - No warranty provided
|
304
|
+
- ❌ **Warranty** - No warranty provided
|
305
|
+
|
306
|
+
## 🆘 Support
|
307
|
+
|
308
|
+
- **Issues**: [GitHub Issues](https://github.com/memra-platform/memra-sdk/issues)
|
309
|
+
- **Discussions**: [GitHub Discussions](https://github.com/memra-platform/memra-sdk/discussions)
|
310
|
+
- **Email**: hello@memra.com
|
311
|
+
|
312
|
+
## 🔗 Related Projects
|
313
|
+
|
314
|
+
- **[memra-workflows](https://github.com/memra-platform/memra-workflows)** - Production workflow templates
|
315
|
+
- **[memra-ops](https://github.com/memra-platform/memra-ops)** - Operations and deployment tools
|
316
|
+
|
317
|
+
---
|
318
|
+
|
319
|
+
**Built with ❤️ by the memra team**
|
memra-0.2.5/README.md
ADDED
@@ -0,0 +1,280 @@
|
|
1
|
+
# Memra SDK
|
2
|
+
|
3
|
+
**The declarative framework for building enterprise-grade AI workflows with MCP integration.**
|
4
|
+
|
5
|
+
[](https://badge.fury.io/py/memra)
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
7
|
+
[](https://www.python.org/downloads/)
|
8
|
+
|
9
|
+
## 🎯 Why Memra?
|
10
|
+
|
11
|
+
Building AI-powered business workflows is hard. You need to:
|
12
|
+
- **Orchestrate multiple AI agents** with different roles and responsibilities
|
13
|
+
- **Integrate with external tools** (databases, APIs, file systems)
|
14
|
+
- **Handle complex business logic** with validation and error recovery
|
15
|
+
- **Scale from prototypes to production** without rewriting everything
|
16
|
+
- **Maintain consistency** across different workflows and teams
|
17
|
+
|
18
|
+
**Memra solves these challenges** by providing a declarative framework that lets you focus on *what* you want to accomplish, not *how* to wire everything together.
|
19
|
+
|
20
|
+
## 🚀 Quick Start (5 minutes!)
|
21
|
+
|
22
|
+
**Want to see Memra in action immediately?** Check out our [Quick Start Guide](QUICK_START.md) to run the ETL demo in minutes!
|
23
|
+
|
24
|
+
### Installation
|
25
|
+
|
26
|
+
```bash
|
27
|
+
pip install memra
|
28
|
+
```
|
29
|
+
|
30
|
+
**📖 New to Memra?** For a complete beginner-friendly setup with step-by-step instructions, see our [Detailed Installation Guide](INSTALLATION_GUIDE.md) or run our automated setup script:
|
31
|
+
|
32
|
+
```bash
|
33
|
+
# Automated setup for new users
|
34
|
+
bash scripts/setup_newbie.sh
|
35
|
+
```
|
36
|
+
|
37
|
+
**🔧 Repository Structure:** This repo uses git submodules with sparse checkout to provide minimal access to infrastructure and workflow templates while keeping private content secure.
|
38
|
+
|
39
|
+
### Basic Example
|
40
|
+
|
41
|
+
```python
|
42
|
+
from memra import Agent, Department, LLM, ExecutionEngine
|
43
|
+
|
44
|
+
# Define an agent
|
45
|
+
agent = Agent(
|
46
|
+
role="Data Analyst",
|
47
|
+
job="Analyze customer data",
|
48
|
+
llm=LLM(model="llama-3.2-11b-vision-preview"),
|
49
|
+
sops=["Load data", "Perform analysis", "Generate report"],
|
50
|
+
output_key="analysis_result"
|
51
|
+
)
|
52
|
+
|
53
|
+
# Create a department
|
54
|
+
department = Department(
|
55
|
+
name="Analytics",
|
56
|
+
mission="Provide data insights",
|
57
|
+
agents=[agent],
|
58
|
+
workflow_order=["Data Analyst"]
|
59
|
+
)
|
60
|
+
|
61
|
+
# Execute the workflow
|
62
|
+
engine = ExecutionEngine()
|
63
|
+
result = engine.execute_department(department, {"data": "customer_data.csv"})
|
64
|
+
```
|
65
|
+
|
66
|
+
## 🏗️ Core Architecture
|
67
|
+
|
68
|
+
### Agent
|
69
|
+
An AI worker that performs specific tasks using LLMs and tools. Agents have:
|
70
|
+
- **Role**: What they do (e.g., "Data Analyst", "Invoice Processor")
|
71
|
+
- **Job**: Specific task description
|
72
|
+
- **LLM**: Language model configuration
|
73
|
+
- **Tools**: External tools they can use
|
74
|
+
- **SOPs**: Standard operating procedures
|
75
|
+
|
76
|
+
### Department
|
77
|
+
A team of agents working together to accomplish a mission. Departments:
|
78
|
+
- **Coordinate multiple agents** in a workflow
|
79
|
+
- **Handle dependencies** between agents
|
80
|
+
- **Provide execution policies** (retries, timeouts, error handling)
|
81
|
+
- **Manage context** and data flow
|
82
|
+
|
83
|
+
### ExecutionEngine
|
84
|
+
Orchestrates the execution of departments and their workflows with:
|
85
|
+
- **Automatic agent coordination**
|
86
|
+
- **Tool integration** via MCP (Model Context Protocol)
|
87
|
+
- **Error handling and retries**
|
88
|
+
- **Execution tracing and monitoring**
|
89
|
+
|
90
|
+
### LLM
|
91
|
+
Configuration for language models used by agents, supporting:
|
92
|
+
- **Multiple model providers** (OpenAI, Anthropic, local models)
|
93
|
+
- **Custom parameters** (temperature, max tokens, etc.)
|
94
|
+
- **Model-specific configurations**
|
95
|
+
|
96
|
+
## 🔥 Real-World Examples
|
97
|
+
|
98
|
+
### ETL Invoice Processing Demo
|
99
|
+
**Complete end-to-end workflow** that processes PDF invoices using vision models and stores data in PostgreSQL:
|
100
|
+
|
101
|
+
```bash
|
102
|
+
# Run the ETL demo
|
103
|
+
python demos/etl_invoice_processing/etl_invoice_demo.py
|
104
|
+
```
|
105
|
+
|
106
|
+
This demo showcases:
|
107
|
+
- **Vision model integration** for PDF processing
|
108
|
+
- **Multi-agent workflow** (Extractor, Validator, Database Engineer)
|
109
|
+
- **MCP tool integration** (PostgreSQL, SQL execution)
|
110
|
+
- **Data validation and error handling**
|
111
|
+
- **Production-ready patterns**
|
112
|
+
|
113
|
+
### Smart File Discovery
|
114
|
+
Automatically discover and process files with intelligent routing:
|
115
|
+
|
116
|
+
```python
|
117
|
+
from memra import Agent
|
118
|
+
|
119
|
+
# Smart agent that discovers and processes files automatically
|
120
|
+
smart_parser = Agent(
|
121
|
+
role="Smart Invoice Parser",
|
122
|
+
job="Discover and process invoice files intelligently",
|
123
|
+
tools=[
|
124
|
+
{"name": "FileDiscovery", "hosted_by": "memra"},
|
125
|
+
{"name": "FileCopy", "hosted_by": "memra"},
|
126
|
+
{"name": "InvoiceExtractionWorkflow", "hosted_by": "memra"}
|
127
|
+
]
|
128
|
+
)
|
129
|
+
|
130
|
+
# Three modes of operation:
|
131
|
+
# 1. Auto-discovery: Scan invoices/ directory
|
132
|
+
# 2. External file: Copy from Downloads to invoices/
|
133
|
+
# 3. Specific file: Process exact file path
|
134
|
+
```
|
135
|
+
|
136
|
+
### Accounts Payable Workflow
|
137
|
+
Complete accounts payable processing with validation and database integration:
|
138
|
+
|
139
|
+
```python
|
140
|
+
# See examples/accounts_payable_smart.py for full implementation
|
141
|
+
from memra import Department, Agent
|
142
|
+
|
143
|
+
ap_department = Department(
|
144
|
+
name="Accounts Payable",
|
145
|
+
mission="Process and validate vendor invoices",
|
146
|
+
agents=[
|
147
|
+
Agent(role="Invoice Extractor", ...),
|
148
|
+
Agent(role="Data Validator", ...),
|
149
|
+
Agent(role="Database Engineer", ...)
|
150
|
+
],
|
151
|
+
workflow_order=["Invoice Extractor", "Data Validator", "Database Engineer"]
|
152
|
+
)
|
153
|
+
```
|
154
|
+
|
155
|
+
## 🛠️ Key Features
|
156
|
+
|
157
|
+
### 🔌 MCP Integration
|
158
|
+
Built-in support for Model Context Protocol (MCP) tools:
|
159
|
+
- **Database operations** (PostgreSQL, MySQL, etc.)
|
160
|
+
- **File system operations** (discovery, copying, processing)
|
161
|
+
- **API integrations** (REST, GraphQL, custom APIs)
|
162
|
+
- **Custom tool development** with simple Python functions
|
163
|
+
|
164
|
+
### 🎯 Declarative Workflows
|
165
|
+
Define workflows in terms of **what** you want to accomplish:
|
166
|
+
|
167
|
+
```python
|
168
|
+
# Instead of writing procedural code, declare your workflow
|
169
|
+
department = Department(
|
170
|
+
name="Invoice Processing",
|
171
|
+
mission="Extract, validate, and store invoice data",
|
172
|
+
agents=[
|
173
|
+
Agent(role="Extractor", job="Extract data from PDFs"),
|
174
|
+
Agent(role="Validator", job="Validate extracted data"),
|
175
|
+
Agent(role="Database Engineer", job="Store data in database")
|
176
|
+
],
|
177
|
+
workflow_order=["Extractor", "Validator", "Database Engineer"]
|
178
|
+
)
|
179
|
+
```
|
180
|
+
|
181
|
+
### 🔄 Error Handling & Recovery
|
182
|
+
Built-in resilience with:
|
183
|
+
- **Automatic retries** with configurable policies
|
184
|
+
- **Fallback agents** for critical workflows
|
185
|
+
- **Validation at each step**
|
186
|
+
- **Comprehensive error reporting**
|
187
|
+
|
188
|
+
### 📊 Monitoring & Observability
|
189
|
+
Track workflow execution with:
|
190
|
+
- **Execution traces** showing agent and tool usage
|
191
|
+
- **Performance metrics** (timing, costs)
|
192
|
+
- **Error logs** with context
|
193
|
+
- **Audit trails** for compliance
|
194
|
+
|
195
|
+
### 🚀 Production Ready
|
196
|
+
Scale from prototype to production:
|
197
|
+
- **Async execution** for high throughput
|
198
|
+
- **Resource management** and connection pooling
|
199
|
+
- **Configuration management** for different environments
|
200
|
+
- **Security best practices** for API keys and credentials
|
201
|
+
|
202
|
+
## 📚 Documentation
|
203
|
+
|
204
|
+
- **[Quick Start Guide](QUICK_START.md)** - Get up and running in 5 minutes
|
205
|
+
- **[Detailed Installation Guide](INSTALLATION_GUIDE.md)** - Complete beginner-friendly setup instructions
|
206
|
+
- **[System Architecture](memra_system_architecture.md)** - Deep dive into Memra's design
|
207
|
+
- **[Text-to-SQL Guide](TEXT_TO_SQL_USAGE_GUIDE.md)** - Building database query workflows
|
208
|
+
- **[Examples Directory](examples/)** - Complete working examples
|
209
|
+
- **[Demos Directory](demos/)** - Advanced workflow demonstrations
|
210
|
+
|
211
|
+
## 🏢 Use Cases
|
212
|
+
|
213
|
+
### Financial Services
|
214
|
+
- **Invoice processing** and accounts payable automation
|
215
|
+
- **Document classification** and routing
|
216
|
+
- **Compliance monitoring** and reporting
|
217
|
+
- **Risk assessment** and fraud detection
|
218
|
+
|
219
|
+
### Healthcare
|
220
|
+
- **Medical record processing** and data extraction
|
221
|
+
- **Claims processing** and validation
|
222
|
+
- **Patient data analysis** and insights
|
223
|
+
- **Regulatory compliance** workflows
|
224
|
+
|
225
|
+
### Manufacturing
|
226
|
+
- **Quality control** and inspection workflows
|
227
|
+
- **Supply chain** optimization and monitoring
|
228
|
+
- **Equipment maintenance** scheduling
|
229
|
+
- **Production planning** and optimization
|
230
|
+
|
231
|
+
### Retail & E-commerce
|
232
|
+
- **Order processing** and fulfillment
|
233
|
+
- **Customer service** automation
|
234
|
+
- **Inventory management** and forecasting
|
235
|
+
- **Market analysis** and trend detection
|
236
|
+
|
237
|
+
## 🤝 Contributing
|
238
|
+
|
239
|
+
We welcome contributions! Please see our [contributing guide](CONTRIBUTING.md) for details.
|
240
|
+
|
241
|
+
### Development Setup
|
242
|
+
|
243
|
+
```bash
|
244
|
+
# Clone the repository
|
245
|
+
git clone https://github.com/memra-platform/memra-sdk.git
|
246
|
+
cd memra-sdk
|
247
|
+
|
248
|
+
# Install in development mode
|
249
|
+
pip install -e .
|
250
|
+
|
251
|
+
# Run tests
|
252
|
+
pytest tests/
|
253
|
+
```
|
254
|
+
|
255
|
+
## 📄 License
|
256
|
+
|
257
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
258
|
+
|
259
|
+
### MIT License Summary
|
260
|
+
- ✅ **Commercial use** - Use in proprietary software
|
261
|
+
- ✅ **Modification** - Modify and distribute
|
262
|
+
- ✅ **Distribution** - Distribute copies
|
263
|
+
- ✅ **Private use** - Use privately
|
264
|
+
- ❌ **Liability** - No warranty provided
|
265
|
+
- ❌ **Warranty** - No warranty provided
|
266
|
+
|
267
|
+
## 🆘 Support
|
268
|
+
|
269
|
+
- **Issues**: [GitHub Issues](https://github.com/memra-platform/memra-sdk/issues)
|
270
|
+
- **Discussions**: [GitHub Discussions](https://github.com/memra-platform/memra-sdk/discussions)
|
271
|
+
- **Email**: hello@memra.com
|
272
|
+
|
273
|
+
## 🔗 Related Projects
|
274
|
+
|
275
|
+
- **[memra-workflows](https://github.com/memra-platform/memra-workflows)** - Production workflow templates
|
276
|
+
- **[memra-ops](https://github.com/memra-platform/memra-ops)** - Operations and deployment tools
|
277
|
+
|
278
|
+
---
|
279
|
+
|
280
|
+
**Built with ❤️ by the memra team**
|