modaic 0.10.4__py3-none-any.whl

modaic/programs/registry.py

@@ -0,0 +1,104 @@
+# registry.py
+import warnings
+from importlib import import_module
+from typing import Callable, Dict, NamedTuple, Tuple, Type
+
+
+class Key(NamedTuple):
+    name: str
+    type: str  # yes, attribute name 'type' is fine here
+
+
+class Registry:
+    def __init__(self):
+        self._paths: Dict[Key, Tuple[str, str]] = {}  # Key -> (module_path, qualname)
+        self._cache: Dict[Key, Type] = {}
+        self._frozen: bool = False
+
+    def register(self, key: Key, cls: Type) -> None:
+        if self._frozen:
+            raise RuntimeError("Registry is frozen; no further registrations allowed.")
+        if key in self._paths:
+            mod, qual = self._paths[key]
+            raise KeyError(f"Collision for {key}: already registered to {mod}:{qual}")
+        if not isinstance(cls, type):
+            raise TypeError("register() expects a class as the second argument.")
+
+        module_path = cls.__module__
+        qualname = cls.__qualname__  # supports nested classes
+        self._paths[key] = (module_path, qualname)
+        self._cache.pop(key, None)  # just in case
+
+    def freeze(self) -> None:
+        self._frozen = True
+
+    def get(self, key: Key) -> Type:
+        # Fast path
+        if key in self._cache:
+            return self._cache[key]
+
+        try:
+            module_path, qualname = self._paths[key]
+        except KeyError:
+            raise KeyError(f"Unknown key {key}. Was it registered before freeze()?") from None
+
+        mod = import_module(module_path)
+        obj = mod
+        for part in qualname.split("."):  # walk nested qualnames safely
+            obj = getattr(obj, part)
+
+        if not isinstance(obj, type):
+            raise TypeError(f"Resolved {module_path}:{qualname} is not a class.")
+
+        self._cache[key] = obj
+        return obj
+
+
+# Instantiate per “kind”
+ProgramRegistry = Registry()
+
+
+def builtin_program(name: str) -> Callable[[Type], Type]:
+    """Decorator to register a builtin module."""
+
+    def _wrap(cls: Type) -> Type:
+        key = Key(name, "program")
+        ProgramRegistry.register(key, cls)
+        return cls
+
+    return _wrap
+
+
+def builtin_agent(name: str) -> Callable[[Type], Type]:
+    """Deprecated: Use builtin_program instead."""
+    warnings.warn(
+        "builtin_agent is deprecated and will be removed in a future version. "
+        "Please use builtin_program instead for better parity with DSPy.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    def _wrap(cls: Type) -> Type:
+        key = Key(name, "program")
+        ProgramRegistry.register(key, cls)
+        return cls
+
+    return _wrap
+
+
+def builtin_indexer(name: str) -> Callable[[Type], Type]:
+    def _wrap(cls: Type) -> Type:
+        key = Key(name, "indexer")
+        ProgramRegistry.register(key, cls)
+        return cls
+
+    return _wrap
+
+
+def builtin_config(name: str) -> Callable[[Type], Type]:
+    def _wrap(cls: Type) -> Type:
+        key = Key(name, "config")
+        ProgramRegistry.register(key, cls)
+        return cls
+
+    return _wrap

modaic/serializers.py

@@ -0,0 +1,222 @@
+import inspect
+import typing as t
+from typing import TYPE_CHECKING, Annotated, Optional, Tuple, Type
+
+import dspy
+from dspy import InputField, OutputField, make_signature
+from pydantic import BeforeValidator, Field, InstanceOf, PlainSerializer, create_model
+from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
+
+if TYPE_CHECKING:
+    from pydantic.json_schema import CoreSchemaOrField
+
+INCLUDED_FIELD_KWARGS = {
+    "desc",
+    "alias",
+    "alias_priority",
+    "validation_alias",
+    "serialization_alias",
+    "title",
+    "description",
+    "exclude",
+    "discriminator",
+    "deprecated",
+    "frozen",
+    "validate_default",
+    "repr",
+    "init",
+    "init_var",
+    "kw_only",
+    "pattern",
+    "strict",
+    "coerce_numbers_to_str",
+    "gt",
+    "ge",
+    "lt",
+    "le",
+    "multiple_of",
+    "allow_inf_nan",
+    "max_digits",
+    "decimal_places",
+    "min_length",
+    "max_length",
+    "union_mode",
+    "fail_fast",
+}
+
+
+def _handle_any_of(obj: dict, defs: Optional[dict] = None) -> t.Type:
+    """
+    Deserializes anyOf into a union type
+    """
+    return t.Union[tuple(json_to_type(item, defs) for item in obj["anyOf"])]
+
+
+def _handle_object(obj: dict, defs: Optional[dict] = None) -> dict:
+    """
+    Deserializes basic objects types into dict type
+    """
+    additional_properties = obj.get("additionalProperties")
+    if additional_properties == True:  # noqa: E712 we need to expliclity check for True, not just truthy
+        return dict
+    value_type = json_to_type(additional_properties, defs)
+    return dict[str, value_type]
+
+
+def _handle_array(obj: dict, defs: Optional[dict] = None) -> list:
+    """
+    Deserializes arrays into lists, sets, or tuple type.
+    """
+    if (items := obj.get("items")) is not None:
+        set_or_list = set if obj.get("uniqueItems") else list
+
+        if items == {}:
+            return set_or_list
+        else:
+            return set_or_list[json_to_type(items, defs)]
+
+    elif "maxItems" in obj and "minItems" in obj and (prefix_items := obj.get("prefixItems")):
+        item_types = tuple(json_to_type(item, defs) for item in prefix_items)
+        return Tuple[item_types]
+    else:
+        raise ValueError(f"Invalid array: {obj}")
+
+
+def _handle_custom_type(ref: str, defs: Optional[dict] = None) -> t.Type:
+    """
+    Deserializes custom types defined in $def into dspy special types and BaseModels
+    """
+    # CAVEAT if user defines custom types that overlap with these names they will be overwritten by the dspy types
+    dspy_types = {
+        "dspy.Image": dspy.Image,
+        "dspy.Audio": dspy.Audio,
+        "dspy.History": dspy.History,
+        "dspy.Tool": dspy.Tool,
+        "dspy.ToolCalls": dspy.ToolCalls,
+        "dspy.Code": dspy.Code,
+    }
+    name = ref.split("/")[-1]
+    obj = defs[name]
+    if dspy_type := dspy_types.get(obj["type"]):
+        return dspy_type
+    if obj["type"] == "object":
+        fields = {}
+        for name, field in obj["properties"].items():
+            field_kwargs = {k: v for k, v in field.items() if k in INCLUDED_FIELD_KWARGS}
+            if default := field.get("default"):
+                fields[name] = (
+                    json_to_type(field, defs),
+                    Field(default=default, **field_kwargs),
+                )
+            else:
+                fields[name] = (json_to_type(field, defs), Field(..., **field_kwargs))
+        return create_model(name, **fields)
+
+    else:
+        raise ValueError(f"Invalid type: {obj}")
+
+
+def json_to_type(json_type: dict, defs: Optional[dict] = None) -> t.Type:
+    """
+    Desserializes a json schema into a python type
+    """
+    primitive_types = {
+        "string": str,
+        "number": float,
+        "integer": int,
+        "boolean": bool,
+        "null": None,
+    }
+    if j_type := json_type.get("type"):
+        if j_type in primitive_types:
+            return primitive_types[j_type]
+        elif j_type == "array":
+            return _handle_array(json_type, defs)
+        elif j_type == "object":
+            return _handle_object(json_type, defs)
+        else:
+            raise ValueError(f"Invalid type: {j_type}")
+    elif ref := json_type.get("$ref"):
+        return _handle_custom_type(ref, defs)
+    elif json_type.get("anyOf"):
+        return _handle_any_of(json_type, defs)
+    else:
+        raise ValueError(f"Invalid json schema: {json_type}")
+
+
+def _deserialize_dspy_signatures(
+    obj: dict | Type[dspy.Signature],
+) -> Type[dspy.Signature]:
+    """
+    Deserizlizes a dictionary into a DSPy signature. Not all signatures can be deserialized.
+    - All fields (and fields of fields) cannot have default factories
+    - Frozensets will be serialized to sets
+    - tuples without arguments will be serialized to lists
+    """
+    if inspect.isclass(obj) and issubclass(obj, dspy.Signature):
+        return obj
+    fields = {}
+    defs = obj.get("$defs", {})
+    properties: dict[str, dict] = obj.get("properties", {})
+    for name, field in properties.items():
+        field_kwargs = {k: v for k, v in field.items() if k in INCLUDED_FIELD_KWARGS}
+        InputOrOutputField = InputField if field.get("__dspy_field_type") == "input" else OutputField  # noqa: N806
+        if default := field.get("default"):
+            fields[name] = (
+                json_to_type(field, defs),
+                InputOrOutputField(default=default, **field_kwargs),
+            )
+        else:
+            fields[name] = (
+                json_to_type(field, defs),
+                InputOrOutputField(**field_kwargs),
+            )
+    signature = make_signature(
+        signature=fields,
+        instructions=obj.get("description"),
+        signature_name=obj.get("title"),
+    )
+    return signature
+
+
+class DSPyTypeSchemaGenerator(GenerateJsonSchema):
+    def generate_inner(self, schema: "CoreSchemaOrField") -> JsonSchemaValue:
+        cls = schema.get("cls")
+        super_generate_inner = super().generate_inner
+
+        def handle_dspy_type(name: str) -> dict:
+            schema["metadata"]["pydantic_js_functions"] = [lambda cls, core_schema: {"type": f"dspy.{name}"}]
+            return super_generate_inner(schema)
+
+        for dspy_type in [
+            dspy.Image,
+            dspy.Audio,
+            dspy.History,
+            dspy.Tool,
+            dspy.ToolCalls,
+            dspy.Code,
+        ]:
+            if cls is dspy_type:
+                return handle_dspy_type(dspy_type.__name__)
+        return super_generate_inner(schema)
+
+
+def _deserialize_dspy_lm(lm: dict | dspy.LM) -> dspy.LM:
+    if type(lm) is dspy.LM:
+        return lm
+    if isinstance(lm, dict):
+        return dspy.LM(**lm)
+
+
+SerializableSignature = Annotated[
+    Type[dspy.Signature],
+    BeforeValidator(_deserialize_dspy_signatures),
+    PlainSerializer(lambda s: s.model_json_schema(schema_generator=DSPyTypeSchemaGenerator)),
+]
+
+
+SerializableLM = Annotated[
+    InstanceOf[dspy.LM],
+    BeforeValidator(_deserialize_dspy_lm),
+    PlainSerializer(lambda lm: lm.dump_state()),
+]

modaic/utils.py

@@ -0,0 +1,115 @@
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from dotenv import find_dotenv, load_dotenv
+from platformdirs import user_cache_dir
+
+INCLUDED_FIELD_KWARGS = {
+    "desc",
+    "alias",
+    "alias_priority",
+    "validation_alias",
+    "serialization_alias",
+    "title",
+    "description",
+    "exclude",
+    "discriminator",
+    "deprecated",
+    "frozen",
+    "validate_default",
+    "repr",
+    "init",
+    "init_var",
+    "kw_only",
+    "pattern",
+    "strict",
+    "coerce_numbers_to_str",
+    "gt",
+    "ge",
+    "lt",
+    "le",
+    "multiple_of",
+    "allow_inf_nan",
+    "max_digits",
+    "decimal_places",
+    "min_length",
+    "max_length",
+    "union_mode",
+    "fail_fast",
+}
+
+env_file = find_dotenv(usecwd=True)
+load_dotenv(env_file)
+
+
+def compute_cache_dir() -> Path:
+    """Return the cache directory used to stage internal modules."""
+    cache_dir_env = os.getenv("MODAIC_CACHE")
+    if sys.platform.startswith("win"):
+        default_cache_dir = Path(user_cache_dir("modaic", appauthor=False))
+    else:
+        default_cache_dir = Path(os.path.expanduser("~")) / ".cache" / "modaic"
+    cache_dir = Path(cache_dir_env).expanduser().resolve() if cache_dir_env else default_cache_dir.resolve()
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def validate_project_name(text: str) -> bool:
+    """Letters, numbers, underscore, hyphen"""
+    assert bool(re.match(r"^[a-zA-Z0-9_]+$", text)), (
+        "Invalid project name. Must contain only letters, numbers, and underscore."
+    )
+
+
+class Timer:
+    def __init__(self, name: str):
+        self.start_time = time.time()
+        self.name = name
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):  # noqa: ANN001, ANN002, ANN003
+        self.done()
+
+    def done(self):
+        end_time = time.time()
+        print(f"{self.name}: {end_time - self.start_time}s")  # noqa: T201
+
+
+def smart_rmtree(path: Path, ignore_errors: bool = False) -> None:
+    """
+    Remove a directory and all its contents.
+    If on windows use rmdir with /s flag
+    If on mac/linux use rm -rf
+    """
+    if sys.platform.startswith("win"):
+        try:
+            shutil.rmtree(path, ignore_errors=False)
+        except PermissionError:
+            subprocess.run(["cmd", "/c", "rmdir", "/s", "/q", str(path)], check=not ignore_errors)
+        except Exception as e:
+            if not ignore_errors:
+                raise e
+    else:
+        shutil.rmtree(path, ignore_errors=ignore_errors)
+
+
+def aggresive_rmtree(path: Path, missing_ok: bool = True) -> None:
+    try:
+        shutil.rmtree(path, ignore_errors=False)
+    except FileNotFoundError as e:
+        if not missing_ok:
+            raise e
+    except Exception as e:
+        if sys.platform.startswith("win"):
+            subprocess.run(["taskkill", "/F", "/IM", "git.exe"], capture_output=True, check=False)
+            time.sleep(0.5)
+            subprocess.run(["cmd", "/c", "rmdir", "/s", "/q", str(path)], capture_output=True, check=True)
+        else:
+            raise e

modaic-0.10.4.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: modaic
+Version: 0.10.4
+Summary: Modular Agent Infrastructure Collection, a python framework for managing and sharing DSPy agents
+Project-URL: Homepage, https://github.com/modaic-ai/modaic
+Project-URL: Modaic, https://www.modaic.dev
+Project-URL: Docs, https://docs.modaic.dev
+Author-email: Tyrin <tytodd@mit.edu>, Farouk <farouk@modaic.dev>
+License: MIT License
+        
+        Copyright (c) 2025 Modaic Inc
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+        ---
+        
+        Additional Terms:
+        
+        1. You may not modify this Software in any way that changes the default hub
+           endpoint, nor distribute derivative works that route agents or models to
+           a hub other than modaic.dev.
+        
+        2. All other rights are granted as per the MIT License.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: dspy>=2.6.27
+Requires-Dist: gitpython>=3.1.45
+Requires-Dist: opik==1.8.42
+Requires-Dist: platformdirs>=4.3.8
+Requires-Dist: tomlkit>=0.13.3
+Description-Content-Type: text/markdown
+
+[![Docs](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://docs.modaic.dev)
+[![PyPI](https://img.shields.io/pypi/v/modaic)](https://pypi.org/project/modaic/)
+
+
+# Modaic 🐙
+Modular + Mosaic, a Python framework for composing and maintaining DSPy applications.
+
+## Key Features
+
+- **Hub Support**: Load and share precompiled DSPY programs from Modaic Hub
+- **Program Framework**: Precompiled and auto-loading DSPY programs
+- **Automated LM Judge Alignment**: Continuously align your LM judges to your preferences while staying at the pareto frontier!
+
+Never lose your progress again.
+Save everything you need to compare and reproduce optimization runs with GEPA, MIPROv2, etc. - architecture, hyperparameters, precompiled prompts, predictions, git commits, and even datasets - in 5 minutes. Modaic is free for personal use and academic projects, and it's easy to get started.
+
+## Installation
+
+### Using uv (recommended)
+
+```bash
+uv add modaic
+```
+
+Optional (for hub operations):
+
+```bash
+export MODAIC_TOKEN="<your-token>"
+```
+
+### Using pip
+Please note that you will not be able to push DSPY programs to the Modaic Hub with pip.
+```bash
+pip install modaic
+```
+## Quick Start
+
+### Creating a Simple Program
+
+```python
+from modaic import PrecompiledProgram, PrecompiledConfig
+
+class WeatherConfig(PrecompiledConfig):
+    weather: str = "sunny"
+
+class WeatherProgram(PrecompiledProgram):
+    config: WeatherConfig
+
+    def __init__(self, config: WeatherConfig, **kwargs):
+        super().__init__(config, **kwargs)
+
+    def forward(self, query: str) -> str:
+        return f"The weather in {query} is {self.config.weather}."
+
+weather_program = WeatherProgram(WeatherConfig())
+print(weather_program(query="Tokyo"))
+weather_program.push_to_hub("me/my-weather-program")
+```
+
+Save and load locally:
+
+```python
+weather_program.save_precompiled("./my-weather")
+
+from modaic import AutoProgram, AutoConfig
+
+cfg = AutoConfig.from_precompiled("./my-weather", local=True)
+loaded = AutoProgram.from_precompiled("./my-weather", local=True)
+print(loaded(query="Kyoto"))
+```
+
+from hub:
+
+```python
+from modaic import AutoProgram, AutoConfig
+
+loaded = AutoProgram.from_precompiled("me/my-weather-program", rev="v2.0.0")
+print(loaded(query="Kyoto"))
+```
+
+## Architecture
+### Program Types
+
+1. **PrecompiledProgram**: Statically defined programs with explicit configuration
+2. **AutoProgram**: Dynamically loaded programs from Modaic Hub or local repositories
+## Support
+
+For issues and questions:
+- GitHub Issues: `https://github.com/modaic-ai/modaic/issues`
+- Docs: `https://docs.modaic.dev`

modaic-0.10.4.dist-info/RECORD

@@ -0,0 +1,19 @@
+modaic/__init__.py,sha256=MhWutNJpPyUBxlAwXj5TaYs9NfslN6DBLSW5g-RxfO8,806
+modaic/auto.py,sha256=cwbuK_MYas3sroR8w6sMDuEWpYXLfE1sPJ0siHTYaJY,10459
+modaic/constants.py,sha256=4HElDBnhbeJYq5KHwcwBfOi50Ov3m5TmVdlu2P4qusc,586
+modaic/datasets.py,sha256=K-PpPSYIxJI0-yH-SBVpk_EfCM9i_uPz-brmlzP7hzI,513
+modaic/exceptions.py,sha256=tdtD8uKA7Tz0H0Q1mLU88mmqKA_X1MQjqdwN3gm62J4,1162
+modaic/hub.py,sha256=AygZiICOmANFxAldZhOs4mWrnDdjJ6sSIuChaCWW7BQ,24285
+modaic/module_utils.py,sha256=steEUjAMMR_iNsnMSdb4wJWOhABkfvplKcMxrXMZjDI,18401
+modaic/observability.py,sha256=_oQ1XHoiGUxcJ4TJuVZdVbHVg_1090vbnrCpDX3baxU,9082
+modaic/precompiled.py,sha256=OKVkS56xzZDQKemJHsLCPOrxoGUowqkEuN8fnQppLlo,22860
+modaic/serializers.py,sha256=1IY2KnxQNZOFNWlyfMnWYYMqWp4aWokL1cqyWISwfGE,6989
+modaic/utils.py,sha256=c3xJ1-HYgBrLWKxlWzM8_RNs0kP2wBoIGb7BTKQ1CTE,3109
+modaic/programs/__init__.py,sha256=Wn-uv5Wd6XGkkvepGIg2R_Dsa9gDBp2Ylyft-n58e1I,58
+modaic/programs/predict.py,sha256=-ybyGv1aT12aMIt8DFYRCn02HLqFVoSIrhcfkg6Xl90,1569
+modaic/programs/rag_program.py,sha256=Hj3LahWgPRnXyz_SIjuNx4uU4mguCJlgTbHd3a62Sec,833
+modaic/programs/registry.py,sha256=2HypXX6t9d00dhyUf8QoeOL6UJpmgN7g0RVQ0oYMCOg,3014
+modaic-0.10.4.dist-info/METADATA,sha256=dzuqz7dQM4aPUhy_TdwEBj7rRHpi4vhokBLUlbOFeD4,4786
+modaic-0.10.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+modaic-0.10.4.dist-info/licenses/LICENSE,sha256=7LMx9j453Vz1DoQbFot8Uhp9SExF5wlOx7c8vw2qhsE,1333
+modaic-0.10.4.dist-info/RECORD,,

modaic-0.10.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

modaic-0.10.4.dist-info/licenses/LICENSE

@@ -0,0 +1,31 @@
+MIT License
+
+Copyright (c) 2025 Modaic Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Additional Terms:
+
+1. You may not modify this Software in any way that changes the default hub
+   endpoint, nor distribute derivative works that route agents or models to
+   a hub other than modaic.dev.
+
+2. All other rights are granted as per the MIT License.