SuperAPI AI Directory

jk-sdk-setup

Coding & development

View repository

Updated 10-16 02:33

About this skill

Jinkō SDK Setup

Use this skill for SDK setup and credential checks only. Keep the user focused on proving that Python can authenticate against Jinkō and read one project item list before moving to model, vpop, protocol, output-set, or trial workflows.

Workflow

  1. Confirm the user has Python 3.10+.
  2. Install the SDK and dotenv support when needed: pip install jinko python-dotenv.
  3. Ask the user to create an API key using https://doc.jinko.ai/docs/api/ if they do not already have one.
  4. Ask the user to set JINKO_API_KEY and JINKO_PROJECT_ID in their shell or local .env file.
  5. Point them to assets/.env.example as the safe template. Do not ask them to paste secrets into chat.
  6. Run or adapt scripts/check_jinko_connection.py to fail fast on configuration, authentication, authorization, or project-read-access issues.
  7. If the check passes, report that the Jinkō connection is OK.
  8. When the user wants to browse the project after setup, recommend client.search(...) as the default read-only exploration call before moving to a workflow-specific skill.

Required Configuration

  • JINKO_API_KEY: API key created in the Jinkō web interface.
  • JINKO_PROJECT_ID: project identifier used by the SDK for X-jinko-project-id.

The SDK also supports JINKO_BASE_URL, but do not introduce alternate environments unless the user explicitly needs them.

Validation Script

Use the bundled script instead of writing ad hoc checks:

python skills/jk-sdk-setup/scripts/check_jinko_connection.py

The script:

  • Loads .env when python-dotenv is installed.
  • Redacts sensitive values when showing configuration.
  • Requires both JINKO_API_KEY and JINKO_PROJECT_ID.
  • Constructs JinkoClient() from environment variables.
  • Calls client.auth_check() to prove authentication and project read access.
  • Prints minimal output on success.

Use --show-config only when debugging local setup; it prints presence and redacted values, never the full API key.

After Validation

Once the connection check passes, prefer client.search(...) for project exploration because it gives the user an immediate view across project items.

Use a minimal example like:

from jinko import JinkoClient

client = JinkoClient()
client.search(limit=20, table_columns="compact")

Use search() when the user wants to:

  • browse what exists in the configured project
  • find an item by name or free text
  • orient themselves before choosing a model, protocol, vpop, or trial workflow

Keep the setup script focused on authentication and access checks. Use search() only after validation succeeds, not as a replacement for the fail-fast check.

Troubleshooting

  • For ConfigurationError, check that .env or the shell environment contains both required variables.
  • For missing JINKO_API_KEY, direct the user to https://doc.jinko.ai/docs/api/.
  • For AuthenticationError, assume the API key is missing, expired, malformed, or copied incorrectly.
  • For AuthorizationError, assume the API key is valid but does not have access to the requested project.
  • For other SDK request failures, check that JINKO_PROJECT_ID is copied exactly and that the network can reach Jinkō.
  • For import errors, reinstall with pip install jinko python-dotenv in the active Python environment.
  • If the user uses direnv, ask them to ensure .envrc loads .env, then run direnv allow.

Reference Routing

Read references/setup-check.md when you need implementation details for the bundled script or a concise explanation of the fail-fast check.