amsdal_ml 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

amsdal_ml/__about__.py

@@ -1 +1 @@
-__version__ = '0.1.3'
+__version__ = '0.1.4'

amsdal_ml/agents/retriever_tool.py

@@ -27,7 +27,16 @@ class RetrieverArgs(BaseModel):
     exclude_tags: Optional[list[str]] = None
 
 
-_retriever = OpenAIRetriever()
+class _RetrieverSingleton:
+    """Singleton holder for lazy retriever initialization."""
+    _instance: Optional[OpenAIRetriever] = None
+
+    @classmethod
+    def get(cls) -> OpenAIRetriever:
+        """Lazy initialization of retriever to ensure env vars are loaded."""
+        if cls._instance is None:
+            cls._instance = OpenAIRetriever()
+        return cls._instance
 
 
 async def retriever_search(
@@ -39,7 +48,8 @@ async def retriever_search(
     logging.info(
         f"retriever_search called with query={query}, k={k}, include_tags={include_tags}, exclude_tags={exclude_tags}"
     )
-    chunks = await _retriever.asimilarity_search(
+    retriever = _RetrieverSingleton.get()
+    chunks = await retriever.asimilarity_search(
         query=query,
         k=k,
         include_tags=include_tags,

amsdal_ml/mcp_client/stdio_client.py

@@ -94,7 +94,7 @@ class StdioClient(ToolClient):
 
         if not self._persist:
             async with AsyncExitStack() as stack:
-                params = StdioServerParameters(command=self._command, args=self._args)
+                params = StdioServerParameters(command=self._command, args=self._args, env=os.environ.copy())
                 rx, tx = await stack.enter_async_context(stdio_client(params))
                 s = await stack.enter_async_context(ClientSession(rx, tx))
                 await s.initialize()
@@ -123,7 +123,7 @@ class StdioClient(ToolClient):
     async def call(self, tool_name: str, args: dict[str, Any], *, timeout: float | None = None) -> Any:
         if not self._persist:
             async with AsyncExitStack() as stack:
-                params = StdioServerParameters(command=self._command, args=self._args)
+                params = StdioServerParameters(command=self._command, args=self._args, env=os.environ.copy())
                 rx, tx = await stack.enter_async_context(stdio_client(params))
                 s = await stack.enter_async_context(ClientSession(rx, tx))
                 await s.initialize()

amsdal_ml-0.1.4.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: amsdal_ml
+Version: 0.1.4
+Summary: amsdal_ml plugin for AMSDAL Framework
+Requires-Python: >=3.11
+Requires-Dist: aiohttp==3.12.15
+Requires-Dist: amsdal-cli>=0.5.7
+Requires-Dist: amsdal-data>=0.5.9
+Requires-Dist: amsdal-models>=0.5.9
+Requires-Dist: amsdal-utils>=0.5.4
+Requires-Dist: amsdal>=0.5.6
+Requires-Dist: mcp>=0.1
+Requires-Dist: openai==1.100.2
+Requires-Dist: pydantic-settings==2.10.1
+Requires-Dist: pydantic==2.11.7
+Description-Content-Type: text/markdown
+
+# AMSDAL ML
+
+[![CI](https://github.com/amsdal/amsdal_ml/actions/workflows/ci.yml/badge.svg)](https://github.com/amsdal/amsdal_ml/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+Machine learning plugin for the AMSDAL Framework, providing embeddings, vector search, semantic retrieval, and AI agents with support for OpenAI models.
+
+## Features
+
+- **Vector Embeddings**: Generate and store embeddings for any AMSDAL model with automatic chunking
+- **Semantic Search**: Query your data using natural language with tag-based filtering
+- **AI Agents**: Build Q&A systems with streaming support and citation tracking
+- **Async-First**: Optimized for high-performance async operations
+- **MCP Integration**: Expose and consume tools via Model Context Protocol (stdio/HTTP)
+- **File Attachments**: Process and embed documents with built-in loaders
+- **Extensible**: Abstract base classes for custom models, retrievers, and ingesters
+
+## Installation
+
+```bash
+pip install amsdal-ml
+```
+
+### Requirements
+
+- Python 3.11 or higher
+- AMSDAL Framework 0.5.6+
+- OpenAI API key (for default implementations)
+
+## Quick Start
+
+### 1. Configuration
+
+Create a `.env` file in your project root:
+
+```env
+OPENAI_API_KEY=sk-your-api-key-here
+async_mode=true
+ml_model_class=amsdal_ml.ml_models.openai_model.OpenAIModel
+ml_retriever_class=amsdal_ml.ml_retrievers.openai_retriever.OpenAIRetriever
+ml_ingesting_class=amsdal_ml.ml_ingesting.openai_ingesting.OpenAIIngesting
+```
+
+Create a `config.yml` for AMSDAL connections:
+
+```yaml
+application_name: my-ml-app
+async_mode: true
+connections:
+  - name: sqlite_state
+    backend: sqlite-state-async
+    credentials:
+      - db_path: ./warehouse/state.sqlite3
+      - check_same_thread: false
+  - name: lock
+    backend: amsdal_data.lock.implementations.thread_lock.ThreadLock
+resources_config:
+  repository:
+    default: sqlite_state
+  lock: lock
+```
+
+### 2. Generate Embeddings
+
+```python
+from amsdal_ml.ml_ingesting.openai_ingesting import OpenAIIngesting
+from amsdal_ml.ml_config import ml_config
+
+# Initialize ingesting
+ingester = OpenAIIngesting(
+    model=MyModel,
+    embedding_field='embedding',
+)
+
+# Generate embeddings for an instance
+instance = MyModel(content='Your text here')
+embeddings = await ingester.agenerate_embeddings(instance)
+await ingester.asave(embeddings, instance)
+```
+
+### 3. Semantic Search
+
+```python
+from amsdal_ml.ml_retrievers.openai_retriever import OpenAIRetriever
+
+retriever = OpenAIRetriever()
+
+# Search for relevant content
+results = await retriever.asimilarity_search(
+    query='What is machine learning?',
+    k=5,
+    include_tags=['documentation']
+)
+
+for chunk in results:
+    print(f'{chunk.object_class}:{chunk.object_id} - {chunk.raw_text}')
+```
+
+### 4. Build an AI Agent
+
+```python
+from amsdal_ml.agents.default_qa_agent import DefaultQAAgent
+
+agent = DefaultQAAgent()
+
+# Ask questions
+output = await agent.arun('Explain vector embeddings')
+print(output.answer)
+print(f'Used tools: {output.used_tools}')
+
+# Stream responses
+async for chunk in agent.astream('What is semantic search?'):
+    print(chunk, end='', flush=True)
+```
+
+## Architecture
+
+### Core Components
+
+- **`MLModel`**: Abstract interface for LLM inference (invoke, stream, with attachments)
+- **`MLIngesting`**: Generate text and embeddings from data objects with chunking
+- **`MLRetriever`**: Semantic similarity search with tag-based filtering
+- **`Agent`**: Q&A and task-oriented agents with streaming and citations
+- **`EmbeddingModel`**: Database model storing 1536-dimensional vectors linked to source objects
+- **MCP Server/Client**: Expose retrievers as tools or consume external MCP services
+
+### Configuration
+
+All settings are managed via `MLConfig` in `.env`:
+
+```env
+# Model Configuration
+llm_model_name=gpt-4o
+llm_temperature=0.0
+embed_model_name=text-embedding-3-small
+
+# Chunking Parameters
+embed_max_depth=2
+embed_max_chunks=10
+embed_max_tokens_per_chunk=800
+
+# Retrieval Settings
+retriever_default_k=8
+```
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+pip install --upgrade uv hatch==1.14.2
+hatch env create
+hatch run sync
+```
+
+### Testing
+
+```bash
+# Run all tests with coverage
+hatch run cov
+
+# Run specific tests
+hatch run test tests/test_openai_model.py
+
+# Watch mode
+pytest tests/ -v
+```
+
+### Code Quality
+
+```bash
+# Run all checks (style + typing)
+hatch run all
+
+# Format code
+hatch run fmt
+
+# Type checking
+hatch run typing
+```
+
+### AMSDAL CLI
+
+```bash
+# Generate a new model
+amsdal generate model MyModel --format py
+
+# Generate property
+amsdal generate property --model MyModel embedding_field
+
+# Generate transaction
+amsdal generate transaction ProcessEmbeddings
+
+# Generate hook
+amsdal generate hook --model MyModel on_create
+```
+
+## MCP Server
+
+Run the retriever as an MCP server for integration with Claude Desktop or other MCP clients:
+
+```bash
+python -m amsdal_ml.mcp_server.server_retriever_stdio \
+  --amsdal-config "$(echo '{"async_mode": true, ...}' | base64)"
+```
+
+The server exposes a `search` tool for semantic search in your knowledge base.
+
+## License
+
+See `amsdal_ml/Third-Party Materials - AMSDAL Dependencies - License Notices.md` for dependency licenses.
+
+## Links
+
+- [AMSDAL Framework](https://github.com/amsdal/amsdal)
+- [Documentation](https://docs.amsdal.com)
+- [Issue Tracker](https://github.com/amsdal/amsdal_ml/issues)

{amsdal_ml-0.1.3.dist-info → amsdal_ml-0.1.4.dist-info}/RECORD

@@ -1,5 +1,5 @@
 amsdal_ml/Third-Party Materials - AMSDAL Dependencies - License Notices.md,sha256=0A3jjw91I-NaTHXCw8IQiKUdFJgVavhgHaFX4Nag4jk,81658
-amsdal_ml/__about__.py,sha256=uZsygMXMKRw-7qhWojAjnpm8GFPXU92xW6XA8O5GwFY,22
+amsdal_ml/__about__.py,sha256=aBEbDvx4LMg8A1TJJR6dEHu8rQODVin528hLS_EDvuA,22
 amsdal_ml/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 amsdal_ml/app.py,sha256=K_lUz37_FUQmPwzDakDhVXA_D2SL9z1JtcuHfuBvlKE,184
 amsdal_ml/ml_config.py,sha256=UONMVG2RbKVbaYF-GdlhRQbm8flp52GxBzfqdzuLZ5w,1788
@@ -7,7 +7,7 @@ amsdal_ml/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 amsdal_ml/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 amsdal_ml/agents/agent.py,sha256=L00RTIkopdGnJp_NctEtWRXAgWy1DAn7AEg0rMoXdJw,1514
 amsdal_ml/agents/default_qa_agent.py,sha256=MjrA5XYOKe5PwfSnkoeGmEnC8mP9asRHGHPHd1oPH6g,14017
-amsdal_ml/agents/retriever_tool.py,sha256=SqIGqYi_xMcm_MgLcwdMW2ALzYphkk02KBevH8n-Op0,1850
+amsdal_ml/agents/retriever_tool.py,sha256=ND4lm1I4ncWWSQBQlYYP1EpNBfwTbdy89FaTvMzLARU,2239
 amsdal_ml/agents/promts/__init__.py,sha256=3AKR3lrV067CO03XYFDmAKJv0x2oqSTcVeDIqNwoAu0,1571
 amsdal_ml/agents/promts/react_chat.prompt,sha256=EArdA102sSBOWchhub1QoaKws_DVpMqDflc5htBkFKI,1762
 amsdal_ml/fileio/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -16,7 +16,7 @@ amsdal_ml/fileio/openai_loader.py,sha256=4YyxK5pBAnRm55et5yMu6X5OdK2kWTqpuPF1E2-
 amsdal_ml/mcp_client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 amsdal_ml/mcp_client/base.py,sha256=cNuHHCSSND4BkIyhQZ-1mJLPp630wTCtiCQSHnK2zmA,441
 amsdal_ml/mcp_client/http_client.py,sha256=2fFCaubp_cFeyCqN9CP7bVLTp4UIIEhJPq9BVHBf6-w,1719
-amsdal_ml/mcp_client/stdio_client.py,sha256=F5Y2yGFNDCE7Nfg_6QMCkp81Vb4uS2UQ1XnD_FTGM8U,5777
+amsdal_ml/mcp_client/stdio_client.py,sha256=i-xI7ROMOV-HKRYVUw-PZR0kYEdQbZfO0E9eteiBaPQ,5823
 amsdal_ml/mcp_server/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 amsdal_ml/mcp_server/server_retriever_stdio.py,sha256=iUQNwWEDZE0OIS9vyTyJp_EOn4kvl9Gn0Okzcq-ymo0,1762
 amsdal_ml/migrations/0000_initial.py,sha256=UeEtqHrCgmTQyGnyV2jC7yt9Ce7Xm0-MyhOQU3rRrs8,1633
@@ -34,6 +34,6 @@ amsdal_ml/ml_retrievers/openai_retriever.py,sha256=oY71oPJdFuECWaJL_ByKZFE7HRJ-S
 amsdal_ml/ml_retrievers/retriever.py,sha256=zHvaAOAD6H4IaIaYA_wy2e8tMmGtOnyNsDS2B4dQjBU,1005
 amsdal_ml/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 amsdal_ml/models/embedding_model.py,sha256=mdMSYHrkSIKHi5mg4HqMaTTiPGqLYtRdRkbEK_trFWw,774
-amsdal_ml-0.1.3.dist-info/METADATA,sha256=BETzPNugrsUz-RL3yG-2I-4I_WBSLkJ5oRJYxyZxEDY,1676
-amsdal_ml-0.1.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-amsdal_ml-0.1.3.dist-info/RECORD,,
+amsdal_ml-0.1.4.dist-info/METADATA,sha256=F4dsbTo3XU-fJ3v1FX8BjimB0lB_B54Nl6gUF0tp2hk,5890
+amsdal_ml-0.1.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+amsdal_ml-0.1.4.dist-info/RECORD,,

amsdal_ml-0.1.3.dist-info/METADATA

@@ -1,69 +0,0 @@
-Metadata-Version: 2.4
-Name: amsdal_ml
-Version: 0.1.3
-Summary: amsdal_ml plugin for AMSDAL Framework
-Requires-Python: >=3.11
-Requires-Dist: aiohttp==3.12.15
-Requires-Dist: amsdal-cli>=0.5.7
-Requires-Dist: amsdal-data>=0.5.9
-Requires-Dist: amsdal-models>=0.5.9
-Requires-Dist: amsdal-utils>=0.5.4
-Requires-Dist: amsdal>=0.5.6
-Requires-Dist: mcp>=0.1
-Requires-Dist: openai==1.100.2
-Requires-Dist: pydantic-settings==2.10.1
-Requires-Dist: pydantic==2.11.7
-Description-Content-Type: text/markdown
-
-# amsdal-ml
-
-This plugin extends the AMSDAL Framework with machine learning utilities, 
-including custom models for embeddings, properties for ML metadata, and 
-hooks for working with vector search and AI-driven features.
-
-## Plugin Structure
-
-- `src/models/` - Contains model definitions in Python format
-- `src/transactions/` - Contains transaction definitions
-- `pyproject.toml` - Plugin configuration file
-- `config.yml` - Configuration for connections
-
-## Installing this Plugin
-
-To use this plugin in an AMSDAL application:
-
-1. Copy the plugin directory to your AMSDAL application
-2. Import the models and transactions as needed
-3. Register the plugin in your application configuration
-
-## Development
-
-This plugin uses sync mode.
-
-### Adding Models
-
-```bash
-amsdal generate model ModelName --format py
-```
-
-### Adding Properties
-
-```bash
-amsdal generate property --model ModelName property_name
-```
-
-### Adding Transactions
-
-```bash
-amsdal generate transaction TransactionName
-```
-
-### Adding Hooks
-
-```bash
-amsdal generate hook --model ModelName on_create
-```
-
-## Testing
-
-Test your plugin by integrating it with an AMSDAL application and running the application's test suite.