How To…
Check out how to create, run and submit a Model based on the Credmark Model Framework. Additionally, before submitting your final model, check our model guidelines and how to build a good model and create a good PR.
Create a Model
A model is simply a decorated class that inherits from credmark.cmf.model.Model
and implements a run()
method that takes an input and returns an output.
To get started, you can use the CLI credmark-dev command to create a new model skeleton python file using something like:
credmark-dev create my_models hello_world
This will create a model in the folder models/contrib/my_models/hello_world.py
.
In the command above you can replace my_models
with your username or a unique folder name for your models and replace hello_world
with the name you wish to use for the file.
The skeleton file will contain a subclass of credmark.cmf.model.Model
decorated with the credmark.cmf.model.Model.describe()
decorator @Model.describe
, something like the following example:
from credmark.cmf.model import Model, EmptyInput
@Model.describe(slug='contrib.hello-world',
version='1.0',
display_name='Hello World',
description="A test model to say hi.",
developer='Credmark',
category='example',
input=EmptyInput,
output=dict)
class HelloModel(Model):
def run(self, input: EmptyInput) -> dict:
return {'message': 'Hello world!'}
From your model’s run()
method, you can access self.context
which gives you access to the context of chain id, block number, a configured web3 instance, and utilitie to access ledger data, to call other models, and more. See credmark.cmf.model.context.ModelContext
for more details.
Run a Model
To see a list of all models available, use the command:
credmark-dev list
You can then pick a model name (slug) and run the model by using the command:
credmark-dev run <Specify Slug> -b <Specify block number> -i <Specify Input>
so for example
credmark-dev run cmk.circulating-supply -b 14000000 -i '{}'
Tip: you can run the command
credmark-dev list --manifests
to see the input data format required for each model. It will also show the output formats.
Submit a Model
If you are a contributor external to credmark, you should create your folder in [credmark-models-py/models/contrib].
You should create and keep your models under this folder. Note that we have applied additional conditions for model slug names under this folder. Slug name must start with contrib.<model-name>
, so for example: Slug = ‘contrib.sample-model
.
If you are a contributor external to credmark, you should create your folder in [credmark-models-py/models/contrib].
You should create and keep your models under this folder. Note that we have applied additional conditions for model slug names under this folder. Slug name must start with contrib.<model-name>
, so for example: Slug = ‘contrib.sample-model
.
Once your model is ready to submit, simply create a pull request on the github repo and let us know in our Discord.
Model Guidelines
What makes a good model? In general, good Models Should be:
Generalized
Short
Legible
Strict
NOTICE: These checks either ARE or WILL be added as automated Checks on PRs.
Here’s a passing test on github: ✅
Here’s a failing test on github: ❌
The Good Model Checklist
Check your model.describe() decorator
[ ] Increment the Version Number when you update your model
[ ] The Slug is Unique
[ ] The Slug is correctly Namespaced
[ ] The Display Name is descriptive but not too long
[ ] The Description describes what the model does
[ ] The DTOs describe the Inputs and Outputs schemas
Check the model’s content
[ ] It does one thing, and it does it well
[ ] It conforms to it’s type definition
[ ] Does the client have the ability to ask for what they want?
[ ] Do you set good default inputs?
[ ] Don’t make historical calls within models unless absolutely necessary.
Check the code
[ ] It raises ModelDataError instead of returning None or 0
[ ] It returns a DTO, and uses a framework DTO if it exists.
[ ] It doesn’t have any print() statements.
[ ] It passes linting tests.
[ ] There are no global functions that aren’t models.
Check the legibility
[ ] It is a minimal number of lines of code to get the job done
[ ] It uses descriptive variable names
Check for repetition
[ ] It calls other models if they exist
[ ] It uses the framework tools if they exist
Check that your actions are allowed on your model type:
Calls Contract Functions |
Calls Database |
Calls other Models |
Has hard-coded Data |
Transforms Input Data |
|
---|---|---|---|---|---|
Models that fetches data |
✅ |
✅ |
⚠️ |
❌ |
❌ |
Algorithmic models |
❌ |
❌ |
⚠️ only other algorithms |
❌ |
✅ |
Models that stitch together other models |
❌ |
❌ |
✅ |
❌ |
❌ |
Models that have hardcoded configuration |
❌ |
❌ |
❌ |
✅ |
❌ |
The Good PR Checklist
[ ] It has no merge conflicts
[ ] It doesn’t break other models
[ ] It builds and runs
[ ] It passes github tests
Pylint settings: https://github.com/credmark/credmark-models-py/blob/main/.pylintrc
At the command-line, run: pylint models
[ ] It is under the maximum PR size:
2 files changed
4 models changed
200 lines of code changed
[ ] For each model
Does it pass the checklist
[ ] For each DTO
Does it already exist in the Framework?
Is it materially different from the existing DTOs
Bugs, Issues, and Support
The Credmark Model Framework is under active development, thus there will be some bugs or issues that may cause problems.
We encourage all modelers to join our Discord, pick the role “Engineering” and post any issues the in the channel #framework-help. The Discord shall be the place to ask general questions about how to do something or if you have data-related questions.
If you want to report a bug, unexpected behavior, or feature request, you can raise an issue in Github directly but we encourage you in this case as well to notify the community in Discord.