KonstrukThor

What is KonstrukThor?

KonstrukThor is a programmable embeddable calculator platform. It lets domain experts — product managers, sales specialists, technical consultants, and marketers — create interactive calculation tools without writing frontend code or filing development tickets.

The platform turns a natural-language description into a fully functional, embeddable web widget backed by sandboxed Python logic. A domain expert can go from idea to a live, customer-facing calculator in a single afternoon, with or without any coding knowledge.

How it works

Quick Start

This guide walks you through creating your first calculator from scratch.

1. Sign in

KonstrukThor uses Google OAuth2. Click "Sign in with Google" and authenticate with your work account. You'll be placed into your organization automatically.

2. Create a new calculator

From the dashboard, click New Calculator. Either describe your calculator to the AI agent, or define it manually in the Visual Builder.

3. Define inputs and outputs

4. Write or review the Python logic

Inputs are available as Python variables by their IDs. Assign results to output variable IDs.

import math

area = wall_length * wall_height
tiles_needed = math.ceil(area / tile_size) * (1 + waste_factor / 100)
total_boxes = math.ceil(tiles_needed / tiles_per_box)

5. Run tests and publish

Go to the Tests tab, add test cases, and run them. All tests must pass before publishing. Click Publish and copy your embed code from the Embed tab.

Core Concepts

Calculator

The central entity. A Calculator has a name, input parameters, output parameters, a Python execution script, and a test suite. It belongs to a Team. When published, it is accessible via an embeddable iframe widget.

Parameter

A typed input or output slot. Parameters have IDs (used as Python variable names), display labels, types, optional units, default values, and validation rules. The UI is entirely auto-generated — no frontend code needed.

Execution

When a user submits the form, input values are sent to the runner which executes the Python script in a sandboxed Docker container. The result is returned and displayed. Every execution is logged for analytics.

Team

The isolated unit of work within an organization. Calculators belong to Teams. Team members can only see calculators in their own team.

Organization

The top-level tenant container. One per company. All data is strictly scoped to an organization — users from Company A cannot see anything from Company B.

AI Calculator Generation

The AI agent is trained on KonstrukThor's parameter formats, naming conventions, and Python runner patterns — producing output immediately compatible with the platform.

How to prompt effectively

Be specific about what you want the calculator to do, what inputs users will provide, and what outputs they expect.

AI generation loop

The agent generates, runs its own test cases, checks results, and self-corrects if they fail. The loop continues until all tests pass. You see the final, working result — not intermediate failures.

After generation

Check that all inputs have sensible labels, defaults, and units. Verify the Python logic matches your business rules. Add additional test cases covering real-world edge cases before publishing.

Python Execution Sandbox

All calculator logic runs in an isolated Python environment with strict security guarantees.

Execution architecture

Frontend → POST /api/v1/run/{id}
  → manager publishes RunnerTaskMessage to RabbitMQ
  → task-runner consumes, forwards to runner (port 8081)
  → runner executes Python in sandbox
  → result returned via ReportConsumer

Test Case Framework

Every calculator should have a test suite that verifies the Python logic produces expected outputs for known inputs.

Creating test cases

Under the Tests tab, add a test case with: a descriptive name, one value per input parameter, and expected result values per output parameter.

Numeric tolerance

Numeric outputs are compared with a configurable relative tolerance of 0.1% by default — accommodating floating-point differences without masking genuine errors.

Analytics

Built-in analytics track usage without requiring any separate setup.

• Total executions (all time)
• Daily and monthly run counts with sparkline trends
• Error rates and execution time distributions

Analytics are available per calculator from the dashboard. Each embed location is counted independently in the total execution count.

Frontend Customization

Calculators ship with a clean default theme that works out of the box — but every visual and behavioural aspect is fully overridable. Three independent slots let authors take control progressively, each replacing its default in isolation:

CSS Slot — Styling & Branding

Replace the default stylesheet to match brand colors, typography, spacing, and motion. Most visual tweaks need nothing else. In the builder, go to the Style tab to enter custom CSS. The widget's root element receives a kt-widget class for scoped styling. Changes preview in real time.

HTML Slot — Layout & Structure

Restructure the form entirely: SVG illustrations, image-driven choices, sliders, date pickers, custom layouts. The runtime still collects values by input id/name, so any element shape is fair game. Transform the input form to match any design vision.

JS Slot — Behavior & Interactivity

Define lifecycle hooks (onSubmit, onResult, onError, onInputChange) for conditional visibility, custom validation, animated results, or interactive charts and tables. React to calculation results in real time.

What This Unlocks

• Match the host page so the calculator feels native rather than embedded
• Conditional UX — show "How many kids?" only after "Do you have kids? Yes"
• Rich output presentation — charts, tables, KPI cards rendered from the calculation result instead of plain rows
• Custom input/output types — arrays, objects, and arrays of objects become possible by handling the data shape in the frontend hooks

There is no fixed limit on appearance or interaction: anything HTML, CSS, and JavaScript can express is reachable. The same KonstrukThor AI agent will customize the frontend for you when prompted on the Frontend tab.

iframe Embedding

Embedding requires exactly one line of HTML. The widget handles its own layout, rendering, execution, and output display.

<iframe
  id="calc-frame"
  src="https://your-konstrukthor-host/api/v1/interactive/<calculator-id>"
  width="520"
  height="600"
  frameborder="0"
  allow="same-origin"
></iframe>

Finding the calculator ID

Shown under the Embed tab after publishing, and visible in the URL when viewing the calculator: /calculator/<id>.

postMessage API

The embedding page can pre-fill calculator fields via window.postMessage, enabling wizard-style flows and deep integration with surrounding applications.

Setting values from the parent page

const frame = document.getElementById('calc-frame');

frame.contentWindow.postMessage({
  type: 'setValues',
  payload: {
    length: 12.5,          // number field
    material: 'steel',     // text or select field
    include_vat: true      // yes/no toggle
  }
}, '*');

Accepted value types

Waiting for the iframe to load

frame.addEventListener('load', function () {
  frame.contentWindow.postMessage({
    type: 'setValues',
    payload: { length: 12.5, material: 'steel' }
  }, '*');
});

Finding parameter IDs

Parameter IDs are assigned in the Visual Builder. You can also inspect the rendered embed HTML — each input carries id="<parameter-id>" and name="<parameter-id>".

Organizations

Every account belongs to an Organization — the top-level isolation boundary. Data from one organization is completely inaccessible to another, enforced at the database query level.

Teams within an organization

Organizations contain one or more Teams, each an isolated workspace with its own calculators and members. A user can be in multiple teams with different roles in each.

Roles & Permissions

Inviting Members

Team Leaders can invite colleagues by email. No Org Admin action required.

Deletion Policies

Each team has a configurable Calculator Deletion Policy set by the Team Leader.

Cloud SaaS

Fully managed by KonstrukThor. No infrastructure to manage.

• Deployment on AWS (EC2/ECS, RDS PostgreSQL, RabbitMQ)
• Custom domain and SSL configuration
• All updates and security patches
• Backups and monitoring included
• Support per tier SLA

Self-Hosted Deployment

Full data sovereignty for organizations that require on-premise deployment or restricted network environments.

Infrastructure requirements

Services in the Docker Compose package

Key environment variables

JWT_ACCESS_SECRET         # JWT access token secret
JWT_REFRESH_SECRET        # JWT refresh token secret
GOOGLE_CLIENT_ID          # Google OAuth2 client ID
GOOGLE_CLIENT_SECRET      # Google OAuth2 client secret
GOOGLE_REDIRECT_URI       # OAuth2 redirect URI
FRONTEND_URL              # Base URL of your deployment
JDBC_DATABASE_URL         # PostgreSQL JDBC URL
DATABASE_USERNAME         # Database user
DATABASE_PASSWORD         # Database password
RABBIT_MQ_URI             # RabbitMQ connection URI
ANTHROPIC_API_KEY         # Claude API key for AI generation
CORS_ALLOWED_ORIGIN       # Your domain (e.g. https://calc.yourcompany.com)

Authentication

KonstrukThor uses Google OAuth2 with JWT tokens for session management.

1. User clicks "Sign in with Google"
2. Redirected to Google OAuth2 consent screen
3. On success, receives a short-lived access token (expires 60s) and a refresh token stored in PostgreSQL
4. Access token sent as Bearer in API headers. Expired tokens refreshed via POST /oauth/access_token

Pricing Reference

Frequently Asked Questions

General

Do domain experts need to know Python?

No. The AI agent generates all Python logic. Experts review outputs and test results. Optionally, experts comfortable with Python can edit logic directly — but it's never required.

Can I use KonstrukThor without the AI agent?

Yes. The Visual Builder lets you define inputs, outputs, and Python logic manually. The AI agent accelerates the process significantly but is not mandatory.

What happens if the Python script has an error?

Execution errors are caught by the sandbox, logged, and returned as an error message — they cannot crash the platform. The error rate is tracked in analytics.

Embedding

Can I embed on multiple websites?

Yes. A single calculator can be embedded on any number of pages. Each embed is an independent iframe. Analytics tracks total executions across all locations.

Does embedding require JavaScript?

No. The basic iframe embed works without any JavaScript on the parent page. The postMessage API (for pre-filling values) requires a small JavaScript snippet but is entirely optional.

Security & Data

Where is data stored?

For Cloud SaaS: AWS PostgreSQL RDS, EU region. For self-hosted: entirely on your own infrastructure — we have no access to it.

Can scripts access external services or data?

No. Network access is completely disabled in the sandbox. Scripts cannot make HTTP requests, connect to databases, or access any external service.

Teams & Access

Can a user belong to multiple teams?

Yes. A user can be a member of multiple teams within the same organization, with different roles in each. Teams are accessible from the dashboard.

What happens to calculators if a Team Leader leaves?

The Organization Admin can access all teams regardless of membership and can manage any team leadership transition.

Billing & Plans

Can I start with a trial?

Yes. Cloud SaaS offers the first month free or 50% off for 3 months. Self-hosted plans offer a 30-day trial via Docker Compose locally. Ask during your demo call.

What does the setup fee cover?

The setup fee (6,000–20,000 Kč for SaaS) covers deployment to AWS, environment configuration, custom domain and SSL, and an onboarding session. It's a one-time cost — the monthly subscription covers hosting, maintenance, support, and updates.

Can I switch between SaaS and self-hosted?

Yes. Migration between the two deployment models is possible. Contact us to discuss the migration process for your data and configuration.