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
<imgsrc="https://colab.research.google.com/assets/colab-badge.svg"alt="Open In Colab"/>
56
+
</a>
9
57
10
58
## Contributing
11
59
12
-
### General Requirements
13
-
14
60
For information about contributing to this repo, code of conduct guidelines, etc., see the community [CONTRIBUTING][CG] and [Code of Conduct][CoC] guides. All commits require DCO-signoff (discussed [here][CG-legal]) _and_ GPG or SSH signing (discussed [here][CG-signing]). The GitHub recommended code security settings are enforced on this public repository (which include the signing requirement).
15
61
16
-
### What is a "Recipe"?
17
-
18
-
A "cookbook" is composed of "recipes".
19
-
In this version of the Granite Code Cookbook, a "recipe" is a Python notebook.
20
-
21
-
Under the implied cooking analogy, there are three key defining elements of a
22
-
good recipe:
23
-
24
-
1. It clearly states the required ingredients and tools up front
25
-
2. It is straightforward to reproduce efficiently
26
-
3. It results in something delicious to eat
27
-
28
-
The "ingredients" and "tools" of the first point mean the data and software at hand.
29
-
30
-
The second point is straightforward to map into the technical space:
31
-
The reader should be able to run the cells of the notebook sequentially
32
-
and the same result as what was published in the original notebook.
33
-
Our objective is to make these recipes reproducible in 15 minutes or less.
34
-
This may inform the decisions about recipe granularity.
35
-
36
-
The third point is more subtle, and is what sets this kind of writing apart.
37
-
In a technical sense, "something delicious to eat" means a system
38
-
that demonstrates useful functionality in such a way that it sets the
39
-
reader on the path to adopting it in their environment. It clearly articulate the business value achieved by the resulting system.
40
-
41
-
For a "text to sql" recipe, for instance, the recipe should:
42
-
43
-
- State at a high level how a "text to sql" capability could create "business value", and therefore be worth the investment.
44
-
- Provide example schema
45
-
- Provide example data
46
-
- Provide example natural language queries
47
-
- Show the expected resulting SQL
48
-
- Provide enough code to walk through the whole process
49
-
- Remind or show the reader how to obtain the schema and execute the query.
50
-
51
-
For recipe authors with strong familiarity with a specific capability or tool,
52
-
the first inclination may be to write a recipe oriented around the tool.
53
-
Consider alternate ways to phrase the recipe so that the end result is showcased, rather than the tool.
54
-
55
-
Under the cooking analogy, that would mean writing a great soup recipe rather than one that talks about the features of a food processor. If the soup tastes great and is easy to prepare, the reader will likely want to know more about how it was made.
56
-
57
-
Recipes will vary in complexity.
58
-
Some may be single inference calls.
59
-
Others may illustrate useful agentic workflows.
60
-
61
-
A "cookbook" is not intended to be a comprehensive guide to all
62
-
issues that may arise during development with Granite Code.
63
-
Recipes will link to helpful external resources on topics including: distributed systems, UI, design, AI/ML theory, metrics, etc.
64
-
65
-
### Exceptions
66
-
67
-
While the majority of the content in the Granite Code Cookbook
68
-
should be "recipes", there will be a need for other kinds of exposition.
69
-
70
-
Relating to Granite Code, these might include:
71
-
72
-
- Generally useful VS Code plugins
73
-
- Application frameworks such as LangChain (and LangServe, LangGraph, ...) and LlamaIndex
74
-
75
-
### Granite Code
76
-
77
-
The common element of all the recipes in this Cookbook is either direct usage of a Granite Code model, or strong relevance to those models.
78
-
79
-
### Everything Local (... except, perhaps, the model)
80
-
81
-
Minimize the reader's exposure to sign-up flows and stateful network calls.
82
-
83
-
In most cases, the user should expect to do a single `git clone`,
84
-
run a notebook, and then optionally do some `pip install` early in
85
-
the execution of the notebook.
86
-
87
-
The recipes should not depend on the model being either remotely hosted
88
-
or local. It is OK for a recipe to make a choice, but providing a link
89
-
to instructions for the other choice is useful.
90
-
91
-
### Automated Validation
92
-
93
-
The code in the recipes will be automatically validated (coming soon).
94
-
Minimally, this should guarantee that no unexpected errors occur.
95
-
Checking deeper assertions about the behavior of the code
96
-
in the cells is preferred.
97
-
98
-
### Performance
99
-
100
-
Where available and appropriate, cite specific relevant expectations
101
-
and claims for quality, latency, cost, or any other relevant metrics.
102
-
103
-
In some cases, it may be appropriate to include a demonstration
104
-
of establishing those benchmarks.
105
-
106
-
### Other general guidance
107
-
108
-
- The Developer Certificate of Origin (DCO) applies to the code, documentation, and any example data provided. See community CONTRIBUTING guide [legal section][CG-legal] for more on the DCO.
109
-
- Commits must be GPG or SSH signed. See the community CONTRIBUTING guide [signing commits section][CG-signing] for details.
110
-
- Prefer an opinionated recipe over one that is flexible.
111
-
- With that said, sometimes offering examples from multiple domains (eg for "text to sql") can be helpful. If that brings too much complexity, split into smaller recipes.
112
-
- Keep in mind a specific user persona when writing a recipe. Rather than writing for a general audience, can you imagine that one specific user would find the recipe valuable from beginning to end?
113
-
- Take an iterative approach to the development of this Cookbook.
114
-
- Expect that over time, recipes will be split, merged, made uniform, deprecated, replace, or deleted.
115
-
- The `ibm-granite-community` org does not host OSS "code" other than what is directly visible in the recipes and simple utility functions.
62
+
For more background and a FAQ, please see the [community wiki](https://github.com/ibm-granite-community/community/wiki)
116
63
117
64
## Licenses
118
65
@@ -126,7 +73,7 @@ Any example datasets committed to this repository are licensed under CDLA Permis
126
73
127
74
All content in these repositories including code has been provided by IBM under the associated open source software license and IBM is under no obligation to provide enhancements, updates, or support. IBM developers produced this code as an open source project (not as an IBM product), and IBM makes no assertions as to the level of quality nor security, and will not be maintaining this code going forward.
0 commit comments