Створення повністю автономної графи знань співробітників: OrgGraph AI — з використанням

Наведені нижче примітки відтворюють практичний підхід до створення «Повністю автономної графіки знань співробітників: OrgGraph AI — з використанням LangGraph та Neo4j». Основна увага приділяється контрактам, перевіркам та місцям для вставки коду, а не мотиваційному формулюванню. Під час роботи на етапі огляду спочатку запишіть контракт: необхідні вхідні дані, сигнал успіху та те, що відбувається у разі часткової невдачі. Цей перелік допоможе зберегти чесність пізніших змін у коді. Документуйте як успішний, так і відновлювальний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки.

Вхідні дані:

Етап вхідних даних працює найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Віддавайте перевагу невеликим, тестованим одиницям перед складними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій. Зберігайте стан графа у вигляді плоских структур із чіткими типами даних. Вкладені структури приховують інформацію про те, який вузол заповнив яке поле, що ускладнює продовження роботи після перерв.

Вихідні дані:

Етап вихідних даних працює найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Розглядайте цей етап як контракт між вхідними даними та перевіреними вихідними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового завершення роботи. Зберігайте стан графа у вигляді плоских структур із чіткими типами даних. Вкладені структури приховують інформацію про те, який вузол заповнив яке поле, що ускладнює продовження роботи після перерв.

Справжня проблема: відносини, а не записи

Етап «Справжня проблема: відносини» функціонує найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Видимість витрат заздалегідь запобігає несподіваним рахункам, коли процес переходить від демо-версії до спільних середовищ. Зберігайте стан графа у випрямленому та типованому форматі. Вкладені блоки приховують інформацію про те, який вузол заповнив яке поле, і ускладнюють відновлення після перерв. Етап «Справжня проблема: відносини» функціонує найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Документуйте як успішний, так і відновлювальний шляхи роботи разом. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.

Чому «Zero-Hardcoding» змінює все

На етапі «Чому Zero-Hardcoding змінює все» необхідно визначити вхідні дані, відповідальну особу та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Краще використовувати невеликі, перевірювані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру процесу. Встановлюйте людське схвалення для операцій, які призводять до витрат грошей чи змінюють дані у продакшені. Підключення на етапі компіляції не є гарантією повноти бізнес-функціоналу.

Огляд архітектури — OrgGraph AI

Для етапу OrgGraph AI у загальному огляді архітектури необхідно визначити вхідні дані, відповідальну особу за кожен крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового завершення. Вимагайте людського схвалення для тих елементів, які спричиняють витрати чи змінюють дані у продакшені. Підключення під час компіляції не є гарантією повності виконання завдань у бізнес-сенсі.

Етап 1: Аналізатор метаданих

На етапі „Метадані“ першої фази необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість знову виконати крок з відомої точки контролю, не намагаючись вгадати прихований стан. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам під час переходу з демо-середовища у спільні. Встановлюйте людське схвалення для кроків, які вимагають фінансових витрат чи змінюють дані у продакшені. Підключення під час компіляції не є гарантією повності функціоналу продукту. На етапі „Метадані“ першої фази необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість знову виконати крок з відомої точки контролю, не намагаючись вгадати прихований стан. Документуйте як оптимальний, так і альтернативний шлях виконання. Повторні спроби, людське схвалення та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.

# Simplified FK detection logic from profiler.py
overlap = col_values & ref_values
if len(overlap) / len(col_values) >= 0.8:
    fk_candidates.append({
        "source_table": tname,
        "source_column": col,
        "target_table": ref_table,
        "target_column": ref_col,
        "match_pct": round(len(overlap) / len(col_values) * 100, 1),
    })

Етап 2: Відкриття схеми LLM за допомогою Pydantic

Під час роботи над етапом 2 необхідно спочатку скласти опис вимог: обов’язкові параметри вхідних даних, сигнал про успіх та наслідки часткової невдачі. Такий перелік допомагає зберігати чесність у подальших змінах коду. Краще використовувати невеликі, перевірювані одиниці коду замість величезних скриптів. Якщо якийсь крок зазнає невдачі, причина має вказувати на конкретну функцію, а не на складну послідовність операцій. Зберігайте у кеші стабільні інструкції системи та схеми інструментів. Повторне надсилання однакових даних є поширеною причиною зайвих витрат ресурсів.

# The LLM is coerced to return this exact structure
class GraphMappingModel(BaseModel):
    nodes: List[NodeMapping]           # What becomes a Node?
    relationships: List[RelationshipMapping]  # What becomes an Edge?
    notes: str                         # LLM's reasoning notes
class NodeMapping(BaseModel):
    label: str                   # e.g., "Employee"
    source_table: str            # e.g., "Employees"
    primary_key_column: str      # e.g., "Employee_ID"
    properties: List[PropertyMapping]  # All columns to map
class RelationshipMapping(BaseModel):
    type: str                    # e.g., "HAS_SKILL"
    from_node_label: str         # e.g., "Employee"
    to_node_label: str           # e.g., "Skill"
    from_key_column: str         # FK column in source table
    to_key_column: str           # PK column of target node
    properties: List[PropertyMapping]  # Edge properties

Етап 3: Динамічне отримання даних за допомогою Cypher

Під час роботи над етапом Phase 3 Dynamic Cypher спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Призначте назви елементам, визначте критерії успіху та не допускайте безповідомного часткового виконання. Робіть контрольні пункти після дорогих кроків. Система повернення до виконання не повинна знову стягувати плату за той самий виклик LLM, коли оператор намагається виконати наступний етап.

# Dynamically generated Cypher from the mapping — zero hardcoding
UNWIND $rows AS row
MERGE (n:Employee {employee_id: row.employee_id})
SET n.full_name = row.full_name,
    n.designation = row.designation,
    n.date_of_joining = row.date_of_joining,
    n.annual_ctc_lpa = toFloat(row.annual_ctc_lpa)

Синтетичний набір даних

Під час роботи над етапом синтетичних даних спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Запишіть час виконання та витрати на токени або запити поруч із функціональними результатами. Відображення витрат заздалегідь запобігає несподіваним рахункам, коли процес переходить від демо-версії до спільних середовищ. Створюйте контрольні точки після дорогих кроків. Функція відновлення не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор перезапускає пізнішу ланку. Під час роботи над етапом синтетичних даних спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Одночасно задокументуйте оптимальний та резервний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.

Етап 4: Агентський чат GraphRAG

Етап 4 – стадія агентного підходу – найкраще функціонує, якщо його розглядати як вимірювану поверхню. Зафіксуйте один ідеальний приклад виконання, один випадок невдачі та примітку щодо скасування змін перед розширенням обсягу роботи. Віддавайте перевагу невеликим, тестованим одиницям перед складними скриптами. Якщо якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій. Розділяйте політику часткового оброблення даних та політику їх отримання. Зміна однієї з них не повинна змушувати переписувати іншу при зміні показників якості.

User Question
    ↓
┌─────────────┐
│   Planner   │ → Analyzes intent, extracts entities, maps to schema
└──────┬──────┘
       ↓
┌─────────────┐
│  CypherGen  │ → Generates Cypher query using schema + few-shot examples
└──────┬──────┘
       ↓
┌─────────────┐     ┌─── Error? ───→ Retry CypherGen (up to 2x)
│  Executor   │ ────┤
└──────┬──────┘     └─── Success ──→
       ↓
┌──────────────┐
│ Synthesizer  │ → Formats raw graph data into natural language
└──────────────┘

Рішення щодо проектування на рівні корпорацій

Етап прийняття рішень щодо дизайну корпоративного рівня найкраще функціонує, якщо його розглядати як вимірювану поверхню. Запишіть один ідеальний приклад роботи, один випадок збою та примітку щодо скасування змін перед розширенням обсягу роботи. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового виконання завдань. Зберігайте структуру графа простою та типованою. Вкладені елементи приховують інформацію про те, який вузол заповнив яке поле, що ускладнює продовження роботи після перерв.

Приватність даних

Етап забезпечення конфіденційності даних працює найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Візуалізація витрат заздалегідь запобігає несподіваним рахункам під час переходу від демо-версії до спільних середовищ. Зберігайте стан графа у простому та типованому вигляді. Вкладені блоки приховують інформацію про те, який вузол записав яке поле, і ускладнюють продовження роботи після перерв. Етап забезпечення конфіденційності даних працює найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу. Документуйте як успішний, так і відновлювальний шляхи роботи разом. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.

Агностичність до постачальника

На етапі агностичності щодо постачальника необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Краще використовувати невеликі, перевірювані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру процесу. Необхідно встановити людське схвалення для операцій, які призводять до витрат грошей чи змінюють дані у продакшені. Підключення на етапі компіляції не є гарантією повноти бізнес-функціоналу.

# .env: LLM_PROVIDER=gemini | openai | groq
llm = get_llm()  # Returns the configured ChatModel

Стійкість до неорганізованих даних

На етапі стійкості до неструктурованих даних необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового завершення. Вимагайте людського схвалення для операцій, які призводять до витрат грошей чи змінюють дані у продакшені. Підключення на етапі компіляції не є гарантією повності виконання завдань у бізнес-сенсі.

Результат: від завантаження до аналітики за кілька хвилин

На етапі „Результат завантаження“ необхідно визначити вхідні дані, власника кроку та критерії завершення ще до зміни коду. Оператори мають мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Візуалізація витрат заздалегідь запобігає несподіваним рахункам під час переходу з демо-середовища у спільні. Встановлюйте людське схвалення для кроків, які спричиняють витрати чи змінюють дані у продакшені. Підключення під час компіляції не є гарантією повності функціоналу продукту. На етапі „Результат завантаження“ необхідно визначити вхідні дані, власника кроку та критерії завершення ще до зміни коду. Оператори мають мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Документуйте як оптимальний, так і альтернативний шлях виконання. Повторні спроби, людське схвалення та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.

Більша картина

Під час роботи над етапом «Більша картина» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Віддавайте перевагу невеликим, тестованим одиницям перед об’ємними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність операцій. Робіть перевірки після дорогих кроків. Система повторного запуску не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор намагається знову виконати пізніший етап.

Жива демонстрація

Під час роботи на етапі живої демонстрації спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте безповідомного часткового виконання. Робіть контрольні пункти після дорогих кроків. Система повернення до виконання не повинна знову стягувати плату за один і той самий виклик ШІ, коли оператор перезапускає пізніший етап.

Чек-лист для експлуатації

На етапі чек-листу для експлуатації перед зміною коду необхідно визначити вхідні дані, власника кроку та критерії завершення. Оператори мають мати можливість перезапустити крок з відомого контрольного пункту, не здогадуючись про прихований стан.

Зберігайте конфігурацію поза кодом додатку. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код.

Встановіть людське схвалення для операцій, які спричиняють витрати грошей або змінюють дані в продакшені. Підключення на етапі компіляції не є гарантією повноти бізнес-функціоналу.

Напишіть короткий посібник: як оновлювати ключі, як спорожнювати чергу, як скасовувати останнє завантаження даних.

Документуйте як успішний, так і відновлювальний сценарії роботи. Повторні спроби, людське контролювання та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.

Встановіть людське схвалення для операцій, які спричиняють витрати грошей або змінюють дані в продакшені. Підключення на етапі компіляції не є гарантією повноти бізнес-функціоналу.

Перш ніж запускати стек у продакшн, заморозьте версії, створіть «золотий» запис для критичного шляху та підтвердьте кроки відкату. У спільних середовищах необхідні обмеження швидкості, перевірки прав власності та чіткий власник для зміни секретів. Віддавайте перевагу надійності перед креативними одноразовими демонстраціями.

Примітка до 470be70bb31c: не включайте ключі постачальника до репозиторію, встановіть ліміт токенів на сеанс та зберігайте записи поруч із фікстурами для оцінки, щоб подальша заміна моделей залишалася порівнянною.