DEV Community: Dmitry Lukashov

Choose the reporting timezone before grouping campaign events

Dmitry Lukashov — Thu, 29 Oct 2026 06:32:51 +0000

An AI assistant can group an event export by the first ten characters of its timestamp and produce a neat daily table. That table can still use the wrong day boundary.

This small exercise makes the boundary explicit before asking an assistant to summarize a campaign. It counts four fictional event rows, not unique users, qualified leads, or purchases. Nothing connects to an ad account or changes a campaign.

Four timestamps, three possible tables

Save this UTF-8 fixture as events.csv:

event,occurred_at
E01,2026-10-28T20:59:00Z
E02,2026-10-28T21:00:00Z
E03,2026-10-29T00:15:00+03:00
E04,2026-10-29T22:15:00+03:00

The first two timestamps use UTC (Z). The other two include +03:00. For this exercise, the reporting timezone is Europe/Moscow. Choose the timezone specified by your real report; this example does not imply every campaign uses Moscow time.

E01 is one minute before midnight in that timezone. E02 is exactly midnight, so it belongs to the next reporting day. E03 and E04 belong to that next day too.

These are the results of three different grouping rules:

Grouping rule	October 28	October 29
First ten characters of each supplied string	2	2
Convert every timestamp to UTC, then take its date	3	1
Convert every timestamp to Europe/Moscow, then take its date	1	3

All three tables count four rows. A total-count check would not reveal the different day boundaries. For the stated reporting contract, the last row is the expected result.

Convert before taking the date

The following complete script uses Python's standard library. Save it as group_events.py beside events.csv:

import csv
import json
from collections import Counter
from datetime import datetime
from pathlib import Path
from zoneinfo import ZoneInfo


REPORT_TZ_NAME = "Europe/Moscow"
REPORT_TZ = ZoneInfo(REPORT_TZ_NAME)


def group_events(rows):
    counts = Counter()
    assignments = []
    for row in rows:
        raw = row["occurred_at"]
        stamp = datetime.fromisoformat(raw.replace("Z", "+00:00"))
        if stamp.utcoffset() is None:
            raise ValueError(row["event"] + ": explicit UTC offset required")
        report_day = stamp.astimezone(REPORT_TZ).date().isoformat()
        counts[report_day] += 1
        assignments.append({"event": row["event"], "report_date": report_day})
    return {
        "report_timezone": REPORT_TZ_NAME,
        "counts": dict(sorted(counts.items())),
        "assignments": assignments,
    }


if __name__ == "__main__":
    try:
        with Path(__file__).with_name("events.csv").open(
            encoding="utf-8", newline=""
        ) as stream:
            report = group_events(list(csv.DictReader(stream)))
    except (ValueError, KeyError) as error:
        print(json.dumps({"error": str(error)}))
        raise SystemExit(2)
    print(json.dumps(report, indent=2))

Run it with:

python3 group_events.py

The output includes the timezone, the counts, and an assignment for each input row:

{
  "report_timezone": "Europe/Moscow",
  "counts": {
    "2026-10-28": 1,
    "2026-10-29": 3
  },
  "assignments": [
    {"event": "E01", "report_date": "2026-10-28"},
    {"event": "E02", "report_date": "2026-10-29"},
    {"event": "E03", "report_date": "2026-10-29"},
    {"event": "E04", "report_date": "2026-10-29"}
  ]
}

The output above uses more compact spacing for the assignment objects; the JSON values are the same as the script's output. Keeping those assignments makes it possible to inspect which event crossed a date boundary instead of comparing totals alone.

The fixture and script were executed locally on Python 3.9.6. The four assignments and the three grouping alternatives in the table were checked. No external language model response was measured in this run; the script provides a reference result for checking one.

zoneinfo requires Python 3.9 or later and available IANA timezone data. It uses the system database or the tzdata package, as described in Python's official zoneinfo documentation. The local run had the required data. A machine without it may raise ZoneInfoNotFoundError; silently replacing the chosen zone with the computer's local timezone would change the contract.

Reject an unspecified offset

Change E03 to this value:

E03,2026-10-29T00:15:00

The timestamp now has no UTC offset. The script stops with exit code 2 and prints:

{"error": "E03: explicit UTC offset required"}

It does not print partial daily counts. Guessing that the value means UTC, Moscow time, or the operator's laptop time would produce a result without a stated source rule. Python distinguishes these naive timestamps from aware timestamps in its datetime documentation.

If the source system documents an offset-free value as belonging to a particular timezone, handle that as a separate input contract. This short example deliberately refuses to infer it.

Check that a different representation preserves the instant

Restore the original fixture. Then replace E02's timestamp with 2026-10-29T00:00:00+03:00.

That is the same instant as 2026-10-28T21:00:00Z. The script must return the same counts and assignments. A program that groups by the string's date would move the row simply because its representation changed.

Both this mutation and the missing-offset mutation were executed locally. One checks an invariant; the other checks a refusal condition.

Use the reference when reviewing an AI summary

Give an assistant the original CSV and a specific instruction:

Count event rows by calendar date in Europe/Moscow.
Require an explicit UTC offset or Z on every timestamp.
Convert each instant to Europe/Moscow before extracting its date.
Do not group by a substring or by the timestamp's original timezone.
If any timestamp has no offset or cannot be parsed, report the error;
do not return partial daily counts and do not guess a timezone.
Return the reporting timezone, daily counts, and each event's assigned date.
Do not infer unique users, leads, purchases, or campaign performance.

Compare the individual assignments as well as the counts. Then repeat the two mutations. A well-written explanation should not conceal a changed grouping rule or an invented offset.

This is a narrowly scoped fixture, not a production analytics pipeline. It assumes the displayed CSV schema and already deduplicated event rows. It does not check export completeness, attribution windows, delayed events, refunds, event definitions, or duplicate identifiers. Those require their own acceptance cases before a daily table can support a business conclusion.

Prepared with an AI agent. The displayed fixture, code, reference values, and two input mutations were checked locally. All event data is synthetic.

A matching name should not choose a CRM recipient

Dmitry Lukashov — Tue, 27 Oct 2026 12:53:03 +0000

Two CRM contacts have the same name. An incoming request mentions that name, and an AI assistant picks the first matching contact. The next draft could include details from the wrong customer record.

A small matching report makes this mistake easier to catch before drafting a reply. This exercise uses four invented contacts and four invented requests. It runs locally, makes no CRM or email API calls, and sends nothing.

Define the matching contract

For this exercise, compare email strings exactly. Do not repair an address, substitute a domain, or use a name to find a record when the email is missing.

The rules are:

A missing email requires manual review.
An email absent from the contacts requires manual review.
An email found in multiple contacts requires manual review. Return every matching contact ID; do not narrow the list by name.
For exactly one email match, compare the names literally. A mismatch requires manual review.
One matching email and name produces a candidate, not an instruction to send.

This deliberately conservative contract leaves aliases, name variations, address changes, and address ownership unresolved. A matching row does not establish identity or authority to disclose customer information.

Create the two fixtures

Save this UTF-8 text as contacts.csv:

contact,name,email
C01,Алексей Смирнов,alex@northern.example
C02,Алексей Смирнов,alex@southern.example
C03,Марина Орлова,office@team.example
C04,Денис Белов,office@team.example

C01 and C02 are two different Alexey Smirnov records. C03 and C04 share an email address. All names and addresses are fictional.

Save the requests as requests.csv in the same directory:

request,name,email
Q01,Алексей Смирнов,alex@southern.example
Q02,Алексей Смирнов,
Q03,Марина Орлова,office@team.example
Q04,Алексей Смирнов,alex@unknown.example

Q02 has no address. Q04 has an address that does not appear in the contacts. Matching either request by name would silently add a rule we did not approve.

Run a deterministic reference check

Save the following complete script as check_matches.py next to the two CSV files. It uses only Python's standard library:

import csv
import json
from pathlib import Path


def read_rows(path):
    with path.open(encoding="utf-8", newline="") as stream:
        return list(csv.DictReader(stream))


def match_requests(contacts, requests):
    result = []
    for request in requests:
        email = request["email"]
        matches = [row for row in contacts if row["email"] == email] if email else []
        if not email:
            reason = "missing_email"
        elif not matches:
            reason = "no_exact_match"
        elif len(matches) != 1:
            reason = "ambiguous_email"
        elif matches[0]["name"] != request["name"]:
            reason = "name_conflict"
        else:
            reason = "candidate"
        result.append({
            "request": request["request"],
            "status": reason,
            "contacts": [row["contact"] for row in matches],
        })
    return result


if __name__ == "__main__":
    folder = Path(__file__).resolve().parent
    result = match_requests(read_rows(folder / "contacts.csv"), read_rows(folder / "requests.csv"))
    print(json.dumps(result, ensure_ascii=False, indent=2))

Run it with:

python3 check_matches.py

The output should contain these four results:

Request	Status	Contacts
Q01	`candidate`	C02
Q02	`missing_email`	none
Q03	`ambiguous_email`	C03, C04
Q04	`no_exact_match`	none

That is one candidate and three requests requiring manual review. Q03's name matches C03, but the shared email still produces two IDs under the stated contract.

The script was executed locally on Python 3.9.6. All four results were checked. This is a reference calculation over the supplied fixtures; an external language model's response was not measured in this run.

Give the same contract to an AI assistant

Paste this prompt followed by both complete CSV fixtures:

Match requests.csv to contacts.csv using only the two supplied tables.

Find contacts by exact email equality. An empty email is not a match.
Do not use a name as a lookup key.

Return missing_email when the request email is empty.
Return no_exact_match when the email is absent from contacts.
Return ambiguous_email when two or more contacts have that email;
include every matching contact ID and do not filter them by name.
For exactly one matching email, compare the names literally.
Return name_conflict when the names differ; otherwise return candidate.

Return one row per request: request, status, contacts, explanation.
In the explanation, cite the email used or its absence.
Do not draft messages, send anything, or modify records.

Compare each returned row with the reference result. Check the IDs as well as the status. A plausible explanation does not compensate for an omitted contact or an extra match.

Change an input before trusting the result

Two small mutations expose different mistakes:

Change Q01's name to Марина Орлова while keeping its email. The result must become name_conflict, with C02 shown for review.
Restore the original fixtures, then add C05 with the same name and email as C02. Q01 must become ambiguous_email, listing C02 and C05. It must not keep selecting the first contact.

Both mutations were also executed and checked locally. They test contradiction handling and ambiguity handling separately.

This short script assumes the displayed, well-formed CSV schema. It is not a production CRM connector or a complete validator for arbitrary files. Before adapting it, define how your system handles incomplete exports, shared addresses, renamed contacts, and duplicate identifiers. Add examples for those cases to the acceptance set.

Keep recipient matching separate from message preparation and delivery. The report tells a reviewer which rows need attention; it does not decide what customer information may be sent.

Python documents the CSV reader and JSON output functions in the official csv and json references.

Prepared with an AI agent. The code and fixtures above were executed and checked. All data is synthetic; this is not a customer deployment or a measured model benchmark.

A malformed suppression CSV should stop an AI-assisted email preflight

Dmitry Lukashov — Sun, 25 Oct 2026 16:55:40 +0000

An exclusion list is an input to a decision. If the list cannot be read reliably, returning an empty list changes the decision: a recipient who should have been excluded may appear eligible.

Here is a small reproducible check of that boundary in my open-source UniSender Campaign Kit. The program prepares an offline plan; it does not send email. I ran the two cases below on version 0.1.0. Every address and permission identifier is synthetic.

Two contacts and one exclusion

Download and extract the existing 0.1.0 release. It needs Python 3.9+ and uses the standard library. Keep the supplied examples/campaign.example.json unchanged. That file is an example draft, not a provider configuration.

Inside the extracted directory, create a fixture directory with three files.

fixture/contacts.csv:

email,consent,consent_at,consent_evidence,unsubscribed
ok@people.example.invalid,true,2026-10-01T12:00:00Z,synthetic-permission-a,false
excluded@people.example.invalid,true,2026-10-01T12:00:00Z,synthetic-permission-b,false

fixture/suppression-valid.csv:

email,reason
excluded@people.example.invalid,synthetic-opt-out

fixture/suppression-invalid.csv:

email,reason
not-an-address,synthetic-invalid-row

Both contact rows declare consent=true. The second address is also in the valid exclusion list. That exclusion must remain effective.

Establish the positive case

The following command uses a POSIX shell. The explicit time makes the result repeatable.

python3 -B lookatshow_mail_plan.py plan \
  --campaign examples/campaign.example.json \
  --contacts fixture/contacts.csv \
  --suppression fixture/suppression-valid.csv \
  --at 2026-10-25T12:00:00Z

The process exited with code 0. The relevant result fields were:

{
  "counts": {
    "contact_rows": 2,
    "eligible_under_supplied_rules": 1,
    "excluded_rows": 1
  },
  "reason_counts": {"suppressed": 1},
  "rows": [
    {"ordinal": 1, "reasons": [], "status": "eligible_under_supplied_rules"},
    {"ordinal": 2, "reasons": ["suppressed"], "status": "excluded"}
  ],
  "sending_performed": false
}

This is an excerpt, not the complete response envelope. The output identifies source row numbers without echoing the addresses or permission evidence.

Change only the suppression input

Run the same command with --suppression fixture/suppression-invalid.csv. Leave the campaign, contacts and evaluation time unchanged.

The process exited with code 2. Its response had ok=false and this error:

{
  "code": "SUPPRESSION_INVALID",
  "input": "suppression",
  "message": "Invalid suppression row makes exclusions uncertain.",
  "ordinal": 1
}

There was no result object and no eligibility count. The malformed row did not become a harmless warning followed by a plan.

Give the wrapper the same stopping rule

An AI agent wrapping this CLI should inspect the process status and response envelope before explaining the plan. For this input, the next action is to report the suppression-file error and request a corrected source file.

Silently discarding the invalid row, replacing the file with an empty one, or continuing from a previous successful plan would defeat the check. Keep the failing input and its outcome together so another person can reproduce the stop.

The successful case also has a boundary: eligible_under_supplied_rules means the supplied fields passed local rules. The tool does not verify that the permission evidence is genuine, establish legal permission, contact UniSender, or prove delivery. Those checks remain separate; the two true fields in this fixture are deliberately invented claims.

For my Russian-language notes on checking AI-assisted marketing workflows, see my Telegram channel.

Prepared with an AI agent. The fixture, exit codes and output excerpts above were executed and checked; this is a synthetic exercise, not a customer campaign.

Check source spans in AI-extracted task lists

Dmitry Lukashov — Sun, 18 Oct 2026 10:08:02 +0000

An extracted task can cite a real line ID while quoting words that are not in that line. A small source-span check makes that error visible before you use the row as evidence.

This exercise has six fictional lines. Maya promises to send an agenda, Noah commits to checking two totals, and Friday remains a proposal. All candidate outputs below are deliberate fixtures, not captured responses from a model.

Ask your extractor for a narrow output:

Extract explicit personal commitments. Return a JSON array with line_id, start, end and quote. Quote the source verbatim. Use zero-based Python string indexes into the line text, including the speaker prefix; end is exclusive. Keep proposals and unassigned requests out of the commitment list.

The runnable source and README contain the same example. Save the code below as source_span_gate.py; it uses only Python's standard library.

import json

# Fictional source lines. Candidate outputs below are also synthetic.
SOURCES = {
    "L1": "Maya: I will send the agenda.",
    "L2": "Noah: Could we review it on Friday?",
    "L3": "Maya: Friday is still a proposal.",
    "L4": "Leo: Please check both totals.",
    "L5": "Noah: I will check both totals. No deadline yet.",
    "L6": "Maya: Nobody is assigned to send the final file.",
}
GOOD = """[
  {"line_id":"L1","start":6,"end":29,"quote":"I will send the agenda."},
  {"line_id":"L5","start":6,"end":31,"quote":"I will check both totals."}
]"""


def check(raw):
    rows = json.loads(raw)
    if not isinstance(rows, list):
        raise ValueError("expected an array")
    seen = set()
    for number, row in enumerate(rows, 1):
        if not isinstance(row, dict) or set(row) != {
            "line_id", "start", "end", "quote"
        }:
            raise ValueError(f"row {number}: unexpected fields")
        ref, start, end, quote = (
            row["line_id"], row["start"], row["end"], row["quote"]
        )
        if not isinstance(ref, str) or ref not in SOURCES:
            raise ValueError(f"row {number}: unknown source line")
        if (
            type(start) is not int or type(end) is not int
            or not 0 <= start < end <= len(SOURCES[ref])
        ):
            raise ValueError(f"row {number}: invalid span bounds")
        if not isinstance(quote, str) or SOURCES[ref][start:end] != quote:
            raise ValueError(f"row {number}: quote does not match source")
        span = (ref, start, end)
        if span in seen:
            raise ValueError(f"row {number}: duplicate span")
        seen.add(span)
    return len(rows)


if __name__ == "__main__":
    examples = {
        "good": GOOD,
        "changed_word": GOOD.replace("send the agenda", "approve the agenda"),
        "wrong_offset": GOOD.replace('"start":6', '"start":7', 1),
        "unknown_line": GOOD.replace('"L1"', '"L99"', 1),
    }
    for name, raw in examples.items():
        try:
            print(f"{name}: PASS ({check(raw)} spans)")
        except ValueError as error:
            print(f"{name}: FAIL ({error})")

Run:

python3 -B source_span_gate.py

The locally executed output was:

good: PASS (2 spans)
changed_word: FAIL (row 1: quote does not match source)
wrong_offset: FAIL (row 1: quote does not match source)
unknown_line: FAIL (row 1: unknown source line)

The good fixture selects two exact pieces of evidence:

Source	Expected interpretation	Agreed deadline
L1, indexes 6:29	Maya will send the agenda.	Unknown
L5, indexes 6:31	Noah will check both totals.	Unknown

The changed-word fixture replaces “send” with “approve” in the candidate quote. The source stays unchanged, so the check rejects it. The other two fixtures move an offset or invent a source ID. They are rejected even though the JSON is parseable.

The offsets refer to Python string positions, not UTF-8 byte positions. The JSON documentation describes parsing; the sequence documentation defines the slicing convention used here.

A passing row establishes only that its quote matches the selected source span. It does not establish that the quote supports a proposed interpretation, that the list is complete, or that the source itself is true. An extractor could omit Noah's commitment and still produce valid spans for Maya.

Keep a short manual review beside this check: L2 asks about Friday and L3 still calls it a proposal, so Friday is not an agreed deadline. L6 leaves the final file without a sender. Neither detail should turn into an assigned, dated task just because a nearby quote passes.

For a real integration, first decide how to handle those semantic and completeness checks. This teaching function is not a complete production-input or JSON-hardening layer. It connects to no model, CRM or network.

Disclosure: AI agents prepared this article and code. The source lines and outputs are synthetic; the exact code shown above was run locally. No model API was called.

Dmitry Lukashov (Дмитрий Лукашов) — founder of Lookatshow, instructor and expert in applied AI at the Russian School of Management. Public author reference.

Four offline checks before giving a marketing agent API access

Dmitry Lukashov — Fri, 16 Oct 2026 17:51:10 +0000

A marketing agent can produce valid JSON and still make the wrong decision. It can average ratios instead of totals, compare packages with different scope, interpret an incomplete CRM response as absence, or turn a local email check into permission to send.

Here are four small offline exercises I use to make those errors visible before connecting an agent to a live account. Each has synthetic input and a result you can reproduce with Python 3.9+ and the standard library. There is no paid-core dependency or signup.

These are four independent tools, not an integrated marketing pipeline or a benchmark of any particular model. I maintain the modules as part of Lookatshow. AI assistance was used to prepare this article; the commands below were run against the public artifacts on 16 October 2026.

1. Check the denominator before recommending an ad change

Direct report audit reads a normalized placement CSV or TSV. It does not connect to Yandex Direct.

Download and unpack the v0.1.0 ZIP, open its directory, then run:

python3 -B direct_report_audit.py --json audit examples/synthetic-placements.csv --max-cpa 1000

The fictional input contains five rows and four grouped placements. The result has 97 clicks, 6,000 RUB cost and 5 conversions. Total CPA is 1,200.00 RUB, calculated from total cost divided by total conversions. Two placements are manual-review candidates under these demonstration thresholds.

Give the agent a narrower task than "optimize this campaign":

Recalculate the totals from the fixture. Explain why total CPA is a ratio of sums. List the review candidates and their reasons. Explain which attribution, tracking and sample-size checks would be needed before a campaign change.

An attractive recommendation to exclude a placement is not a passing answer. The program has not established causal waste or a complete customer journey. Native export headers and cost units must also be normalized first; the CLI is not a universal parser for every advertising export.

2. Separate a price change from a package change

Competitor offer radar compares supplied local snapshots. It does not scrape websites or verify that an offer was really available.

Use the pinned source archive. This later source revision includes a console-encoding fix; the original v0.1.0 release ZIP predates it.

python3 -B competitor_offer_radar.py compare examples/before.json examples/after.json

In the synthetic strategy-session package, the price changes from 10,000 to 12,500 RUB: +25%. Delivery changes from four to six business days, and interview quantity changes from two to one. The output includes scope_changed_warning=true.

Ask the agent:

Show the arithmetic and identify the changed scope. Can this establish a 25% price increase for equivalent work? What does an offer absent from the later snapshot actually prove?

A useful answer preserves the warning. Missing from a supplied snapshot does not establish that a competitor discontinued the product. Different package content does not support a clean like-for-like price conclusion.

3. Keep incomplete CRM reads out of the absence queue

Bitrix read kit has a synthetic demonstration that needs no portal or credentials. Its separate live mode is read-only and limited to what the configured user can see.

Download the v0.1.0 ZIP, unpack it and run:

python3 -B bitrix_read_kit.py demo

There are five fictional open deals and three unique visible unfinished activities. One deal has a scheduled activity, one an overdue activity, one an undated activity, one a complete activity read with no visible unfinished item, and one an incomplete activity read.

Ask:

Which deal supports an absence claim, and which needs a coverage check? Keep overdue-but-present activities separate from missing ones. State the demo's analysis time.

Deal 101 has the complete empty read. Deal 105 has incomplete coverage: its absence status cannot be established. The fixed analysis time is 10 October 2026, 10:00 MSK. Rerunning the fixture today is not a fresh portal capture, and a CRM activity is not proof of an agreed customer next step.

4. Keep a local eligibility check separate from sending

UniSender campaign kit checks a draft, a supplied permission ledger and a suppression file locally. It has no UniSender API connection, contact import or send command.

Download the v0.1.0 ZIP, unpack it and run:

python3 -B lookatshow_mail_plan.py demo

The six invented rows produce one eligible-under-supplied-rules row and five excluded rows. The reasons are a duplicate address, suppression, expired supplied permission, an unsubscribe flag and no affirmative supplied permission. All addresses use example.invalid.

The JSON still reports:

{
  "consent_evidence_verified": false,
  "legal_permission_verified": false,
  "provider_acceptance_verified": false,
  "deliverability_verified": false,
  "sending_performed": false
}

Ask the agent to explain those false fields before proposing any next step. A successful command means the local calculation completed. It does not verify a person's actual consent, a provider's acceptance or delivery. The demonstration also uses a fixed evaluation time rather than today's date.

A compact acceptance prompt

After downloading and reading the four modules' READMEs, try this with your coding agent:

Run only the four bundled synthetic commands above. For each exercise, report the exact command, exit code, observed values, supported conclusion and one tempting unsupported conclusion. Compare observed values with the stated expectations and report mismatches. Do not connect accounts, fetch customer data, send messages, alter campaigns or upload files. Stop and explain any missing input. Do not present synthetic results as a client case.

The distinction to inspect is between a calculation, the evidence it actually received, and the action someone wants to take. Passing these examples does not establish readiness for a live account. Failing one gives you a specific behavior to fix first.

The open-tools catalog links the installation instructions, licenses and limitations. Each module is independently usable for free. There is no hidden telemetry in these offline exercises. If you pass real output to a cloud agent later, that provider's data policy still applies.

For a task-first guide in Russian, choose a module by business task.

If you try a fixture, which unsupported conclusion did your agent make? A command, environment and synthetic mismatch are useful in a comment or repository issue; please keep customer exports, addresses and credentials private.

Prepared by Dmitry Lukashov. If your team needs help adapting this kind of evidence check to its own workflow, discuss implementation. Scope and cost are agreed separately from the free tools.

An empty CRM response is not evidence of no follow-up

Dmitry Lukashov — Thu, 15 Oct 2026 08:40:00 +0000

Suppose your CRM agent returns this sentence:

Two deals have no follow-up. Ask their owners to fix them.

The JSON behind it contains two empty arrays. One belongs to a completed activity read. The other belongs to an incomplete read. The agent has turned a collection limit into an accusation.

You don't fix that with a more persuasive prompt. Keep the evidence needed to support the statement, and test the rule before asking a model to explain it.

Here's a small, reproducible example using Bitrix read kit, a free MIT-licensed Python CLI from my Lookatshow project. Every record below is synthetic. You need no CRM account, credentials or paid core.

Reproduce the mistake without connecting a CRM

Use Python 3.9 or later. The package uses the standard library:

git clone https://github.com/ilookatshow-gif/bitrix-read-kit.git
cd bitrix-read-kit
git checkout --detach e102c33d20ed5d74591092433e78fb9019e1cc0d
python3 -B bitrix_read_kit.py demo

Use python instead of python3 if that's your interpreter name. Pinning the commit makes the example repeatable even if the default branch changes.

The fixture contains five fictional deals and three unique unfinished activities. Look at these two rows in the output; this is an excerpt, not the full report:

[
  {
    "deal_id": 101,
    "activity_read_complete": true,
    "visible_open_activity_ids": [],
    "flags": ["no_visible_open_activity"]
  },
  {
    "deal_id": 105,
    "activity_read_complete": false,
    "visible_open_activity_ids": [],
    "flags": ["activity_coverage_incomplete"]
  }
]

The arrays match. The conclusions don't.

This tempting filter produces the wrong work queue:

missing = [
    row["deal_id"] for row in report["deals"]
    if not row["visible_open_activity_ids"]
]
# [101, 105]

A narrower predicate preserves what the reader actually established:

missing = [
    row["deal_id"] for row in report["deals"]
    if row["activity_read_complete"]
    and not row["visible_open_activity_ids"]
]
unknown = [
    row["deal_id"] for row in report["deals"]
    if not row["activity_read_complete"]
]
# missing: [101]; unknown: [105]

Even missing needs a careful label: no visible unfinished CRM activity, not “no customer agreement.” A promise could live in a conversation or another system. The useful next action is to check the deal card and correspondence, not reprimand an employee.

Make coverage part of the data contract

Bitrix24 documents that crm.activity.list respects the current user's permissions, paginates results, and returns next when another page exists. A successful HTTP response doesn't establish that your integration collected the whole selection, much less every record in the company.

This module keeps coverage per deal. It also reports the collection window and refuses to claim an atomic portal snapshot:

{
  "scope": "records_visible_to_webhook_user",
  "selected_deal_pages_complete": true,
  "all_selected_activity_pages_complete": false,
  "snapshot_is_atomic": false,
  "portal_wide_completeness_proven": false
}

That object is the fixture's actual coverage output. true for deal pages and false for activity pages aren't contradictory: the selection of deals finished, but one deal's activity read didn't.

Don't discard an entire partial report either. An incomplete read that contains an overdue activity still proves that particular activity was visible. It doesn't prove there were no others. In a separate regression, adding synthetic unfinished activity 205 to deal 105 produces both activity_coverage_incomplete and overdue.

Positive evidence survives incomplete coverage. An absence claim doesn't.

A later clock is not a newer snapshot

Run the same saved input at two analysis times:

python3 -B bitrix_read_kit.py audit \
  --input examples/synthetic-snapshot.json \
  --as-of 2026-10-10T10:00:00+03:00

python3 -B bitrix_read_kit.py audit \
  --input examples/synthetic-snapshot.json \
  --as-of 2026-10-13T10:00:00+03:00

Field	First analysis	Later analysis
Unique visible unfinished activities	3	3
Deals with a scheduled activity	1	0
Deals with an overdue activity	1	2
Deals with incomplete activity reads	1	1

Activity 201 on deal 102 has a deadline of 10 October at 12:00 MSK. The first analysis happens before it; the second happens after it. Nothing entered or left the input file.

Both reports retain captured_at: 2026-10-10T06:00:00Z. The later report doesn't tell you whether someone completed the activity after capture. It answers “how does this saved evidence classify at this time?”, not “what is happening in the portal now?”

Keep that difference in the UI. Show capture time beside analysis time. Before a consequential action, obtain an authorized fresh read rather than merely changing --as-of.

There is another date trap: Bitrix24's official activity example uses 9999-12-31 for an activity with no deadline. The kit classifies the fixture's activity 203 as undated. It doesn't celebrate an appointment scheduled thousands of years ahead.

Give the model a bounded job

Once the checks run, use the model to explain evidence, not manufacture certainty. This prompt works with the included fixture:

Run the two offline audits at the exact times in this article. Don't connect a portal or change the CRM. For each deal, give its ID, visible unfinished activity IDs, coverage, supported conclusion and manual verification step. Keep incomplete reads separate from complete empty selections. Explain why activity 201 changes classification without changing the unfinished count. Distinguish capture time from analysis time. Don't infer lost sales, employee failure or an agreed customer next step.

Make the same boundary executable in your integration tests:

for row in report["deals"]:
    flags = set(row["flags"])
    assert not {
        "no_visible_open_activity",
        "activity_coverage_incomplete",
    } <= flags

That assertion catches one specific contradiction. It doesn't certify the underlying portal data. Keep provider errors, malformed records and permission checks out of the “empty success” path too.

For this article, autonomous AI agents reran the pinned source's 95 tests and its clean-install smoke test on macOS arm64 with Python 3.9.6. They passed. No real customer portal supplied these results. Real capture files still contain linkable internal CRM IDs even without names or phone numbers; don't publish them or hand them to an unrelated AI service.

Use the free module, then decide what needs integration

Start with the pinned source and fixture. You can keep the offline checks independent of any agent host. The CLI isn't an MCP server; adding a model doesn't change its evidence limits.

I'm Dmitry Lukashov, creator of Lookatshow, a marketing-management system for AI agents. If your team needs a CRM review workflow with explicit permissions, freshness rules and a separate read-before-write check, discuss that implementation with me. The module remains free and doesn't require that service. I share practical notes at @lookatsoul.

Disclosure: this is my project. Autonomous AI agents prepared the article and checked its code and outputs. The linked source, fixture and commands make the technical claims independently testable.