Add OPRO and prepare for KG integration

Author: YoanSallami

README.md

@@ -91,7 +91,7 @@ async def main():
         )
 
     language_model = synalinks.LanguageModel(
-        model="ollama_chat/deepseek-r1",
+        model="ollama/mistral",
     )
 
     x0 = synalinks.Input(data_model=Query)
@@ -190,7 +190,7 @@ async def main():
             return cls(language_model=language_model, **config)
 
     language_model = synalinks.LanguageModel(
-        model="ollama_chat/deepseek-r1",
+        model="ollama/mistral",
     )
 
     program = ChainOfThought(
@@ -260,7 +260,7 @@ async def main():
             )
 
     language_model = synalinks.LanguageModel(
-        model="ollama_chat/deepseek-r1",
+        model="ollama/mistral",
     )
 
     program = ChainOfThought(
@@ -298,7 +298,7 @@ async def main():
         )
 
     language_model = synalinks.LanguageModel(
-        model="ollama_chat/deepseek-r1",
+        model="ollama/mistral",
     )
 
     program = synalinks.Sequential(

coverage-badge.svg

@@ -0,0 +1,233 @@
+# Your First Programs
+
+The main concept of Synalinks, is that an application (we call it a `Program`)
+is a computation graph (a Directed Acyclic Graph to be exact) with JSON data (called `JsonDataModel`) as edges and `Operation`s as nodes.
+
+What set apart Synalinks from other similar frameworks like DSPy or AdalFlow is that we focus on graph-based systems but also that it allow users to declare the computation graph using a Functional API inherited
+from [Keras](https://keras.io/).
+
+About modules, similar to layers in deep learning applications, modules are
+composable blocks that you can assemble in multiple ways. Providing a modular
+and composable architecture to experiment and unlock creativity.
+
+Note that each `Program` is also a `Module`! Allowing you to encapsulate them
+as you want.
+
+Many people think that what enabled the Deep Learning revolution was compute
+and data, but in reality, frameworks also played a pivotal role as they enabled
+researchers and engineers to create complex architectures without having to 
+re-implement everything from scatch.
+
+```python
+import synalinks
+import asyncio
+# Now we can define the data models that we are going to use in the tutorial.
+
+class Query(synalinks.DataModel):
+    query: str = synalinks.Field(
+        description="The user query",
+    )
+
+class AnswerWithThinking(synalinks.DataModel):
+    thinking: str = synalinks.Field(
+        description="Your step by step thinking process",
+    )
+    answer: str = synalinks.Field(
+        description="The correct answer",
+    )
+
+# And the language model to use
+
+language_model = synalinks.LanguageModel(
+    model="ollama/mistral",
+)
+```
+
+## Functional API
+
+You can program your application using 4 different ways, let's start with the
+Functional way.
+
+In this case, you start from `Input` and you chain modules calls to specify the
+programs's structure, and finally, you create your program from inputs and outputs:
+
+```python
+
+async def main():
+
+    x0 = synalinks.Input(data_model=Query)
+    x1 = await synalinks.Generator(
+        data_model=AnswerWithThinking,
+        language_model=language_model,
+    )(x0)
+
+    program = synalinks.Program(
+        inputs=x0,
+        outputs=x1,
+        name="chain_of_thought",
+        description="Useful to answer in a step by step manner.",
+    )
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Subclassing the `Program` class
+
+Now let's try to program it using another method, subclassing the `Program`
+class. It is the more complicated one, and reserved for skilled developers or contributors.
+
+In that case, you should define your modules in `__init__()` and you should
+implement the program's structure in `call()` and the serialization methods (`get_config` and `from_config`).
+
+```python
+class ChainOfThought(synalinks.Program):
+    """Useful 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=AnswerWithThinking, language_model=language_model
+        )
+
+    async def call(self, inputs, training=False):
+        x = await self.answer(inputs)
+        return x
+
+    def get_config(self):
+        config = {
+            "name": self.name,
+            "description": self.description,
+            "trainable": self.trainable,
+        }
+        language_model_config = {
+            "language_model": synalinks.saving.serialize_synalinks_object(
+                self.language_model
+            )
+        }
+        return {**config, **language_model_config}
+
+    @classmethod
+    def from_config(cls, config):
+        language_model = synalinks.saving.deserialize_synalinks_object(
+            config.pop("language_model")
+        )
+        return cls(language_model=language_model, **config)
+
+program = ChainOfThought(language_model=language_model)
+```
+
+Note that the program isn't actually built, this behavior is intended its 
+means that it can accept any king of input, making the program truly 
+generalizable.
+
+## Mixing the subclassing and the `Functional` API
+
+This way of programming is recommended to encapsulate your application while providing an easy to use setup.
+It is the recommended way for most users as it avoid making your program/agents from scratch.
+In that case, you should implement only the `__init__()` and `build()` methods.
+
+```python
+
+class ChainOfThought(synalinks.Program):
+    """Useful to answer in a step by step manner."""
+
+    def __init__(
+        self,
+        language_model=None,
+        name=None,
+        description=None,
+        trainable=True,
+    ):
+        super().__init__(
+            name=name,
+            description=description,
+            trainable=trainable,
+        )
+        self.language_model = language_model
+    
+    async def build(self, inputs):
+        outputs = await synalinks.Generator(
+            data_model=AnswerWithThinking,
+            language_model=self.language_model,
+        )(inputs)
+
+        # Create your program using the functional API
+        super().__init__(
+            inputs=inputs,
+            outputs=outputs,
+            name=self.name,
+            description=self.description,
+            trainable=self.trainable,
+        )
+
+program = ChainOfThought(
+    language_model=language_model,
+)
+```
+
+Like when using the subclassing method, the program will be built on the fly when called for the first time.
+
+## 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
+
+async def main():
+
+    program = synalinks.Sequential(
+        [
+            synalinks.Input(
+                data_model=Query,
+            ),
+            synalinks.Generator(
+                data_model=AnswerWithThinking,
+                language_model=language_model,
+            ),
+        ],
+        name="chain_of_thought",
+        description="Useful to answer in a step by step manner.",
+    )
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Running your programs
+        
+In order to run your program, you just have to call it with the input data model
+as argument.
+
+```python
+result = await program(
+    Query(query="What are the key aspects of human cognition?"),
+)
+```
+
+## Conclusion
+        
+Congratulations! You've successfully explored the fundamental concepts of programming
+applications using Synalinks.
+
+Now that we know how to program applications, you can learn how to control
+the data flow in the next tutorial.
+
+### Key Takeaways
+
+- **Functional API**: Allows you to chain modules to define the program's structure, 
+    providing a clear and intuitive way to build applications.
+- **Subclassing**: Offers flexibility and control by defining modules and implementing
+    the program's structure from scratch within a class.
+- **Mixing the subclassing and the Functional API**: Allows to benefit from the
+    compositionality of the subclassing while having the ease of use of the functional way of programming.
+- **Sequential Programs**: Simplifies the creation of linear workflows, making it easy
+    to stack single-input, single-output modules.
+- **Modularity and Composability**: Enables the reuse of components, fostering  
+    creativity and efficiency in application development.

docs/Code Examples/First Programs.md

@@ -0,0 +1,111 @@
+# First Steps
+
+First, install Synalinks, the easiest way is using pip:
+
+```shell
+pip install synalinks
+```
+
+Or uv (recommended):
+
+```shell
+uv pip install synalinks
+```
+
+If you want to install it from source (for contributors), then do:
+
+```shell
+git clone https://github.com/SynaLinks/synalinks
+cd synalinks
+./shell/uv.sh # Install uv
+./shell/install.sh # Create the virtual env and install Synalinks
+```
+
+After this, open a python file or notebook and check the install:
+
+```python
+import synalinks
+print(synalinks.__version__)
+```
+
+Or just create a new project using the following command:
+
+```shell
+uv run synalinks init
+```
+
+Synalinks use a global context to ensure that each variable/module
+have a unique name. Clear it at the beginning of your scripts to 
+ensure naming reproductability.
+
+```python
+# Clear the global context
+synalinks.clear_session()
+```
+
+Addtionally, you can install Ollama [here](https://ollama.com/) to run
+Language Models (LMs) locally, which is very usefull to development.
+
+## Prompting
+
+You will notice that there is no traditional prompting involved in 
+Synalinks, everything is described as data models in and out.
+However we use a prompt template, that will tell the system how to 
+construct the prompt automatically.
+
+The prompt template is a jinja2 template that describe how to render 
+the examples, instructions and how to convert them into chat messages:
+
+::: synalinks.src.modules.core.generator.default_prompt_template
+
+The template use the XML tags `<system>...</system>`, `<user>...</user>` and
+`<assistant>...</assistant>` to know how to convert the prompt template 
+into messages. You can modify the default template used by using the 
+`prompt_template` argument in Synalinks modules. You can notice also, 
+that we send the inputs's and output's JSON schema to instruct the LMs
+how to answer, you can enable/disable that behavior by using `use_inputs_schema`
+and `use_outputs_schema` in Synalinks modules. Synalinks use constrained
+structured output ensuring that the LMs answer respect the data models
+specification (the JSON schema), and is ready to parse, so in theory
+we don't need it, except if you use it to provide additional information
+to the LMs. You can find more information in the 
+[`Generator`](https://synalinks.github.io/synalinks/Synalinks%20API/Modules%20API/Core%20Modules/Generator%20module/) documentation.
+
+## Data Models
+
+To provide additional information to the LMs, you can use the data models
+`Field`. You can notice that Synalinks use Pydantic as default data backend.
+Allowing Synalinks to be compatible out-of-the-box with constrained structured output, FastAPI of FastMCP.
+
+```python
+class AnswerWithThinking(synalinks.DataModel):
+    thinking: str = synalinks.Field(
+        description="Your step by step thinking",
+    )
+    answer: str = synalinks.Field(
+        description="The correct answer",
+    )
+```
+
+## Conclusion
+        
+Usually that will be enough to instruct the LMs, you don't need to modify
+the prompt template. Just by adding additional descriptions to the data
+models fields you can instruct your system to behave as you want. 
+If the system needs general instructions about how to behave, you can 
+use the `instructions` argument in Synalinks modules that will be formatted as 
+presented in the prompt template.
+
+### Key Takeaways
+
+- **Ease of Integration**: Synalinks seamlessly integrates with existing
+    Python projects, making it easy to incorporate advanced language 
+    model capabilities without extensive modifications.
+- **Structured Outputs**: By using data models and JSON schemas combined with
+    *constrained structed output*, Synalinks ensures that the LMs responses are structured and ready for parsing, reducing the need for additional post-processing.
+- **Customizable Prompts**: The prompt templates in Synalinks are highly
+    customizable, allowing you to tailor the instructions provided to
+    the LMs based on your specific use case. 
+- **Compatibility**: Synalinks use Pydantic as the default data backend
+    ensures compatibility with structured output, FastAPI or FastMCP.
+"""

docs/Code Examples/First Steps.md

@@ -3,4 +3,4 @@
 - [Concat module](Concat module.md)
 - [And module](And module.md)
 - [Or module](Or module.md)
-- [Xor module](Merging Modules/Xor module.md)
+- [Xor module](Xor module.md)