merco-agents 0.1.1

package/LICENSE

@@ -0,0 +1,209 @@
+BigScience Open RAIL-M License
+dated August 18, 2022
+
+Section I: PREAMBLE
+
+This Open RAIL-M License was created by BigScience, a collaborative open innovation project aimed at
+the responsible development and use of large multilingual datasets and Large Language Models
+(“LLMs”). While a similar license was originally designed for the BLOOM model, we decided to adapt it
+and create this license in order to propose a general open and responsible license applicable to other
+machine learning based AI models (e.g. multimodal generative models).
+In short, this license strives for both the open and responsible downstream use of the accompanying
+model. When it comes to the open character, we took inspiration from open source permissive licenses
+regarding the grant of IP rights. Referring to the downstream responsible use, we added use-based
+restrictions not permitting the use of the Model in very specific scenarios, in order for the licensor to be
+able to enforce the license in case potential misuses of the Model may occur. Even though downstream
+derivative versions of the model could be released under different licensing terms, the latter will always
+have to include - at minimum - the same use-based restrictions as the ones in the original license (this
+license).
+The development and use of artificial intelligence (“AI”), does not come without concerns. The world has
+witnessed how AI techniques may, in some instances, become risky for the public in general. These risks
+come in many forms, from racial discrimination to the misuse of sensitive information.
+BigScience believes in the intersection between open and responsible AI development; thus, this License
+aims to strike a balance between both in order to enable responsible open-science in the field of AI.
+This License governs the use of the model (and its derivatives) and is informed by the model card
+associated with the model.
+
+NOW THEREFORE, You and Licensor agree as follows:
+
+1. Definitions
+(a) "License" means the terms and conditions for use, reproduction, and Distribution as defined in
+this document.
+(b) “Data” means a collection of information and/or content extracted from the dataset used with the
+Model, including to train, pretrain, or otherwise evaluate the Model. The Data is not licensed under
+this License.
+(c)“Output” means the results of operating a Model as embodied in informational content resulting
+therefrom.
+(d)“Model” means any accompanying machine-learning based assemblies (including checkpoints),
+consisting of learnt weights, parameters (including optimizer states), corresponding to the model
+architecture as embodied in the Complementary Material, that have been trained or tuned, in whole or
+in part on the Data, using the Complementary Material.
+(e) “Derivatives of the Model” means all modifications to the Model, works based on the Model, or any
+other model which is created or initialized by transfer of patterns of the weights, parameters,
+activations or output of the Model, to the other model, in order to cause the other model to perform
+similarly to the Model, including - but not limited to - distillation methods entailing the use of
+intermediate data representations or methods based on the generation of synthetic data by the Model
+for training the other model.
+(f)“Complementary Material” means the accompanying source code and scripts used to define,
+run, load, benchmark or evaluate the Model, and used to prepare data for training or evaluation, if
+any. This includes any accompanying documentation, tutorials, examples, etc, if any.
+(g) “Distribution” means any transmission, reproduction, publication or other sharing of the Model or
+Derivatives of the Model to a third party, including providing the Model as a hosted service made
+available by electronic or other remote means - e.g. API-based or web access.
+(h) “Licensor” means the copyright owner or entity authorized by the copyright owner that is
+granting the License, including the persons or entities that may have rights in the Model and/or
+distributing the Model.
+(i) "You" (or "Your") means an individual or Legal Entity exercising permissions granted by this
+License and/or making use of the Model for whichever purpose and in any field of use, including
+usage of the Model in an end-use application - e.g. chatbot, translator, image generator.
+(j) “Third Parties” means individuals or legal entities that are not under common control with
+Licensor or You.
+(k) "Contribution" means any work of authorship, including the original version of the Model and
+any modifications or additions to that Model or Derivatives of the Model thereof, that is
+intentionally submitted to Licensor for inclusion in the Model by the copyright owner or by an
+individual or Legal Entity authorized to submit on behalf of the copyright owner. For the
+purposes of this definition,
+“submitted” means any form of electronic, verbal, or written
+communication sent to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and issue tracking
+systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and
+improving the Model, but excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+(l) "Contributor" means Licensor and any individual or Legal Entity on behalf of whom a
+Contribution has been received by Licensor and subsequently incorporated within the Model.
+
+
+Section II: INTELLECTUAL PROPERTY RIGHTS
+
+Both copyright and patent grants apply to the Model, Derivatives of the Model and Complementary
+Material. The Model and Derivatives of the Model are subject to additional terms as described in Section III.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor
+hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare, publicly display, publicly perform, sublicense, and distribute the
+Complementary Material, the Model, and Derivatives of the Model.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License and where and as
+applicable, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+royalty-free, irrevocable (except as stated in this paragraph) patent license to make, have made, use, offer
+to sell, sell, import, and otherwise transfer the Model and the Complementary Material, where such
+license applies only to those patent claims licensable by such Contributor that are necessarily infringed by
+their Contribution(s) alone or by combination of their Contribution(s) with the Model to which such
+Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim
+or counterclaim in a lawsuit) alleging that the Model and/or Complementary Material or a Contribution
+incorporated within the Model and/or Complementary Material constitutes direct or contributory patent
+infringement, then any patent licenses granted to You under this License for the Model and/or Work shall
+terminate as of the date such litigation is asserted or filed.
+Section III: CONDITIONS OF USAGE, DISTRIBUTION AND REDISTRIBUTION
+
+4. Distribution and Redistribution. You may host for Third Party remote access purposes (e.g.
+software-as-a-service), reproduce and distribute copies of the Model or Derivatives of the Model thereof
+in any medium, with or without modifications, provided that You meet the following conditions:
+
+a. Use-based restrictions as referenced in paragraph 5 MUST be included as an enforceable provision
+by You in any type of legal agreement (e.g. a license) governing the use and/or distribution of the
+Model or Derivatives of the Model, and You shall give notice to subsequent users You Distribute to,
+that the Model or Derivatives of the Model are subject to paragraph 5. This provision does not apply
+to the use of Complementary Material.
+
+b. You must give any Third Party recipients of the Model or Derivatives of the Model a copy of this
+License;
+
+c. You must cause any modified files to carry prominent notices stating that You changed the files;
+
+d. You must retain all copyright, patent, trademark, and attribution notices excluding those notices
+that do not pertain to any part of the Model, Derivatives of the Model.
+You may add Your own copyright statement to Your modifications and may provide additional or
+different license terms and conditions - respecting paragraph 4.a.
+- for use, reproduction, or Distribution
+of Your modifications, or for any such Derivatives of the Model as a whole, provided Your use,
+reproduction, and Distribution of the Model otherwise complies with the conditions stated in this License.
+
+5. Use-based restrictions. The restrictions set forth in Attachment A are considered Use-based restrictions.
+Therefore You cannot use the Model and the Derivatives of the Model for the specified restricted uses. You
+may use the Model subject to this License, including only for lawful purposes and in accordance with the
+License. Use may include creating any content with, finetuning, updating, running, training, evaluating and/or
+reparametrizing the Model. You shall require all of Your users who use the Model or a Derivative of the Model
+to comply with the terms of this paragraph (paragraph 5).
+
+6. The Output You Generate. Except as set forth herein, Licensor claims no rights in the Output You
+generate using the Model. You are accountable for the Output you generate and its subsequent uses. No
+use of the output can contravene any provision as stated in the License.
+
+Section IV: OTHER PROVISIONS
+
+7. Updates and Runtime Restrictions. To the maximum extent permitted by law, Licensor reserves the
+right to restrict (remotely or otherwise) usage of the Model in violation of this License, update the Model
+through electronic means, or modify the Output of the Model based on updates. You shall undertake
+reasonable efforts to use the latest version of the Model.
+
+8. Trademarks and related. Nothing in this License permits You to make use of Licensors’ trademarks,
+trade names, logos or to otherwise suggest endorsement or misrepresent the relationship between the
+parties; and any rights not expressly granted herein are reserved by the Licensors.
+
+9. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides
+the Model and the Complementary Material (and each Contributor provides its Contributions) on an "AS
+IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
+MERCHANTABILITY , or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for
+determining the appropriateness of using or redistributing the Model, Derivatives of the Model, and the
+Complementary Material and assume any risks associated with Your exercise of permissions under this
+License.
+
+10. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or
+agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect,
+special, incidental, or consequential damages of any character arising as a result of this License or out of
+the use or inability to use the Model and the Complementary Material (including but not limited to
+damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other
+commercial damages or losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+11. Accepting Warranty or Additional Liability. While redistributing the Model, Derivatives of the
+Model and the Complementary Material thereof, You may choose to offer, and charge a fee for, acceptance
+of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License.
+However, in accepting such obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and
+hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor
+by reason of your accepting any such warranty or additional liability.
+
+12. If any provision of this License is held to be invalid, illegal or unenforceable, the remaining
+provisions shall be unaffected thereby and remain valid as if such provision had not been set forth herein.
+
+END OF TERMS AND CONDITIONS
+
+Attachment A
+
+Use Restrictions
+
+You agree not to use the Model or Derivatives of the Model:
+(a) In any way that violates any applicable national, federal, state, local or international law
+or regulation;
+(b) For the purpose of exploiting, harming or attempting to exploit or harm minors in any
+way;
+(c) To generate or disseminate verifiably false information and/or content with the purpose of
+harming others;
+(d) To generate or disseminate personal identifiable information that can be used to harm an
+individual;
+(e) To generate or disseminate information and/or content (e.g. images, code, posts, articles),
+and place the information and/or content in any context (e.g. bot generating tweets)
+without expressly and intelligibly disclaiming that the information and/or content is
+machine generated;
+(f) To defame, disparage or otherwise harass others;
+(g) To impersonate or attempt to impersonate (e.g. deepfakes) others without their consent;
+(h) For fully automated decision making that adversely impacts an individual’s legal rights or
+otherwise creates or modifies a binding, enforceable obligation;
+(i) For any use intended to or which has the effect of discriminating against or harming
+individuals or groups based on online or offline social behavior or known or predicted
+personal or personality characteristics;
+(j) To exploit any of the vulnerabilities of a specific group of persons based on their age,
+social, physical or mental characteristics, in order to materially distort the behavior of a
+person pertaining to that group in a manner that causes or is likely to cause that person or
+another person physical or psychological harm;
+(k) For any use intended to or which has the effect of discriminating against individuals or
+groups based on legally protected characteristics or categories;
+(l) To provide medical advice and medical results interpretation;
+(m) To generate or disseminate information for the purpose to be used for administration of
+justice, law enforcement, immigration or asylum processes, such as predicting an
+individual will commit fraud/crime commitment (e.g. by text profiling, drawing causal
+relationships between assertions made in documents, indiscriminate and
+arbitrarily-targeted use).

package/README.md

@@ -0,0 +1,240 @@
+# Merco-Agents
+
+A powerful Rust library for building intelligent AI agents with advanced memory capabilities, task execution, and tool integration.
+
+## 📦 **Node.js/TypeScript Support**
+
+This library provides full Node.js and TypeScript bindings, making it easy to use from JavaScript/TypeScript projects.
+
+### Installation (Local Development)
+
+Since this package is not yet published to npm, use one of these methods:
+
+**Option 1: Local Path** (Recommended)
+```json
+// In your project's package.json
+{
+  "dependencies": {
+    "merco-agents": "file:../merco-agents"
+  }
+}
+```
+
+**Option 2: npm link**
+```bash
+# In merco-agents directory
+npm link
+
+# In your project
+npm link merco-agents
+```
+
+**See [LOCAL_USAGE.md](./LOCAL_USAGE.md) for detailed local installation instructions.**
+
+### Quick Start (TypeScript/JavaScript)
+
+```typescript
+import { createAgent } from 'merco-agents';
+
+const agent = await createAgent({
+  name: 'My Assistant',
+  provider: 'openai',
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4',
+});
+
+const response = await agent.call('What is 2+2?');
+console.log(response.content);
+```
+
+**See [QUICK_START.md](./QUICK_START.md) for more examples.**
+
+**For other services/repositories**: See [USAGE.md](./USAGE.md) for complete documentation on using this library in your projects.
+
+**Architecture**: See [ARCHITECTURE.md](./ARCHITECTURE.md) for details on the codebase structure.
+
+## 🧠 **NEW: Memory-Enabled Agents**
+
+Merco-Agents now features a comprehensive memory system that allows agents to:
+
+- **Remember user interactions** across sessions
+- **Learn from successes and failures** to improve over time
+- **Provide personalized responses** based on user history  
+- **Use multiple memory types** (Working, Semantic, Episodic, Procedural)
+- **Automatically store and retrieve context** for better conversations
+
+### Quick Start with Memory
+
+```rust
+use merco_agents::agent::agent::{Agent, AgentLLMConfig, AgentMemoryConfig};
+use merco_agents::memory::config::{MemoryConfig, EmbeddingProvider, StorageBackend};
+
+// Create an agent with memory capabilities
+let memory_config = AgentMemoryConfig::new()
+    .with_auto_store(true)     // Automatically remember interactions
+    .with_auto_retrieve(true)  // Use memory for context
+    .with_context_limit(5);    // Max memories per response
+
+let mut agent = Agent::with_memory(
+    llm_config,
+    "You are a helpful assistant with memory".to_string(),
+    vec!["Remember user preferences".to_string()],
+    vec![], // tools
+    memory_config
+);
+
+// The agent automatically remembers this interaction
+let result = agent.call_with_user(task, Some("user_123".to_string())).await?;
+
+// Later conversations will use previous context
+let followup = agent.call_with_user(followup_task, Some("user_123".to_string())).await?;
+```
+
+### Memory System Features
+
+| Feature | Description | Use Case |
+|---------|-------------|----------|
+| **Working Memory** | Short-term conversation context | Chat continuity, current session |
+| **Semantic Memory** | Facts and knowledge | User preferences, learned information |
+| **Episodic Memory** | Past experiences and interactions | User history, previous conversations |
+| **Procedural Memory** | Skills and processes | How-to knowledge, best practices |
+
+### Memory Configuration Options
+
+```rust
+// Default configuration (recommended for most use cases)
+let agent = Agent::new(llm_config, backstory, goals, tools);
+
+// Performance mode (no memory)
+let agent = Agent::new_without_memory(llm_config, backstory, goals, tools);
+
+// Custom memory configuration
+let memory_config = MemoryConfig {
+    embedding: EmbeddingProvider::HuggingFace,  // or OpenAI, Ollama, Custom
+    storage: StorageBackend::SQLiteInMemory,    // or PostgreSQL, Qdrant
+    limits: MemoryLimits {
+        max_working_memory_messages: 50,
+        max_retrieval_results: 10,
+        similarity_threshold: 0.7,
+        // ... other settings
+    },
+};
+
+let agent_config = AgentMemoryConfig::new()
+    .with_memory_config(memory_config)
+    .with_auto_store(true)
+    .with_auto_retrieve(true);
+
+let agent = Agent::with_memory(llm_config, backstory, goals, tools, agent_config);
+```
+
+### Manual Memory Management
+
+```rust
+// Store facts for the agent to remember
+agent.learn_fact(
+    "User prefers JSON responses over plain text".to_string(),
+    Some("preferences".to_string()),
+    Some(0.9) // importance score
+).await?;
+
+// Teach procedures
+agent.learn_procedure(
+    "How to format code examples".to_string(),
+    vec![
+        "Use proper syntax highlighting".to_string(),
+        "Include comments explaining key parts".to_string(),
+        "Provide a brief explanation".to_string(),
+    ],
+    Some("coding".to_string())
+).await?;
+
+// Store specific experiences
+agent.store_memory(
+    "User had trouble with async/await concepts".to_string(),
+    MemoryType::Episodic,
+    Some("user_123".to_string()),
+    Some(metadata)
+).await?;
+
+// Query memories manually
+let memories = agent.retrieve_memories(
+    "async programming difficulties",
+    Some("user_123".to_string()),
+    "educational context"
+).await?;
+```
+
+## 🚀 Features
+
+- **Intelligent Agents**: Create AI agents with custom backstories, goals, and capabilities
+- **Memory System**: Advanced memory capabilities with multiple storage backends
+- **Task Execution**: Structured task handling with validation and retry logic
+- **Tool Integration**: Easy integration with external tools and APIs
+- **JSON Validation**: Robust JSON output validation with schema support
+- **Crew Workflows**: Coordinate multiple agents in sequential or hierarchical workflows
+- **Embedding Support**: Multiple embedding providers (OpenAI, Ollama, HuggingFace, Custom)
+- **Storage Backends**: SQLite, PostgreSQL, Qdrant, and in-memory options
+
+## Examples
+
+The `examples/` directory contains comprehensive demonstrations:
+
+- **`agent_with_memory.rs`**: Complete memory system showcase
+- **`memory_demo.rs`**: Memory types and storage backends
+- **`basic_agent/`**: Simple agent interactions  
+- **`json_validation/`**: JSON output validation
+- **`tool_usage/`**: Custom tool integration
+
+Run examples with:
+```bash
+cargo run --example agent_with_memory
+cargo run --example memory_demo
+```
+
+## Architecture
+
+### Agent System
+- **Agent**: Core agent with configurable memory capabilities
+- **Task**: Structured task execution with validation
+- **Tool**: External function integration
+- **Crew**: Multi-agent coordination
+
+### Memory System  
+- **Memory Manager**: Intelligent memory storage and retrieval
+- **Storage Backends**: Pluggable storage (SQLite, PostgreSQL, Qdrant)
+- **Embedding Providers**: Multiple embedding options
+- **Memory Types**: Working, Semantic, Episodic, Procedural
+
+## Configuration
+
+Set up your environment:
+
+```bash
+# Required
+export OPENROUTER_API_KEY="your-api-key"
+
+# Optional memory configurations
+export SQLITE_PATH="./agent_memory.db"
+export QDRANT_URL="http://localhost:6333" 
+export OLLAMA_URL="http://localhost:11434"
+```
+
+## Benefits of Memory-Enabled Agents
+
+✅ **Personalization**: Agents remember user preferences and adapt responses  
+✅ **Continuous Learning**: Improve performance through experience  
+✅ **Context Awareness**: Better conversations with relevant context  
+✅ **User Relationships**: Build long-term relationships with users  
+✅ **Error Learning**: Learn from mistakes to avoid future errors  
+✅ **Knowledge Retention**: Preserve important information across sessions  
+
+## Use Cases
+
+- **Customer Support**: Remember customer history and preferences
+- **Educational Tutors**: Track learning progress and adapt explanations  
+- **Personal Assistants**: Learn user habits and preferences
+- **Code Assistants**: Remember project context and coding patterns
+- **Content Creation**: Maintain consistent voice and style preferences
+
+This memory system transforms simple chatbots into intelligent agents that truly understand and adapt to their users! 🧠✨