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.
Files changed (76) hide show
  1. memra-0.2.5/CHANGELOG.md +63 -0
  2. memra-0.2.5/LICENSE +21 -0
  3. memra-0.2.5/PKG-INFO +319 -0
  4. memra-0.2.5/README.md +280 -0
  5. memra-0.2.5/mcp_bridge_server.py +1178 -0
  6. memra-0.2.5/memra/__init__.py +45 -0
  7. memra-0.2.5/memra/cli.py +286 -0
  8. memra-0.2.5/memra/discovery.py +15 -0
  9. memra-0.2.5/memra/discovery_client.py +49 -0
  10. memra-0.2.5/memra/execution.py +662 -0
  11. memra-0.2.5/memra/models.py +100 -0
  12. memra-0.2.5/memra/tool_registry.py +351 -0
  13. memra-0.2.5/memra/tool_registry_client.py +106 -0
  14. memra-0.2.5/memra-ops/app.py +808 -0
  15. memra-0.2.5/memra-ops/config/config.py +25 -0
  16. memra-0.2.5/memra-ops/config.py +34 -0
  17. memra-0.2.5/memra-ops/logic/__init__.py +1 -0
  18. memra-0.2.5/memra-ops/logic/file_tools.py +43 -0
  19. memra-0.2.5/memra-ops/logic/invoice_tools.py +668 -0
  20. memra-0.2.5/memra-ops/logic/invoice_tools_fix.py +66 -0
  21. memra-0.2.5/memra-ops/mcp_bridge_server.py +1178 -0
  22. memra-0.2.5/memra-ops/scripts/check_database.py +37 -0
  23. memra-0.2.5/memra-ops/scripts/clear_database.py +48 -0
  24. memra-0.2.5/memra-ops/scripts/monitor_database.py +67 -0
  25. memra-0.2.5/memra-ops/scripts/release.py +133 -0
  26. memra-0.2.5/memra-ops/scripts/reset_database.py +65 -0
  27. memra-0.2.5/memra-ops/scripts/start_memra.py +334 -0
  28. memra-0.2.5/memra-ops/scripts/stop_memra.py +132 -0
  29. memra-0.2.5/memra-ops/server_tool_registry.py +190 -0
  30. memra-0.2.5/memra-ops/tests/test_llm_text_to_sql.py +115 -0
  31. memra-0.2.5/memra-ops/tests/test_llm_vs_pattern.py +130 -0
  32. memra-0.2.5/memra-ops/tests/test_mcp_schema_aware.py +124 -0
  33. memra-0.2.5/memra-ops/tests/test_schema_aware_sql.py +139 -0
  34. memra-0.2.5/memra-ops/tests/test_schema_aware_sql_simple.py +66 -0
  35. memra-0.2.5/memra-ops/tests/test_text_to_sql_demo.py +140 -0
  36. memra-0.2.5/memra-ops/tools/mcp_bridge_server.py +851 -0
  37. memra-0.2.5/memra-sdk/examples/accounts_payable.py +215 -0
  38. memra-0.2.5/memra-sdk/examples/accounts_payable_client.py +217 -0
  39. memra-0.2.5/memra-sdk/examples/accounts_payable_mcp.py +200 -0
  40. memra-0.2.5/memra-sdk/examples/ask_questions.py +123 -0
  41. memra-0.2.5/memra-sdk/examples/invoice_processing.py +116 -0
  42. memra-0.2.5/memra-sdk/examples/propane_delivery.py +87 -0
  43. memra-0.2.5/memra-sdk/examples/simple_text_to_sql.py +158 -0
  44. {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/__init__.py +1 -1
  45. memra-0.2.5/memra-sdk/scripts/release.py +133 -0
  46. {memra-0.2.3 → memra-0.2.5/memra-sdk}/setup.py +1 -1
  47. memra-0.2.5/memra-workflows/accounts_payable/accounts_payable.py +215 -0
  48. memra-0.2.5/memra-workflows/accounts_payable/accounts_payable_client.py +216 -0
  49. memra-0.2.5/memra-workflows/accounts_payable/accounts_payable_mcp.py +200 -0
  50. memra-0.2.5/memra-workflows/accounts_payable/accounts_payable_smart.py +221 -0
  51. memra-0.2.5/memra-workflows/invoice_processing/invoice_processing.py +116 -0
  52. memra-0.2.5/memra-workflows/invoice_processing/smart_invoice_processor.py +220 -0
  53. memra-0.2.5/memra-workflows/logic/__init__.py +1 -0
  54. memra-0.2.5/memra-workflows/logic/file_tools.py +50 -0
  55. memra-0.2.5/memra-workflows/logic/invoice_tools.py +501 -0
  56. memra-0.2.5/memra-workflows/logic/propane_agents.py +52 -0
  57. memra-0.2.5/memra-workflows/mcp_bridge_server.py +230 -0
  58. memra-0.2.5/memra-workflows/propane_delivery/propane_delivery.py +87 -0
  59. memra-0.2.5/memra-workflows/text_to_sql/complete_invoice_workflow_with_queries.py +208 -0
  60. memra-0.2.5/memra-workflows/text_to_sql/complete_text_to_sql_system.py +266 -0
  61. memra-0.2.5/memra-workflows/text_to_sql/file_discovery_demo.py +156 -0
  62. memra-0.2.5/memra.egg-info/SOURCES.txt +70 -0
  63. {memra-0.2.3 → memra-0.2.5}/pyproject.toml +2 -2
  64. memra-0.2.5/requirements.txt +6 -0
  65. memra-0.2.5/setup.py +52 -0
  66. memra-0.2.3/PKG-INFO +0 -101
  67. memra-0.2.3/README.md +0 -64
  68. memra-0.2.3/memra.egg-info/SOURCES.txt +0 -11
  69. {memra-0.2.3 → memra-0.2.5}/MANIFEST.in +0 -0
  70. {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/discovery.py +0 -0
  71. {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/discovery_client.py +0 -0
  72. {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/execution.py +0 -0
  73. {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/models.py +0 -0
  74. {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/tool_registry.py +0 -0
  75. {memra-0.2.3 → memra-0.2.5/memra-sdk}/memra/tool_registry_client.py +0 -0
  76. {memra-0.2.3 → memra-0.2.5}/setup.cfg +0 -0
@@ -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
+ [![PyPI version](https://badge.fury.io/py/memra.svg)](https://badge.fury.io/py/memra)
45
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
46
+ [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](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
+ [![PyPI version](https://badge.fury.io/py/memra.svg)](https://badge.fury.io/py/memra)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
+ [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](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**