Skip to main content

Placer

The Placer utility orchestrates the ingestion, mapping, and uploading of interaction data and metadata directly into your persistent storage layers. The tool supports several granular operations, allowing you to:

  • Define database table layouts and structural target schemas.
  • Execute programmable data and metadata ingestion workflows (supporting both INSERT and UPDATE operations).
  • Compute and inject automated vector embeddings for semantic search fields.
  • Leverage custom UUID primitives or traditional auto-generated keys for primary indexing.

Parameters​

The Placer utility accepts the following execution parameters:

  • filein – The target CTT file containing the enriched dataset to process.
  • action – The specific identifier of the loader block configuration to execute.
  • -e or --move – Automatically moves the original CTT file to a designated folder upon successful database ingestion (optional).
  • -v or --verbose – Sets the verbosity level, ranging from 0 (minimal) to 4 (maximum) (optional).
  • -t or --testupload – Simulates execution by generating and validation the SQL commands without committing changes to the live database (optional).

Central System Configurations (contacter.yaml)​

The main contacter.yaml file features two dedicated structural sections engineered to govern secure database access routing and automated vector embedding pipelines.

DATABASE Section​

This section establishes network locations, connection routing, and target schema boundaries alongside secure access credentials.

contacter.yaml
# Relational and database connection routing properties
DATABASE:
    host: "127.0.0.1"
    port: "54332"
    database: "postgres"
    user: "postgres"
    password: "$key:database_password"
    schema: "contacter"

EMBEDDINGS Section​

The EMBEDDINGS block establishes which foundational embedding models are triggered to vectorize text contents. Placer natively connects to Hugging Face Sentence-Transformers, Ollama, and OpenRouter model backends.

You can map specific target model dimensions (vector768, vector1024, vector1536) to respective processing modes and model weights. Network endpoints and API keys are isolated cleanly within specific provider sub-sections.

contacter.yaml
# Vector embedding model and provider configuration
# Available backends: Ollama, OpenRouter, and local Sentence-Transformers
# Target database columns will automatically map to vectorXXXX fields based on size limits
EMBEDDINGS:
    vector768:
        mode: "sentence-transformers"
        model: "all-MiniLM-L6-v2"
    vector1024:
        mode: "ollama"
        model: "mxbai-embed-large"
        # Alternative model considerations:
        # model: "paraphrase-multilingual-MiniLM-L12-v2"
        # model: "bge-large-en-v1.5"
    vector1536:
        mode: "openrouter"
        model: "sentence-transformers/all-minilm-l6-v2"
    ollama:
        base_url: "http://172.30.128.1:11434"
    openrouter:
        openai_api_key: "$key:openrouter_apikey"
        openai_api_base: "https://openrouter.ai"

Placer Ingestion Configuration Files​

All instructions handling database ingestion mappings and relational schema constraints are declared within your placer_*.yaml configuration files. At runtime, Placer dynamically reads and compiles all placer_*.yaml documents located within the current working folder. You can separate database abstractions and loading routines across unique workspace files as preferred.

An execution file isolates its logic into two main component boundaries:

  • db: Specifies the underlying database topology, outlining target tables and data types. This block does not function as a comprehensive DDL SQL script, but contains the critical structural metadata required to generate safe queries, insertions, and transactional updates.
  • load: Defines the granular pipeline instructions used to map and transfer variables from the CTT structure into the database.

Component Versioning & Environment Tags​

To prevent system regressions during updates, the database architecture supports multi-table versioning tracking. Every structured schema features a parent namespace identifier and a list of internal tables. Each table can track an independent structural version version tag if schemas change over time.

Similarly, the load configurations are protected by dedicated versioning layers, allowing you to run parallel production paths. Versions are declared using absolute numeric indexes (e.g., 1.1) or tracking environment labels (e.g., stable).

When linking loader engines, you specify the target template using a name:version syntax:

  • Declaring format01:1.1 locks execution to version 1.1 of the format01 component.
  • Declaring format01:stable instructs the runtime to dynamically query the highest-indexed version tagged as stable inside that namespace.

You retain complete architectural freedom to structure these revisions within centralized manifests or isolated files.

db Component​

The db component outlines the targeted data layout schema. You can declare multiple database instances under distinct tracking name properties. Every database definition encapsulates a collection of version-controlled table structures mapping explicit field names to their required technical storage column data types.

ainter_*.yaml
db:
    "contacter":
        "customer":
            "0.1:stable":
                id: "auto!primary"
                code: "str"
        "agent":
            "0.1:stable":
                id: "auto|primary"
                code: "str"
        "interaction":
            "0.1:stable":
                id: "uudi|primary"
                idcustomer: "int"
                idagent: "int"
                startdate: "date"
                enddate: "date"
                duration: "float"
                mainlanguage: "str"
                tags: "str"
                summary: "str"
                vsummary: "vector1024"
                metadata: "json"
        "speaker":
            "0.1:stable":
                id: "auto|primary"
                idinteraction: "uuid"
                name: "str"
                profile: "str"
                tags: "str"
                vvoiceprint: "vector512"
                metadata: "json"
        "issue":
            "0.1:stable":
                id: "auto|primary"
                idinteraction: "uuid"
                state: str
                "issue": "str"
                "vissue": "vector1024"
                metadata: "json"
        "phrase":
            "0.1:stable":
                id: "uudi|primary"
                idinteraction: "uuid"
                "tags": "str"
                "starttime": "float"
                "endtime": "float"
                "idspeaker": "uuid"
                rlvtag: "str"
                "text": "str"
                "vtext": "vector1024"
                metadata: "json"

In this deployment example, the target database configuration is named Contacter and orchestrates data mapping across five core entity tables: customer, agent, interaction, issue, and phrase.

For the infrastructure registry tables (customer and agent), you only need to define the explicit attributes your business rules require. The primary keys for these two dimensions are automatically derived directly from the application identifiers embedded inside the source CTT document. For the remaining operational tables, you must declare all target fields requiring runtime processing.

The compiler natively supports a specific subset of specialized column data types:

  • uuid – Cryptographic string identifier mapping.
  • auto – Standard database-managed auto-incrementing serial indices.
  • str – Text data arrays.
  • int – Integer numerical data.
  • float – Floating-point decimal data.
  • json – Complex nested metadata documents.
  • vector – High-dimensional embedding registers. The required array dimension boundary is passed as a numerical suffix (e.g., vector768 indicates a 768-dimensional space).

The Placer ingestion parser automatically manages format serialization, converting complex data structures into valid json and vector database types during the upload phase.

Load Component​

The load component maps the explicit structural mutations and transactional uploads to be executed across your database layers.

The configuration profile below instantiates a loader directive named callupload. The load.db subsection binds execution parameters to a designated database target and a list of version-controlled, aliased entity tables. The accompanying sections manage the actual data insertion workflows using the enhanced Cequation syntax extension for relational storage routing.

placer_*.yaml
load:
    # Loader Nane callupload
    "callupload":
        "0.1:stable":
            # Database to use: contacter
            "db":
                database: "contacter"
                table:
                    # Every table version we migh use
                    - customer:stable
                    - agent:stable
                    - interaction:stable
                    - speaker:stable
                    - issue:stable
                    - phrase:stable
            # Sub-componente call
            "call":
                # store in variable the id of customer table where code==$main.customer
                "idcustomer": "{$db.customer.id.[code='{$main.customer}']}"
                # Perform an insert/update in interaction table. idinteraction will take the primary key
                # [] insert (fails if already exists)
                # [+] insert only if not exists
                # [*] insert if not exists and update if exists
                # [=] updates if exists (fails if not exists)
                # [unsafe:{condition}] you can destroy your database easly. use with care
                "$db.interaction[*]:idinteraction":
                    # id is uuid
                    "id": "{$uuid}"
                    # idcustomer is the above variable idcustomer
                    "idcustomer": "{.idcustomer}"
                    # idagent read from the database, table agent
                    "idagent": "{$db.agent.id.[code='{$main.agent}']}"
                    "startdate": "{$main.date}"
                    "enddate": "{$main.date}"
                    "duration": "{$origin.durationorig}"
                    "mainlanguage": "{$call.mainlanguage}"
                    "tags": "{$call.tags::.:join:}"
                    "summary": "{$call.summary}"
                    "vsummary": "{$call.summary}"
                    # json of all detailed fields in call
                    "metadata": "{$call.(channel,volumeorig,gaincorr,volumecorr,nospeechprob,langprob,comratio,trust,wordnumber,language)}"
            "issue":
                "?call.issue.[myissue]":
                    "$db.issue[*]:idissue":
                        "id": "{$call.issue.[myissue].uuid}"
                        "idinteraction": "{.idinteraction}"
                        "issue": "{$call.issue.[myissue].issue}"
                        "vissue": "{$call.issue.[myissue].issue}"
            "speaker":
                "?speaker.[myspeaker]":
                    "$db.speaker[*]:idspeaker":
                        "id": "{$speaker.[myspeaker].uuid}"
                        "idinteraction": "{.idinteraction}"
                        "name": "{.myspeaker}"
                        "profile": "{$speaker.[myspeaker].profile}"
                        "tags": "{$speaker.[myspeaker].tags::.:join:}"
                        "vvoiceprint": "{$speaker.[myspeaker].voiceprint}"
                        "metadata": "{$speaker.[myspeaker].(turns,duration,volumeorig,volumecorr,nospeechprob,logprob,comratio,wordnumber,trust,language)}"
            "dialog":
                "?dialog.[mydial]":
                    "myspeaker": "{$dialog.[mydial].speaker}"
                    "$db.phrase[*]:idphrase":
                        "id": "{$dialog.[mydial].uuid}"
                        "idinteraction": "{.idinteraction}"
                        "starttime": "{$dialog.[mydial].start}"
                        "endtime": "{$dialog.[mydial].end}"
                        "idspeaker": "{$db.speaker.id.[idinteraction='{.idinteraction}'_and_name='{.myspeaker}']}" # you can not use spaces in the condition. Use underscore instead. you can use soeaker uuid directly. this method has educational purposes only in how to retrive primary keys from other tables.
                        "rlvtag": "{$dialog.[mydial].rlvtag}"
                        "text": "{$dialog.[mydial].text}"
                        "vtext": "{$dialog.[mydial].text}"
                        "tags": "{$dialog.[mydial].tags::.:join:}"
                        "metadata": "{$dialog.[mydial].(duration,channel,volumeorig,gaincorr,volumecorr,mainlanguage,nospeechprob,langprob,comratio,trust,wordnumber,language)}"