Initial commit

Author: YoanSallami

.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+# name: Docs
+# on:
+#   push:
+#     branches:
+#       - master 
+#       - main
+# permissions:
+#   contents: write
+# jobs:
+#   deploy:
+#     runs-on: ubuntu-latest
+#     steps:
+#       - uses: actions/checkout@v4
+#       - name: Configure Git Credentials
+#         run: |
+#           git config user.name github-actions[bot]
+#           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+#       - uses: actions/setup-python@v5
+#         with:
+#           python-version: 3.x
+#       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+#       - uses: actions/cache@v4
+#         with:
+#           key: mkdocs-material-${{ env.cache_id }}
+#           path: .cache
+#           restore-keys: |
+#             mkdocs-material-
+#       - run: pip install mkdocs-material 
+#       - run: mkdocs gh-deploy --force

.github/workflows/tests.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Display Python version
+      - name: Install Project Manager
+        run: ./shell/uv.sh
+      - name: Install Synalinks
+        run: ./shell/install.sh
+      - name: Run the tests
+        run: ./shell/test.sh

README.md

@@ -0,0 +1,214 @@
+# 🧠🔗 Synalinks
+
+## What is Synalinks?
+
+Synalinks is an open-source framework that makes it easy to create, evaluate, train, and deploy industry-standard Language Models (LMs) applications. Synalinks follows the principle of *progressive disclosure of complexity*: meaning that simple workflows should be quick and easy, while arbitrarily advanced ones should be possible via a clear path that builds upon what you've already learned.
+
+Synalinks is a *fork of Keras 3* adapted for neuro-symbolic systems and in-context reinforcement learning, an ensemble of techniques that enhance the LMs predictions and accuracy without changing the weights of the model. We also provide techniques and optimizers to automatically collect data in order to train and fine-tune your own LMs. The goal of Synalinks is to facilitate the rapid setup of simple applications while providing the flexibility for researchers and advanced users to develop sophisticated systems.
+
+## Who is Synalinks for?
+
+Synalinks is designed for a diverse range of users, from professionals and AI researchers to students, independent developers, and hobbyists. It is suitable for anyone who wants to learn about AI by building/composing blocks or build solid foundations for enterprise-grade products. While a background in Machine Learning and Deep Learning can be advantageous — as Synalinks leverages design patterns from Keras, one of the most user-friendly and popular Deep Learning frameworks — it is not a prerequisite. Synalinks is designed to be accessible to anyone with basic programming skills in Python, making it a versatile and inclusive platform for AI development.
+
+## Why use Synalinks?
+
+Developping a successful LM application in a profesional context, beyond stateless chatbots, is difficult and typically include:
+
+- Building optimized prompts with examples/hints at each step
+- Pipelines that change over time
+- Assessing the performance of your application
+- Configuring Language Models
+- Building data extraction pipelines
+- Documenting your ML workflows
+- Using advanced in-context RL techniques and symbolic systems
+- Traning, evaluating and versioning the prompts/pipelines
+- Deploying REST APIs
+
+Synalinks can help you simplify these tasks by leveraging decade old practices in Deep Learning frameworks. We provide a comprehensive suite of tools and features designed to streamline the development process, making it easier to create, evaluate, train, document and deploy robust neuro-symbolic LMs applications.
+
+### Install
+
+```shell
+pip install synalinks
+```
+
+## Programming your application: 3 ways
+
+### Using the `Functional` API
+
+You start from `Input`, you chain modules calls to specify the model's forward pass, and finally, you create your model from inputs and outputs:
+
+```python
+import synalinks
+
+class Query(synalinks.DataModel):
+    query: str
+
+class AnswerWithRationale(synalinks.DataModel):
+    rationale: str
+    answer: str
+
+language_model = synalinks.LanguageModel(model="ollama/mistral")
+
+x0 = synalinks.Input(data_model=Query)
+x1 = synalinks.Generator(
+    data_model=AnswerWithRationale,
+    language_model=language_model
+)(x0)
+
+program = synalinks.Program(
+    inputs=x0,
+    outputs=x1,
+    name="chain_of_thought",
+    description="Usefull to answer in a step by step manner.",
+)
+```
+
+### Subclassing the `Program` class
+
+In that case, you should define your modules in `__init__()` and you should implement the model's forward pass in `call()`.
+
+**Note:** you can optionaly have a `training` argument (boolean), which you can use to specify a different behavior in training and inference.
+
+```python
+import synalinks
+
+class Query(synalinks.DataModel):
+    query: str
+
+class AnswerWithRationale(synalinks.DataModel):
+    rationale: str
+    answer: str
+
+class ChainOfThought(synalinks.Program):
+    """Usefull to answer in a step by step manner.
+    
+    The first line of the docstring is provided as description
+    for the program if not provided in the `super().__init__()`.
+    In a similar way the name is automatically infered based on
+    the class name if not provided.
+    """
+
+    def __init__(self, language_model=None):
+        super().__init__()
+        self.answer = synalinks.Generator(
+            data_model=AnswerWithRationale,
+            language_model=language_model
+        )
+
+    def call(self, inputs):
+        x = self.answer(inputs)
+        return x
+
+program = ChainOfThought(language_model=language_model)
+```
+
+### Using the `Sequential` API
+
+In addition, `Sequential` is a special case of program where the program
+is purely a stack of single-input, single-output modules.
+
+```python
+import synalinks
+
+class Query(synalinks.DataModel):
+    query: str
+
+class AnswerWithRationale(synalinks.DataModel):
+    rationale: str
+    answer: str
+
+language_model = synalinks.LanguageModel(model="ollama/mistral")
+
+program = synalinks.Sequential(
+    [
+        synalinks.Input(
+            data_model=Query,
+        ),
+        synalinks.Generator(
+            data_model=AnswerWithRationale,
+            language_model=language_model,
+        ),
+    ],
+    name="chain_of_thought",
+    description="Usefull to answer in a step by step manner.",
+)
+```
+
+## Getting summary of your program
+
+To print a tabular summary of your program:
+
+```python
+program.summary()
+```
+
+Or a plot (usefull to document your system):
+
+```python
+synalinks.utils.plot_program(
+    program,
+    show_trainable=True,
+    show_schema=True,
+)
+```
+
+## Running your program
+
+To run your program use the following:
+
+```python
+result = program(Query(query="What is the French city of aerospace?"))
+
+print(result)
+```
+
+## Training your program
+
+```python
+(x_train, y_train), (x_test, y_test) = synalinks.datasets.gsm8k.load_data()
+
+program.compile(
+    reward=synalinks.rewards.ExactMatch(in_mask=["answer"]),
+    optimizer=synalinks.optimizers.RandomFewShot()
+)
+
+batch_size=32
+epochs=2
+
+program.fit(
+    x_train,
+    y_train,
+    batch_size=batch_size,
+    epochs=epochs,
+    validation_split=0.15,
+)
+
+metrics = program.evaluate(x_test, y_test, verbose=0, return_dict=True)
+```
+
+### Learn more
+
+You can learn more on how to create your RAG/Graph-RAG or Agentic applications by reading our [documentation](docs/) or [notebooks](notebooks/). If you have questions about our vision or approach, the [FAQ]() might help you.
+
+### Contributions
+
+Contributions are welcome, either for the implementation of additional modules, metrics, optimizers or for database integrations.
+For more information, or help for implementing your ideas (or ones from a paper), please join our discord.
+
+Beware that every additional metric/module/optimizer should be approved by the core team, we want to keep the library minimal and clean as possible to avoid an uncontrolled growth leading to bad software practices like in most current leading LM frameworks.
+
+### Community
+
+[Discord]()
+
+Join our community to learn more about neuro-symbolic systems and the future of AI. We welcome the participation of people from very different backgrounds or education levels.
+
+### Credit
+
+Synalinks would not be possible without the great work of the following open-source projects:
+
+- [Keras](https://keras.io/) for the graph-based computation backbone, API and overall code, design and philosophy
+- [DSPy](https://dspy.ai/) for the modules/optimizers inspiration
+- [AdalFlow](https://github.com/SylphAI-Inc/AdalFlow) for the the use of jinja2 templates in a self-contained prompt
+- [Pydantic](https://docs.pydantic.dev/latest/) for the backend data layer

api_gen.py

@@ -0,0 +1,97 @@
+"""Script to generate synalinks public API in `synalinks/api` directory.
+
+Usage:
+
+Run via `./shell/api_gen.sh`.
+It generates API and formats user and generated APIs.
+"""
+
+import importlib
+import os
+import shutil
+
+import namex
+
+PACKAGE = "synalinks"
+BUILD_DIR_NAME = "tmp_build_dir"
+
+
+def ignore_files(_, filenames):
+    return [f for f in filenames if f.endswith("_test.py")]
+
+
+def copy_source_to_build_directory(root_path):
+    # Copy sources (`synalinks/` directory and setup files) to build dir
+    build_dir = os.path.join(root_path, BUILD_DIR_NAME)
+    if os.path.exists(build_dir):
+        shutil.rmtree(build_dir)
+    os.mkdir(build_dir)
+    shutil.copytree(PACKAGE, os.path.join(build_dir, PACKAGE), ignore=ignore_files)
+    return build_dir
+
+
+def export_version_string(api_init_fname):
+    with open(api_init_fname) as f:
+        contents = f.read()
+    with open(api_init_fname, "w") as f:
+        contents += "from synalinks.src.version import __version__\n"
+        f.write(contents)
+
+
+def update_package_init(template_fname, dest_fname, api_module):
+    with open(template_fname) as template_file:
+        with open(dest_fname, "w") as dest_file:
+            for line in template_file:
+                if "# DO NOT EDIT." in line:
+                    dest_file.write(line)
+                    # Import all public symbols from `api/` and `__version__`.
+                    for symbol in api_module.__dict__.keys():
+                        if symbol.startswith("_") and symbol != "__version__":
+                            continue
+                        dest_file.write(f"from synalinks.api import {symbol}\n")
+                    # Skip the previous autogenerated block.
+                    for line in template_file:
+                        if "# END DO NOT EDIT." in line:
+                            break
+                dest_file.write(line)
+
+
+def build():
+    # Backup the `synalinks/__init__.py` and restore it on error in api gen.
+    root_path = os.path.dirname(os.path.abspath(__file__))
+    code_api_dir = os.path.join(root_path, PACKAGE, "api")
+    code_init_fname = os.path.join(root_path, PACKAGE, "__init__.py")
+    # Create temp build dir
+    build_dir = copy_source_to_build_directory(root_path)
+    build_api_dir = os.path.join(build_dir, PACKAGE, "api")
+    build_init_fname = os.path.join(build_dir, PACKAGE, "__init__.py")
+    build_api_init_fname = os.path.join(build_api_dir, "__init__.py")
+    try:
+        os.chdir(build_dir)
+        # Generates `synalinks/api` directory.
+        if os.path.exists(build_api_dir):
+            shutil.rmtree(build_api_dir)
+        if os.path.exists(build_init_fname):
+            os.remove(build_init_fname)
+        os.makedirs(build_api_dir)
+        namex.generate_api_files(
+            "synalinks", code_directory="src", target_directory="api"
+        )
+        # Add __version__ to `api/`.
+        export_version_string(build_api_init_fname)
+        # Update toplevel init with all `api/` imports.
+        api_module = importlib.import_module(f"{BUILD_DIR_NAME}.synalinks.api")
+
+        update_package_init(code_init_fname, build_init_fname, api_module)
+        # Copy back the synalinks/api and synalinks/__init__.py from build directory
+        if os.path.exists(code_api_dir):
+            shutil.rmtree(code_api_dir)
+        shutil.copytree(build_api_dir, code_api_dir)
+        shutil.copy(build_init_fname, code_init_fname)
+    finally:
+        # Clean up: remove the build directory (no longer needed)
+        shutil.rmtree(build_dir)
+
+
+if __name__ == "__main__":
+    build()