rakam-systems-core 0.1.1rc7__tar.gz

rakam_systems_core-0.1.1rc7/.gitignore

@@ -0,0 +1,46 @@
+# Python specific
+*.pyc
+*.pyo
+*.pyd
+__pycache__/
+.pytest_cache/
+*.so
+
+# Environments
+.env
+*.env
+*.venv*
+venv/
+*venv/
+ENV/
+env/
+env.bak/
+venv.bak/
+
+# VS Code
+.vscode/
+.vscode/*
+
+# PyCharm
+.idea/
+.idea/*
+
+# OS specific
+.DS_Store
+Thumbs.db
+
+#data
+data/
+dist/
+logs/
+
+# Build artifacts
+*.egg-info/
+
+# tracking data
+agent_tracking/
+
+# docs
+docs/
+
+temp_path/

rakam_systems_core-0.1.1rc7/.python-version

@@ -0,0 +1 @@
+3.11

rakam_systems_core-0.1.1rc7/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: rakam-systems-core
+Version: 0.1.1rc7
+Summary: A Package containing core logic and schema for rakam-systems
+Author-email: Mohamed Hilel <mohammedjassemhlel@gmail.com>, Peng Zheng <pengzheng990630@outlook.com>, somebodyawesome-dev <luckynoob2011830@gmail.com>
+Requires-Python: >=3.10
+Requires-Dist: boto3>=1.26.0
+Requires-Dist: pydantic
+Description-Content-Type: text/markdown
+
+# Rakam System Core
+
+The core package of Rakam Systems providing foundational interfaces, base components, and utilities.
+
+## Overview
+
+`rakam-system-core` is the foundation of the Rakam Systems framework. It provides:
+
+- **Base Component**: Abstract base class with lifecycle management
+- **Interfaces**: Standard interfaces for agents, tools, vector stores, embeddings, and loaders
+- **Configuration System**: YAML/JSON configuration loading and validation
+- **Tracking System**: Input/output tracking for debugging and evaluation
+- **Logging Utilities**: Structured logging with color support
+
+This package is required by both `rakam-system-agent` and `rakam-systems-vectorstore`.
+
+## Installation
+
+```bash
+pip install -e ./rakam-system-core
+```
+
+## Key Components
+
+### BaseComponent
+
+All components extend `BaseComponent` which provides:
+
+- Lifecycle management with `setup()` and `shutdown()` methods
+- Auto-initialization via `__call__`
+- Context manager support
+- Built-in evaluation harness
+
+```python
+from rakam_systems_core.ai_core.base import BaseComponent
+
+class MyComponent(BaseComponent):
+    def setup(self):
+        super().setup()
+        # Initialize resources
+
+    def shutdown(self):
+        # Clean up resources
+        super().shutdown()
+
+    def run(self, *args, **kwargs):
+        # Main logic
+        pass
+```
+
+### Interfaces
+
+Standard interfaces for building AI systems:
+
+- **AgentComponent**: AI agents with sync/async support
+- **ToolComponent**: Callable tools for agents
+- **LLMGateway**: LLM provider abstraction
+- **VectorStore**: Vector storage interface
+- **EmbeddingModel**: Text embedding interface
+- **Loader**: Document loading interface
+- **Chunker**: Text chunking interface
+
+```python
+from rakam_systems_core.ai_core.interfaces.agent import AgentComponent
+from rakam_systems_core.ai_core.interfaces.tool import ToolComponent
+from rakam_systems_core.ai_core.interfaces.vectorstore import VectorStore
+```
+
+### Configuration System
+
+Load and validate configurations from YAML files:
+
+```python
+from rakam_systems_core.ai_core.config_loader import ConfigurationLoader
+
+loader = ConfigurationLoader()
+config = loader.load_from_yaml("agent_config.yaml")
+agent = loader.create_agent("my_agent", config)
+```
+
+### Tracking System
+
+Track inputs and outputs for debugging:
+
+```python
+from rakam_systems_core.ai_core.tracking import TrackingMixin
+
+class MyAgent(TrackingMixin, BaseAgent):
+    pass
+
+agent.enable_tracking(output_dir="./tracking")
+# Use agent...
+agent.export_tracking_data(format='csv')
+```
+
+## Package Structure
+
+```
+rakam-system-core/
+├── src/rakam_systems_core/
+│   ├── ai_core/
+│   │   ├── base.py              # BaseComponent
+│   │   ├── interfaces/          # Standard interfaces
+│   │   ├── config_loader.py     # Configuration system
+│   │   ├── tracking.py          # I/O tracking
+│   │   └── mcp/                 # MCP server support
+│   └── ai_utils/
+│       └── logging.py           # Logging utilities
+└── pyproject.toml
+```
+
+## Usage in Other Packages
+
+### Agent Package
+
+```python
+# rakam-system-agent uses core interfaces
+from rakam_systems_core.ai_core.interfaces.agent import AgentComponent
+from rakam_system_agent import BaseAgent
+
+agent = BaseAgent(name="my_agent", model="openai:gpt-4o")
+```
+
+### Vectorstore Package
+
+```python
+# rakam-systems-vectorstore uses core interfaces
+from rakam_systems_core.ai_core.interfaces.vectorstore import VectorStore
+from rakam_systems_vectorstore import ConfigurablePgVectorStore
+
+store = ConfigurablePgVectorStore(config=config)
+```
+
+## Development
+
+This package contains only interfaces and utilities. To contribute:
+
+1. Install in editable mode: `pip install -e ./rakam-system-core`
+2. Make changes to interfaces or utilities
+3. Ensure backward compatibility with agent and vectorstore packages
+4. Update version in `pyproject.toml`
+
+## License
+
+Apache 2.0
+
+## Links
+
+- [Main Repository](https://github.com/Rakam-AI/rakam-systems)
+- [Documentation](../docs/)
+- [Agent Package](../rakam-system-agent/)
+- [Vectorstore Package](../rakam-systems-vectorstore/)

rakam_systems_core-0.1.1rc7/README.md

@@ -0,0 +1,152 @@
+# Rakam System Core
+
+The core package of Rakam Systems providing foundational interfaces, base components, and utilities.
+
+## Overview
+
+`rakam-system-core` is the foundation of the Rakam Systems framework. It provides:
+
+- **Base Component**: Abstract base class with lifecycle management
+- **Interfaces**: Standard interfaces for agents, tools, vector stores, embeddings, and loaders
+- **Configuration System**: YAML/JSON configuration loading and validation
+- **Tracking System**: Input/output tracking for debugging and evaluation
+- **Logging Utilities**: Structured logging with color support
+
+This package is required by both `rakam-system-agent` and `rakam-systems-vectorstore`.
+
+## Installation
+
+```bash
+pip install -e ./rakam-system-core
+```
+
+## Key Components
+
+### BaseComponent
+
+All components extend `BaseComponent` which provides:
+
+- Lifecycle management with `setup()` and `shutdown()` methods
+- Auto-initialization via `__call__`
+- Context manager support
+- Built-in evaluation harness
+
+```python
+from rakam_systems_core.ai_core.base import BaseComponent
+
+class MyComponent(BaseComponent):
+    def setup(self):
+        super().setup()
+        # Initialize resources
+
+    def shutdown(self):
+        # Clean up resources
+        super().shutdown()
+
+    def run(self, *args, **kwargs):
+        # Main logic
+        pass
+```
+
+### Interfaces
+
+Standard interfaces for building AI systems:
+
+- **AgentComponent**: AI agents with sync/async support
+- **ToolComponent**: Callable tools for agents
+- **LLMGateway**: LLM provider abstraction
+- **VectorStore**: Vector storage interface
+- **EmbeddingModel**: Text embedding interface
+- **Loader**: Document loading interface
+- **Chunker**: Text chunking interface
+
+```python
+from rakam_systems_core.ai_core.interfaces.agent import AgentComponent
+from rakam_systems_core.ai_core.interfaces.tool import ToolComponent
+from rakam_systems_core.ai_core.interfaces.vectorstore import VectorStore
+```
+
+### Configuration System
+
+Load and validate configurations from YAML files:
+
+```python
+from rakam_systems_core.ai_core.config_loader import ConfigurationLoader
+
+loader = ConfigurationLoader()
+config = loader.load_from_yaml("agent_config.yaml")
+agent = loader.create_agent("my_agent", config)
+```
+
+### Tracking System
+
+Track inputs and outputs for debugging:
+
+```python
+from rakam_systems_core.ai_core.tracking import TrackingMixin
+
+class MyAgent(TrackingMixin, BaseAgent):
+    pass
+
+agent.enable_tracking(output_dir="./tracking")
+# Use agent...
+agent.export_tracking_data(format='csv')
+```
+
+## Package Structure
+
+```
+rakam-system-core/
+├── src/rakam_systems_core/
+│   ├── ai_core/
+│   │   ├── base.py              # BaseComponent
+│   │   ├── interfaces/          # Standard interfaces
+│   │   ├── config_loader.py     # Configuration system
+│   │   ├── tracking.py          # I/O tracking
+│   │   └── mcp/                 # MCP server support
+│   └── ai_utils/
+│       └── logging.py           # Logging utilities
+└── pyproject.toml
+```
+
+## Usage in Other Packages
+
+### Agent Package
+
+```python
+# rakam-system-agent uses core interfaces
+from rakam_systems_core.ai_core.interfaces.agent import AgentComponent
+from rakam_system_agent import BaseAgent
+
+agent = BaseAgent(name="my_agent", model="openai:gpt-4o")
+```
+
+### Vectorstore Package
+
+```python
+# rakam-systems-vectorstore uses core interfaces
+from rakam_systems_core.ai_core.interfaces.vectorstore import VectorStore
+from rakam_systems_vectorstore import ConfigurablePgVectorStore
+
+store = ConfigurablePgVectorStore(config=config)
+```
+
+## Development
+
+This package contains only interfaces and utilities. To contribute:
+
+1. Install in editable mode: `pip install -e ./rakam-system-core`
+2. Make changes to interfaces or utilities
+3. Ensure backward compatibility with agent and vectorstore packages
+4. Update version in `pyproject.toml`
+
+## License
+
+Apache 2.0
+
+## Links
+
+- [Main Repository](https://github.com/Rakam-AI/rakam-systems)
+- [Documentation](../docs/)
+- [Agent Package](../rakam-system-agent/)
+- [Vectorstore Package](../rakam-systems-vectorstore/)

rakam_systems_core-0.1.1rc7/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "rakam-systems-core"
+version = "0.1.1rc7"
+description = "A Package containing core logic and schema for rakam-systems"
+readme = "README.md"
+authors = [
+    {name = "Mohamed Hilel", email = "mohammedjassemhlel@gmail.com"},
+    {name = "Peng Zheng", email = "pengzheng990630@outlook.com"},
+    {name = "somebodyawesome-dev", email = "luckynoob2011830@gmail.com"}
+]
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic",
+    "boto3>=1.26.0",  # For S3 utilities
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

rakam_systems_core-0.1.1rc7/src/rakam_systems_core/__init__.py

@@ -0,0 +1,41 @@
+"""
+Rakam System Core - Core abstractions and data structures for the AI system.
+"""
+
+from .ai_core.vs_core import Node, NodeMetadata, VSFile
+from .ai_core import (
+    AgentComponent,
+    AgentInput,
+    AgentOutput,
+    ModelSettings,
+    ToolComponent,
+    ConfigurationLoader,
+    TrackingManager,
+    TrackingMixin,
+    track_method,
+    get_tracking_manager,
+)
+
+__all__ = [
+    # Core data structures
+    "Node",
+    "NodeMetadata",
+    "VSFile",
+    # Core interfaces
+    "AgentComponent",
+    "AgentInput",
+    "AgentOutput",
+    "ModelSettings",
+    "ToolComponent",
+    # Configuration
+    "ConfigurationLoader",
+    # Tracking
+    "TrackingManager",
+    "TrackingMixin",
+    "track_method",
+    "get_tracking_manager",
+]
+
+
+def hello() -> str:
+    return "Hello from rakam-system-core!"

rakam_systems_core-0.1.1rc7/src/rakam_systems_core/ai_core/__init__.py

@@ -0,0 +1,68 @@
+"""Core abstractions for the AI system."""
+
+from .interfaces import (
+    AgentComponent,
+    AgentInput,
+    AgentOutput,
+    ModelSettings,
+    ToolComponent,
+)
+
+# Core data structures
+from .vs_core import Node, NodeMetadata, VSFile
+
+# Configuration and tracking
+from .config_loader import ConfigurationLoader
+from .tracking import (
+    TrackingManager,
+    TrackingMixin,
+    track_method,
+    get_tracking_manager,
+)
+
+# Configuration schemas
+from .config_schema import (
+    AgentConfigSchema,
+    ToolConfigSchema,
+    ModelConfigSchema,
+    PromptConfigSchema,
+    ConfigFileSchema,
+    MethodInputSchema,
+    MethodOutputSchema,
+    MethodCallRecordSchema,
+    TrackingSessionSchema,
+    EvaluationCriteriaSchema,
+    EvaluationResultSchema,
+)
+
+__all__ = [
+    # Core interfaces
+    "AgentComponent",
+    "AgentInput",
+    "AgentOutput",
+    "ModelSettings",
+    "ToolComponent",
+    # Core data structures
+    "Node",
+    "NodeMetadata",
+    "VSFile",
+    # Configuration
+    "ConfigurationLoader",
+    "AgentConfigSchema",
+    "ToolConfigSchema",
+    "ModelConfigSchema",
+    "PromptConfigSchema",
+    "ConfigFileSchema",
+    # Tracking
+    "TrackingManager",
+    "TrackingMixin",
+    "track_method",
+    "get_tracking_manager",
+    "MethodInputSchema",
+    "MethodOutputSchema",
+    "MethodCallRecordSchema",
+    "TrackingSessionSchema",
+    # Evaluation
+    "EvaluationCriteriaSchema",
+    "EvaluationResultSchema",
+]

rakam_systems_core-0.1.1rc7/src/rakam_systems_core/ai_core/base.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Iterable, List, Optional, Callable, Tuple
+import time
+import traceback
+import contextlib
+
+
+class BaseComponent(ABC):
+    """Minimal, dependency-free lifecycle + evaluation mixin for all components.
+
+    Responsibilities
+    - hold a name + config
+    - provide setup()/shutdown() lifecycle
+    - provide __call__ that auto-setup then delegates to run()
+    - provide evaluate() helper for quick smoke tests (no external deps)
+    - context manager support to ensure shutdown() on exit
+    """
+
+    def __init__(self, name: str, config: Optional[Dict[str, Any]] = None) -> None:
+        self.name: str = name
+        self.config: Dict[str, Any] = dict(config or {})
+        self.initialized: bool = False
+
+    # ---------- lifecycle ----------
+    def setup(self) -> None:
+        """Initialize heavy resources (override in subclasses)."""
+        self.initialized = True
+
+    def shutdown(self) -> None:
+        """Release resources (override in subclasses)."""
+        self.initialized = False
+
+    @abstractmethod
+    def run(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute the primary operation for the component."""
+        raise NotImplementedError
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        if not self.initialized:
+            self.setup()
+        return self.run(*args, **kwargs)
+
+    # ---------- context manager ----------
+    def __enter__(self) -> "BaseComponent":
+        if not self.initialized:
+            self.setup()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        # Always attempt to shutdown, even if exceptions happened
+        with contextlib.suppress(Exception):
+            self.shutdown()
+
+    # ---------- utility: timed call wrapper ----------
+    def timed(
+        self, fn: Callable[..., Any], *args: Any, **kwargs: Any
+    ) -> Tuple[Any, float]:
+        start = time.time()
+        out = fn(*args, **kwargs)
+        return out, time.time() - start
+
+    # ---------- micro evaluation harness ----------
+    def evaluate(
+        self,
+        methods: Optional[List[str]] = None,
+        test_cases: Optional[Dict[str, List[Dict[str, Any]]]] = None,
+        metric_fn: Optional[Callable[[Any, Any], float]] = None,
+        verbose: bool = True,
+    ) -> Dict[str, Any]:
+        """Evaluate one or more public methods using a tiny harness.
+
+        test_cases format:
+        {
+          "run": [
+             {"args": [...], "kwargs": {...}, "expected": <any>},
+             ...
+          ],
+          "other_method": [...]
+        }
+        """
+        methods = methods or ["run"]
+        results: Dict[str, Any] = {}
+
+        for method_name in methods:
+            if not hasattr(self, method_name):
+                raise AttributeError(
+                    f"{self.__class__.__name__} has no method '{method_name}'"
+                )
+            method = getattr(self, method_name)
+            if not callable(method):
+                raise TypeError(f"{method_name} is not callable")
+
+            cases = (test_cases or {}).get(method_name, [])
+            mres: List[Dict[str, Any]] = []
+            if verbose:
+                print(
+                    f"🔍 Evaluating {self.name}.{method_name} on {len(cases)} case(s)..."
+                )
+
+            for i, case in enumerate(cases):
+                args = list(case.get("args", []))
+                kwargs = dict(case.get("kwargs", {}))
+                expected = case.get("expected", None)
+
+                t0 = time.time()
+                try:
+                    out = method(*args, **kwargs)
+                    dt = time.time() - t0
+                    score = (
+                        metric_fn(out, expected)
+                        if (metric_fn and expected is not None)
+                        else None
+                    )
+                    mres.append(
+                        {
+                            "case": i,
+                            "ok": True,  # kept for backwards-compat
+                            "success": True,  # <- added for your tests
+                            "time": dt,
+                            "input": {"args": args, "kwargs": kwargs},
+                            "output": out,
+                            "expected": expected,
+                            "score": score,
+                        }
+                    )
+                except Exception as e:
+                    mres.append(
+                        {
+                            "case": i,
+                            "ok": False,  # kept for backwards-compat
+                            "success": False,  # <- added for your tests
+                            "error": f"{e}",
+                            "traceback": traceback.format_exc(),
+                        }
+                    )
+            results[method_name] = mres
+
+        if verbose:
+            print(f"✅ Evaluation complete for {self.name}.")
+        return results

rakam_systems_core-0.1.1rc7/src/rakam_systems_core/ai_core/config.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+import os
+from dataclasses import dataclass
+
+@dataclass
+class Settings:
+    env: str = os.environ.get("AI_ENV", "dev")
+    debug: bool = os.environ.get("AI_DEBUG", "0") == "1"
+    # Add more keys here as needed, always optional to avoid deps.
+    # Example: OPENROUTER_API_KEY = os.environ.get("OPENROUTER_API_KEY")
+
+settings = Settings()