You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Mar 7, 2025. It is now read-only.
**Is your documentation update related to a problem/software issue? Please describe.**
17
+
A clear and concise description of what the problem is. Ex. The API documentation must be updated [...] , The project team changed, we need to update the project team markdown file [...], etc.
18
+
19
+
**Additional context**
20
+
Add any other context or screenshots about how documentation must be updated.
## <aname='SetuptheDevelopmentEnvironment'></a>Setup the Development Environment
27
+
## Setup the Development Environment
27
28
28
-
### <aname='Pre-requisites'></a>Pre-requisites
29
+
### Pre-requisites
29
30
30
31
- Python version >= 3.9.
31
32
- Setup a virtual environment (using [venv](https://docs.python.org/3/library/venv.html) or [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)) and activate it.
32
33
- You need to **activate this environment every time** before you want to make changes to this repository.
33
34
34
-
#### <aname='UsingVenv'></a>Using Venv
35
+
#### Using Venv
35
36
```bash
36
37
python -m venv .venv # Create your Virtual environment
37
38
source .venv/bin/activate # Activate and use your virtual environment
@@ -40,16 +41,23 @@ source .venv/bin/activate # Activate and use your virtual environment
40
41
# And once you're all done..
41
42
deactivate
42
43
```
44
+
### Fork the official repo
43
45
46
+
1. Navigate to https://github.com/IBM/ibm-generative-ai repository.
47
+
2. In the top-right corner of the page, click **Fork**.
48
+
*Important: **DO NOT** select 'Copy the DEFAULT branch only' option.*
49
+
3. Click **Create fork** .
44
50
45
-
### <aname='Clonerepoandcheckoutdevbranch'></a>Clone repo and checkout dev branch
51
+
Further information on how to fork a GitHub repository is avaiable [here](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
Minimal pip version is 22.0.1. Check your pip version with `pip --version` and if needed run the following command to upgrade pip.
55
63
```bash
@@ -64,7 +72,7 @@ Install pre-commit setup
64
72
pre-commit install
65
73
```
66
74
67
-
### <aname='SetupyourIBMGenAItoken'></a>Setup your IBM Generative AI token
75
+
### Setup your IBM Generative AI token
68
76
Login to [workbench.res.ibm.com/](https://workbench.res.ibm.com/) and get your IBM Generative AI API key. Then, create a `genai/.env` and assign the `GENAI_KEY` value as:
69
77
```
70
78
GENAI_KEY=<your key here>
@@ -73,17 +81,20 @@ GENAI_KEY=<your key here>
73
81
Once done, you and genai can use your key using `os.getenv("GENAI_KEY")` and you will not
74
82
have to worry about committing it to GitHub.
75
83
76
-
## <aname='MakeChanges'></a>Make Changes
84
+
## Make Changes
77
85
Create a branch for making changes
86
+
78
87
```bash
79
-
git checkout -b <my_awesome_branch>
88
+
git checkout -b <my_awesome_branch> develop
80
89
```
90
+
*Important: Note we branched off 'develop' not 'main'*
91
+
81
92
Make your changes and add any unit tests. Run tests as
82
93
```bash
83
94
python -m pytest
84
95
```
85
96
86
-
## <aname='CommitChangesandMakeaPullRequest'></a>Commit Changes and Make a Pull Request
97
+
## Commit Changes and Make a Pull Request
87
98
Once you are done making changes, run `flake8` for linting and try fixing for as many messages as possible.
88
99
```bash
89
100
flake8 .
@@ -100,12 +111,15 @@ Push your changes
100
111
```bash
101
112
git push origin HEAD
102
113
```
103
-
Raise a pull request from your `<my_awesome_branch>` containing changes to `dev` branch by going to github page of the repo.
114
+
Raise a pull request from your `<my_awesome_branch>` in the `head repository` to the `develop` branch in the `base repository`. To do so go to the github page of the repo. The image below shows an example:
- Wait for tests to pass. If they fail then try to fix issues. Get in touch with the core team if needed. They will get back to you for anything that needs to be addressed.
107
121
108
-
## <aname='Logging'></a>Logging
122
+
## Logging
109
123
110
124
GenAI uses the standard python logging module for logging debug messages within the module. Unless the consuming application explicitly enables logging, no logging messags from GenAI should appear in stdout or stderr e.g. no `print` statements, we should also always log to the `genai` namespace so that logs are easily identifiable.
Open-source contributors are welcome to extend IBM Gen AI functionality via extensions that must keep the IBM Gen AI package as a dependency. This document explains what extensions are, the types of extensions that exist, and how to create them.
3
+
4
+
# Table of Contents
5
+
-[About the core package](#ibm-generative-ai-core-package)
6
+
-[What is an extension?](#what-is-an-ibm-generative-ai-extension)
7
+
-[Types of extensions](#ibm-generative-ai-extension-types)
[IBM Generative AI open-source repository](https://github.com/IBM/ibm-generative-ai) lives under [IBM Github organization](https://github.com/IBM/). This repository is the official and unique location of IBM Gen AI core package source code.
13
+
14
+
# What is an IBM Generative AI Extension?
15
+
An extension is a software add-on that is installed on a program to enhance its capabilities. Gen AI extensions are meant to expand the capabilities of the Gen AI core package. For instance, imagine that you want to build a prompt pattern with data from a pandas dataframe. You could write your own code to achive such functionaliy, or you could instead use the Gen AI Pandas extension. Using the extension will allow you to save development time and deliver an elegant solution that re-uses code when it is possible.
16
+
17
+
# IBM Generative AI Extension types
18
+
IBM Generative AI extensions can be either of the following :
19
+
- official open-source extensions (supported by the project team)
20
+
- third-party open-source extensions
21
+
22
+
## Open-source "Gen AI official" extensions
23
+
Extensions that are meant for public use from the get-go should instead be developed as official open-source extensions. Examples of official extensions that have already been released are LangChain, Pandas, and Hugging Face extensions.
24
+
25
+
### Ownership and location
26
+
Open-source extensions should be submitted directly to the [IBM Generative AI open-source repository](https://github.com/IBM/ibm-generative-ai) and should be developed following the [open-source Gen AI contribution guide](https://github.com/IBM/ibm-generative-ai/blob/main/DEVELOPMENT.md). Open-source official extensions are typically developed by the Gen AI team, or in collaboration with them. Providing maintenance to open-source official extensions is responsability of the Gen AI team.
27
+
28
+
## Open-source "third-party" extensions
29
+
All other extensions neither implemented nor officially maintained by the Gen AI team are referred to as open-source third-party extensions.
30
+
31
+
### Ownership and location
32
+
Open-source third-party extensions can live anywhere, inside [IBM organization](https://github.com/IBM/), the wider Github universe, or other contributors' own Github spaces (e.g., other IBM teams, clients, partners). Maintaining these extensions would be the responsibility of their owners.
33
+
34
+
# Extensions migration
35
+
Extensions might be migrated from one type to another upon evaluation and approval of the Gen AI maintenance team. Below, we describe two common migration scenarios:
36
+
37
+
## Open-source "third-party" to open-source "Gen AI official"
38
+
If open-source third-party contributors have an interest in their extensions becoming official, they must contact the IBM Gen AI team. The Gen AI team will evaluate the request considering novelty and implementation quality (meaning it was developed following the Gen AI official guide and meets Gen AI extensions' design considerations). If the request is approved, the Gen AI team will assist the extension owners in migrating the extension.
39
+
40
+
## Open-source "Gen AI official" to Gen AI's core
41
+
Upon evaluation of the Gen AI maintenance team, open-source extensions could be merged with Gen AI core code and become deprecated as extensions. Deprecation announcements will be shared as part of the release notes of every new version of the IBM Gen AI package.
42
+
43
+
# Design considerations to build extensions
44
+
Among other patterns, a developer should consider a mix-and-match of the two following important development experience patterns to design an extension for IBM Gen AI SDK:
45
+
46
+
## Extensions that simulate being part of a core class
47
+
48
+
In spite of the extension's code living in a separate location, **try to give the impression that extended functionality is part of an IBM Gen AI core class**.
49
+
50
+
The code snippet below shows an example of this pattern. While `from_template` method is part of an extension class (`PromptExtension`) and not a core class (`PromptPattern`), the way it is being called gives end-users the impression that the method is part of the `PromptPattern` core class. The magic that enables providing this development experience is the use of decorators at import time. This pattern enables extending user-facing classes in a user-friendly way.
Designing extensions that do not integrate, but **wrap functionality in Gen AI's core** for common use cases. These classes are meant to be used as entities on their own.
60
+
61
+
The `LangChainInterface` class (see below) is an example of this pattern. `LangChainInterface` is a subclass of langchain's `LLM` class that wraps `generate` functionality of Gen AI's Model.
62
+
63
+
```python
64
+
...
65
+
66
+
try:
67
+
from langchain.llms.base importLLM
68
+
from langchain.llms.utils import enforce_stop_tokens
69
+
exceptImportError:
70
+
raiseImportError("Could not import langchain: Please install ibm-generative-ai[langchain] extension.")
71
+
72
+
...
73
+
74
+
classLangChainInterface(LLM, BaseModel):
75
+
```
76
+
77
+
Click [here](https://github.com/IBM/ibm-generative-ai/blob/main/src/genai/extensions/langchain/llm.py)" to check the full definition of this class.
## <aname='ContributionInfo'></a>Important Information for Contributors
319
330
320
-
Please read our [contributing guide](DEVELOPMENT.md)for details on our code of conduct and details on submitting pull requests.
331
+
IBM Generative AI is an open-source project that welcomes the community to contribute with documentation, tests, bug corrections, and new fuctionality in the form of [extensions](/EXTENSIONS.md). Please read our [code of counduct](/CODE_OF_CONDUCT.md)to learn the expected behavior from participants that contribute to the project, and our [contribution guide](DEVELOPMENT.md) to learn the gitflow and steps to submit pull requests.
0 commit comments