From f110028c2979cad07d2601e9bb8102720a5d7499 Mon Sep 17 00:00:00 2001 From: Farouk Adeleke Date: Wed, 4 Feb 2026 21:41:22 -0800 Subject: [PATCH] (no commit message) --- CONTRIBUTING.md | 64 ++++++++++++++++++++++++++++++++ LICENSE | 31 ++++++++++++++++ README.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++- config.json | 3 ++ program.json | 42 +++++++++++++++++++++ 5 files changed, 236 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 config.json create mode 100644 program.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1add746 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# Contributing to Modaic +## Finding an Issue to Work On +- Check the [issues](https://github.com/modaic-ai/modaic/issues) page for open issues. +- If you are new to the project, start with the [good first issue](https://github.com/modaic-ai/modaic/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label. +- Also check the [help wanted](https://github.com/modaic-ai/modaic/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) label for issues that are more complex but still manageable. +- If you have questions about an issue, ask in the comments. +- If you want to work on an issue, comment on the issue that you will work on it. +- If you have already started working on an issue, let us know in the comments. + +## Setting up the Development Environment +- First, fork the repository and clone it locally. +- We use [uv](https://docs.astral.sh/uv/) to manage the dependencies. Refer to the site for installation instructions. +- Then install the development dependencies with the following command: +```bash +cd modaic +uv sync --dev +``` + +## Code Style and Formatting +**Comments** + +Include docstrings for all public functions and classes. +Do not use # comments unless they are prefixed with a code tag and are necessary for the code to be understandable. We use the following code tags: +- `# CAVEAT:` - A heads-up that there’s something tricky or non-obvious here that the reader should keep in mind. +- `# NOTE:` - A note to the reader offering some necessary context. +- `# TODO:` - Something needs to be done. +- `# DOCME:` - Needs to be documented. +- `# BUG:` - Something is wrong. +- `# FIXME:` - Something needs to be fixed. +- `# HACK:` - A temporary ugly workaround solution that is hacky and should be changed. +To get the most use out of code tags, I recommend you install the [TODO Tree Extension](https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree) + +**Formatting** + +We use the ruff linter/formatter to check for code style and formatting. It is installed with the dev dependencies. To use it, install the [Ruff Extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) on VSCode. Make sure your VSCode python interpreter is set to the python path in the `.venv` created by uv. You can change it by pressing `Ctrl+Shift+P` on windows and `Cmd+Shift+P` on Mac and typing `Python: Select Interpreter`. You should see one named `.venv`. This will ensure the formatter rules match the modaic specific formatting. + +When working with ruff, you may find these settings useful for auto-formatting code. You can add these to your VSCode user settings. (cmd + shift + p -> "Preferences: Open Workspace Settings (JSON)") +```json + "editor.formatOnSave": true, + "ruff.path": ["ruff"], + "[python]": { + "editor.defaultFormatter": "charliermarsh.ruff", + "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.fixAll": "explicit" + } + } +``` + +## Contributing to the Documentation +- Follow instructions for setting up the local development environment [above](#setting-up-the-development-environment). +- Next ensure you have [node](https://nodejs.org/en/download/) installed. +- Install the node dependencies for the documentation. +```bash +npm install +``` +- To run the documentation locally with live reload, run the following command: +```bash +npm run dev +``` +- To build the documentation, run the following command: +```bash +npm run build +``` \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..e125a3d --- /dev/null +++ b/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 programs or models to + a hub other than modaic.dev. + +2. All other rights are granted as per the MIT License. diff --git a/README.md b/README.md index 57d7bf9..e34d31e 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,97 @@ -# no-code-repo +[![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="" +``` + +### 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` + +## Development + +install development dependencies: +```bash +uv sync --all-extras +``` diff --git a/config.json b/config.json new file mode 100644 index 0000000..4475ebc --- /dev/null +++ b/config.json @@ -0,0 +1,3 @@ +{ + "model": null +} \ No newline at end of file diff --git a/program.json b/program.json new file mode 100644 index 0000000..8e0f4ae --- /dev/null +++ b/program.json @@ -0,0 +1,42 @@ +{ + "predictor": { + "traces": [], + "train": [], + "demos": [], + "signature": { + "instructions": "Given the fields `question`, `context`, produce the fields `answer`.", + "fields": [ + { + "prefix": "Question:", + "description": "${question}" + }, + { + "prefix": "Context:", + "description": "${context}" + }, + { + "prefix": "Answer:", + "description": "Answer to the question, based on the passage" + } + ] + }, + "lm": { + "model": "openai/gpt-4o-mini", + "model_type": "chat", + "cache": true, + "num_retries": 3, + "finetuning_model": null, + "launch_kwargs": {}, + "train_kwargs": {}, + "temperature": null, + "max_tokens": null + } + }, + "metadata": { + "dependency_versions": { + "python": "3.13", + "dspy": "3.1.2", + "cloudpickle": "3.1" + } + } +} \ No newline at end of file