QuickStart

Your First Steps with Shimoku

If you are interested in the AI functions, have a look here: Artificial Intelligence

Setting Up Your Local Server

Begin your journey with Shimoku by setting up a local server. This process allows you to explore Shimoku's capabilities without needing to log in or create an account.

Step 1 - Install the Library

To use Shimoku’s API first install our SDK library

See it from Github at:

https://github.com/shimoku-tech/shimoku-api-python

And in your Python +3.9 install it

pip install shimoku

Step 2 - Initialize the Server for the Playground

In this step you will have to use the a terminal in your environment and type the following command:

> shimoku playground init

You will see that the terminal is showing the logs from the server, then you can follow to the next step.

In case the default port (8000) is already in use, it is necessary to change it in the command for example, the port 8080 could be used:

> shimoku playground init --local-port 8080

It is not recommended to have more than one local server running, as the front-end application can only access one at a time (even in different tabs).

Step 3 - Initialize the Shimoku SDK

Now you will have to use a python script, start by importing the client from the shimoku library and initializing it. This step sets up a local server environment for your development and automatically opens a browser.

from shimoku import Client

s = Client()

We recommend the following parameters for a better development experience:

s = Client(
    async_execution=True,  # Grouped plotting
    verbosity='INFO',      # Insight in the execution
)

If you have used a port for the server that is not 8000 you will have to set it in the initialization of the client:

s = Client(
    local_port=8080,
    async_execution=True,
    verbosity='INFO'
)

Code Example

When changes are made locally using the s.run() command, the SDK provides immediate feedback to the front end. This live update system ensures developers can see the impact of their changes in real time:

# Necessary for compatibility with cloud execution
s.set_workspace() 

# Set the group of the menu
s.set_board('Custom Board')

# Set the menu path 'catalog' with the sub-path 'bar-example'
s.set_menu_path('catalog', 'bar-example')

language_expressiveness = [
    {'Language': 'C', 'Statements ratio': 1.0, 'Lines ratio': 1.0},
    {'Language': 'C++', 'Statements ratio': 2.5, 'Lines ratio': 1.0},
    {'Language': 'Fortran', 'Statements ratio': 2.0, 'Lines ratio': 0.8},
    {'Language': 'Java', 'Statements ratio': 2.5, 'Lines ratio': 1.5},
    {'Language': 'Perl', 'Statements ratio': 6.0, 'Lines ratio': 6.0},
    {'Language': 'Smalltalk', 'Statements ratio': 6.0, 'Lines ratio': 6.25},
    {'Language': 'Python', 'Statements ratio': 6.0, 'Lines ratio': 6.5},
]

s.plt.bar(
    order=0, title='Language expressiveness',
    data=language_expressiveness, x='Language',
    y=['Statements ratio', 'Lines ratio'],
)

# Necessary for notifying the front-end even if not using async execution
s.run()

Deployment in Cloud

The deployment with the Shimoku platform is very straightforward, just set your credentials in the client initialization and execute the same code you've been developing:

from shimoku import Client 

access_token: str = getenv('API_TOKEN')     # Environment variable
universe_id: str = getenv('UNIVERSE_ID')    # Environment variable
workspace_id: str = getenv('WORKSPACE_ID')  # Environment variable

s = Client(
    access_token=access_token,
    universe_id=universe_id,
    async_execution=True,
    verbosity='INFO'
)

s.set_workspace(workspace_id)

. . .
  • If you don't have these credentials you will need to create an account here, consult the Shimoku Cloud for further information.

  • It is advisable to make sure that the contents of the playground can be replicated by the code before deploying.

Sharing Your Insights: Embedding and Beyond

Shimoku's sharing functionality transforms the way you incorporate analytics into web platforms, enabling you to deliver personalized insights to your audience and add significant value to your product offerings with minimal development efforts.

Creating a Shareable Board

Update your persisted Board with the CLI in Shimoku Cloud to make it shareable.

> shimoku cloud update board --board {YOUR BOARD NAME OR ID} --is-public

And that's it!

Now, to access the link through the Front End, you must click in the chain of your board:

You can read more about our Shared boards by reading this section: Shared links

Key Features and Advantages

The Shimoku Playground is an integral feature of the Shimoku platform, designed to facilitate local development.

  • Local Server Utilization: Instead of connecting to the cloud-based Shimoku API, the Playground operates via a local server. This setup is initialized through the SDK, offering a more immediate and responsive development environment.

  • Consistent API Compatibility: Code developed within the Playground is fully compatible with the Shimoku API. This ensures a smooth transition from local to cloud-based environments, allowing developers to switch between local and cloud deployments without needing to modify their code.

  • No Token Consumption: The Playground runs on the developer's local machine, bypassing the need for token usage associated with cloud-based operations on the Shimoku platform. This is particularly beneficial for extensive testing and development, as it reduces the overhead costs typically incurred during the development process.

Last updated