{% extends "base.html" %}

{% block title %}IAToolkit - Foundation{% endblock %}

{% block styles %}
    <link rel="stylesheet" href="{{ url_for('static', filename='styles/landing_page.css') }}">
{% endblock %}

{% block content %}
<div class="container-fluid p-0">
    {% include '_static_header.html' %}
</div>

<div class="article-container">
    <header class="article-header">
        <h1 class="article-title">IAToolkit: Building Real Enterprise AI Assistants on Your Own Data</h1>
        <p class="article-subtitle">
            A practical guide for CTOs and developers who want to build real AI assistants connected to corporate data.
        </p>
    </header>

    <div class="article-content">

    <p>
      Over the last two years, many teams have experimented with “AI chatbots” for their business.
  Some early prototypes appeared promising during internal reviews, but very few held up once
  confronted with production expectations—authentication, data accuracy, security controls,
  and real users with unpredictable questions.

<p>
  The core lesson from early experiments is clear: LLMs often work beautifully in theory,
  but fail in real-world scenarios unless they are connected to reliable data, structure,
  context, and tools. IAToolkit was built precisely to solve that gap.
</p>


    <p>
      IAToolkit is an open-source framework designed specifically for that gap.
      It gives you a complete, production-ready base for building AI assistants that:
      connect to your corporate databases, run custom tools, query private documents
      using RAG, and serve multiple companies or business units from a single, clean architecture.
    </p>

    <p>
      This article is written for technical founders, developers, and CTOs who want to understand
      what IAToolkit offers, how it’s architected, how multi-tenancy works,
      and what a small real-world implementation project looks like.
    </p>

    <hr />

    <!-- Chapter 1 -->
      <h2>1. The Problem IAToolkit Solves</h2>


      <p>
          In simple terms, an AI assistant is like an internal ChatGPT for your company:
          a private, secure interface where people can ask questions and run tasks in natural language.
          It plays a role similar to the intranet in the 2000s—a central gateway to internal knowledge and processes.
      </p>

      <p>
          If you’ve tried to build an internal AI assistant, you’ve probably run into some of these issues:
      </p>

      <ul>
          <li>
              <strong>Chatbots disconnected from real data.</strong>
              Many “LLM chatbots” only work with a simple vector store or a few uploaded PDFs
              and cannot query real business databases.
          </li>
      <li>
        <strong>One-off architectures for every POC.</strong>
        Each proof of concept becomes its own fragile stack with duplicated logic.
      </li>
      <li>
        <strong>No real workflow integration.</strong>
        Prototypes rarely evolve into assistants that send emails, call APIs,
        or trigger internal processes.
      </li>
      <li>
        <strong>Vendor lock-in.</strong>
        Closed platforms limit customization and transparency.
      </li>
      <li>
        <strong>Multi-client deployments are painful.</strong>
        Forking code for each client or department does not scale.
      </li>
    </ul>

    <p>
      IAToolkit solves these issues by providing a framework built specifically for real-world scenarios:
      a full web app, multi-tenant architecture, SQL access, RAG, tool calling,
      logging, extensibility, and a clean Python API.
    </p>

    <hr />

<h2>2. Inside the Architecture: A Framework You Can Trust</h2>

<p>
  IAToolkit is designed with a clear, layered architecture that keeps concerns separated and makes the system easy to maintain, extend, and reason about. Each part of the framework plays a specific role, ensuring that your assistant remains robust as it grows in complexity.
</p>

<p>
  The framework organizes its logic into well-defined layers:
</p>

<ul>
  <li><strong>Views</strong> handle HTTP requests, authentication, sessions, and JSON/HTML responses.</li>
  <li><strong>Services</strong> orchestrate core workflows—query handling, RAG, prompt rendering, authentication, history, feedback, and configuration.</li>
  <li><strong>Repositories</strong> provide structured access to the internal database using SQLAlchemy.</li>
  <li><strong>Infrastructure adapters</strong> connect to external systems such as LLM providers (OpenAI, Gemini), mail services, and file storage like S3.</li>
  <li><strong>Common utilities</strong> include helpers for encryption, validation, routing, and error handling.</li>
</ul>

<p>
  Under the hood, IAToolkit is a well-structured Flask application that keeps its components cleanly
    separated and easily testable through a clear service and module layout.
    It uses SQLAlchemy as its ORM to provide consistent, predictable data access,
    and relies on a comprehensive suite of automated tests to ensure reliability as
    you extend the framework with new companies, tools, and workflows.
</p>
    <hr />

    <!-- Chapter 3 -->
    <h2>3. Building a Multi-Tenant Assistant</h2>

    <p>
      One of the most powerful ideas in IAToolkit is the concept of a <strong>Company</strong>.
      A Company is a self-contained module that defines everything the AI needs
      to operate within a single business domain or client:
      data sources, prompts, tools, documents, branding, and context.
    </p>

    <h3>3.1 The Company Module: A Clean Boundary per Tenant</h3>

    <p>
      Each Company lives in its own directory, for example:
    </p>

    <pre><code>companies/
  ├── sample_company/
  │   ├── config/
  │   ├── context/
  │   ├── schema/
  │   ├── prompts/
  │   └── sample_company.py
  └── your_company/
      ├── config/
      ├── context/
      ├── schema/
      ├── prompts/
      └── your_company.py
    </code></pre>

    <p>
      This structure gives you a natural, file-system level isolation:
      each client or business unit gets its own folder with its own configuration and resources.
      For agencies and SaaS providers, this means you can host many clients in the same deployment,
      while keeping their logic and knowledge cleanly separated.
    </p>

    <h3>3.2 Per-Company Directories: Config, Context, Schema, Prompts</h3>

    <p>
      Each Company has several dedicated directories:
    </p>

    <ul>
        <li>
            <strong><code>config/</code></strong>:
    Contains the core configuration files for the assistant.
    The most important is <strong><code>company.yaml</code></strong>, which defines
    the company’s name, branding, LLM models, SQL connections, tools,
    document sources, and prompt categories.
    This file is essentially the “brain” of each Company.
        </li>
      <li>
        <strong><code>context/</code></strong>:
        Markdown files with static knowledge – business rules, procedures, FAQs, company overview.
        These become part of the system context for that assistant.
      </li>
      <li>
        <strong><code>schema/</code></strong>:
        YAML descriptions of each table or entity in your business database.
        They document column names, types, relationships, and natural-language explanations,
        helping the LLM generate high-quality SQL.
      </li>
      <li>
        <strong><code>prompts/</code></strong>:
        Jinja2 prompt templates for predefined complex questions, such as sales analysis,
        supplier reports, or risk summaries. The UI can expose these as one-click prompts.
      </li>
      <li>
        <strong><code>your_company.py</code></strong>:
        A Python class that extends a base Company class and can register
        custom tools or company-specific logic.
      </li>
    </ul>

    <p>
      The result is a powerful multi-tenant pattern:
      the core IAToolkit framework is shared, but each Company folder
      encapsulates a complete AI assistant tailored to a specific domain or client.
      Adding a new client becomes a matter of copying a template Company,
      editing some YAML files, and implementing whatever custom tools are needed.
    </p>

        <h3>3.3 <code>company.yaml</code>: Declarative Control Over Each Assistant</h3>

    <p>
      At the heart of each Company lies a single file: <code>company.yaml</code>.
      This is the declarative blueprint for that assistant. Among other things, it defines:
    </p>

    <ul>
      <li><strong>Identity</strong>: company ID, display name, default locale.</li>
      <li><strong>LLM configuration</strong>: which model to use and which environment variable stores its API key.</li>
        <li><strong>Data sources</strong>: SQL databases, connection strings (via env vars), table inclusion/exclusion rules, and natural-language descriptions.</li>
      <li><strong>Knowledge base options</strong>: document connectors (local, S3) and logical document sources for RAG.</li>
      <li><strong>Tools</strong>: the functions the LLM can call, with OpenAPI-style schemas for parameters.</li>
      <li><strong>Prompts &amp; categories</strong>: pre-configured prompts with descriptions and custom fields for the UI.</li>
      <li><strong>Branding</strong>: header colors, primary and secondary brand colors, and visual tweaks.</li>
        <li><strong>Embedding provider</strong>: model and key for semantic search.</li>

    </ul>

    <p>
      Instead of hard-coding any of this in Python, you configure it declaratively.
      That makes it much easier to spin up a new tenant, tweak a single client’s branding,
      or point a new assistant to a different database without modifying core code.
    </p>
              <h3>3.4 The Dispatcher: Connecting the LLM to Your Custom Python Logic</h3>

<p>
  While <code>company.yaml</code> defines <em>what</em> tools exist, the <strong>Dispatcher</strong> is the
  component that makes them actually work. It acts as a bridge between the LLM and each
  Company’s custom Python code.
</p>

<p>
  When the LLM decides to call a tool (for example: <code>get_customer_summary</code> or
  <code>generate_invoice</code>), the Dispatcher:
</p>

<ul>
  <li>Detects which Company the user belongs to</li>
  <li>Loads that Company’s Python class (e.g. <code>AcmeCompany</code>)</li>
  <li>Maps the LLM tool call to a Python method inside that Company</li>
  <li>Validates inputs, executes the method, and returns structured output to the LLM</li>
</ul>

<p>
  This design gives each Company full power to implement its own logic:
</p>

<blockquote>
  “Every Company gets its own business logic, its own functions, its own workflow automation —
  all without touching the core framework.”
</blockquote>

<p>
  For agencies, this means each client can have custom behaviors.
  For enterprises, each business unit can integrate with its own APIs and processes.
  For developers, it creates a clean and safe extension point that avoids code duplication.
</p>


    <hr />


    <!-- Chapter 4 -->
    <h2>4. From Idea to Production: A Mini Implementation Project</h2>

<p>
  A realistic IAToolkit implementation for a single business unit or client usually unfolds as
  a structured mini-project. Based on real deployments, a full cycle of analysis, setup,
  configuration, tooling, testing, and rollout takes approximately <strong>three months</strong>.
</p>

<h3>4.1 What You Need</h3>

<ul>
  <li>One Python developer familiar with SQL and APIs</li>
  <li>One domain expert who understands key business questions</li>
  <li>Access to a SQL database (ideally a read-only replica)</li>
  <li>A small set of internal documents for RAG</li>
  <li>A cloud environment for hosting (Python + PostgreSQL + Redis)</li>
</ul>

<h3>4.2 Project Phases</h3>

<p>The mini-project advances through five clear phases:</p>

<ul>
  <li>
    <strong>Phase 1 — Setup, Exploration, and Company Creation </strong><br/>
    Running IAToolkit locally, understanding the sample Company. Defining the Company’s identity, configuring <code>company.yaml</code>,
    connecting SQL databases, applying basic branding, and enabling authentication.
  </li>

  <li>
    <strong>Phase 2 — Modeling Knowledge and Data</strong><br/>
    Creating schema YAML files, writing context documents, aligning terminology with
    domain experts, and iterating until SQL and RAG answers become consistent and useful.
  </li>

  <li>
    <strong>Phase 3 — Tools, Workflows, and Documents</strong><br/>
    Adding Python tools the LLM can call, integrating APIs, loading documents into the
    vector store, and building structured prompts for recurrent analyses.
  </li>

  <li>
    <strong>Phase 4 — Pilot and Production Rollout</strong><br/>
    Deploying a pilot version to real users, collecting feedback, refining prompts and
    schemas, and finally deploying the production assistant with monitoring and logs.
  </li>
</ul>

<hr />


<h2>Closing Thoughts</h2>

<p>
  If your goal is to move beyond demos and into robust, secure, extensible systems,
  IAToolkit gives you a strong and transparent foundation. Its multi-tenant design,
  declarative configuration, and extensible Python tools make it ideal for organizations
  taking their first serious steps into AI.
</p>

<p>
  Because IAToolkit is <strong>fully open source</strong>, anyone can explore it, test it,
  adapt it, and deploy it freely. The easiest way to understand its power is to use it in a
  <strong>focused mini-project</strong>: a three-month initiative where your team gains hands-on experience
  with prompts, SQL modeling, document integration, and custom tools in a real, high-learning environment.
</p>

<p>
  Whether you're a CTO evaluating platforms or a developer curious about enterprise AI patterns,
  IAToolkit is an accessible, transparent, and practical place to start.
  You're invited to download it, clone the repo, and experiment with your own data.
</p>

{% include '_static_footer.html' %}
    </div>
</div>
{% endblock %}