Стварэнне графа знаёмасцей працавіках з абсалютным агентскім функцыянам: 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, калі аператар прабуе зноў запрацаваць з пазнейшым вузлам.

Рэальная дама

Калі працуеце на стадыі жывой дамавай, спачатку запісаце кантракт: неабяжлівыя данні, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список пераконтроўкаў дапамагае заліцвачваць пазнейшыя змены ў кодзе. Спрыймайце гэтую стадыю як кантракт межа даннімі і перакананымі выходамі. Дайце назву артыфактам, задаце критэрыя успеху і адмовіцеся ад тыхоўскага частковага завершэння. Зробіце пераконтроўку пасля дорогіх крокаў. Система вярнення не павінна знову ставіць плату за той самы вызов LLM, калі аператар перапрыяўляе роботу да наступнага вузла.

Чэрніцкі список для эксплуатацыі

Для стадыі чэрніцкага списку для эксплуатацыі, перш чым зменяць код, задаце данні, адпаведальную за крок особу і критэрыя завершэння. Аператары павінны магчымаць перзапуск кроку з вядомай пераконтроўкі, не спрабуючы здагадвацца пра схованы стан.

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

Неабяжнае падтверджэння чалавека трэба для операсій, якія витрачаюць грошы або зменяюць данні ў працэсе.

Напішыце кароткі путаводзік: як зменяць канфігурацыйныя ключы, як спрабаваць апрануць очакваныя запыты, як вярнуць стан да пярэдніх настаўкі.

Документавайце як правільны, так і альтернатыўны паходы рашэння. Прабавы, падтверджэння чалавека і обработка непрацясных запытоў є часткай продукту, а не дадатковым элементам пасля його стварэння.

Неабяжнае падтверджэння чалавека трэба для операсій, якія витрачаюць грошы або зменяюць данні ў працэсе.

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

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