Skip to content

Conversational-Flow-Prototype

Graph-based KYC conversation flow prototype

View on GitHub

Information

Property Value
Language Jupyter Notebook
Stars 0
Forks 0
Watchers 0
Open Issues 0
License No License
Created 2026-01-29
Last Updated 2026-02-19
Last Push 2026-02-06
Contributors 1
Default Branch main
Visibility private

Notebooks

This repository contains 2 notebook(s):

Notebook Language Type

| kyc_conversation_flow_demo | PYTHON | jupyter |

| kyc_multi_agent_demo | PYTHON | jupyter |

Reproducibility

No specific reproducibility files found.

Status

  • Issues: Enabled
  • Wiki: Enabled
  • Pages: Disabled

README

Conversational Flow Prototype

A graph-based KYC (Know Your Customer) conversation flow prototype built with LangGraph, Streamlit, and Claude.

Overview

This prototype implements an AI-powered KYC data collection system that guides users through a conversational interface to gather required information. The system uses a graph-based architecture with four main nodes:

  1. Analyzer Node: Extracts KYC information from user messages using Claude
  2. Router Node: Determines if KYC is complete or needs more information
  3. Question Generator Node: Generates natural language questions for missing fields
  4. Finalizer Node: Saves completed KYC data to the database

Architecture

┌─────────────┐     ┌──────────┐     ┌─────────────────────┐
│   User      │────▶│ Analyzer │────▶│       Router        │
│   Input     │     │   Node   │     │ (Complete/Incomplete)│
└─────────────┘     └──────────┘     └──────────┬──────────┘
                                                │
                   ┌────────────────────────────┴────────────────────────────┐
                   │                                                          │
                   ▼                                                          ▼
       ┌───────────────────────┐                               ┌──────────────────┐
       │  Question Generator   │                               │    Finalizer     │
       │   (Ask next field)    │                               │ (Save to DB)     │
       └───────────────────────┘                               └──────────────────┘

Tech Stack

Component Technology Purpose
Package Manager uv Fast Python package management
LLM Claude (Anthropic) Information extraction and question generation
Tooling Instructor Structured LLM output with Pydantic
Orchestration LangGraph State machine for conversation flow
Database PostgreSQL (JSONB) Flexible data storage (optional)
Validation Pydantic Schema validation
Frontend Streamlit Web interface

Data Model

The system maintains two types of data in PostgreSQL JSONB columns:

  • chat_history: Immutable source of truth containing all user interactions (append-only)
  • extracted_data: Mutable cache of structured KYC data (can be regenerated)

Getting Started

Prerequisites

  • Python 3.11+
  • PostgreSQL 16+ (optional, for full app only)
  • uv package manager

Installation

  1. Clone the repository: 

    git clone https://github.com/Digital-AI-Finance/Conversational-Flow-Prototype.git
cd Conversational-Flow-Prototype

  2. Install dependencies: 

    uv sync

  3. Copy environment file and configure: 

    cp .env.example .env
# Edit .env with your Anthropic API key

  4. (Optional) Start PostgreSQL for full app: 

    docker-compose up -d

Running the Applications

# Simple app with demo mode (no database required)
uv run streamlit run streamlit/app_simple.py

# Full app with database support
uv run streamlit run streamlit/app.py

The application will be available at http://localhost:8501.

Running the Notebook

# Start Jupyter and open the demo notebook
uv run jupyter notebook notebook/kyc_conversation_flow_demo.ipynb

Development

Running Tests

# Run all tests
uv run pytest notebook/test_notebook.py

# Run with verbose output
uv run pytest notebook/test_notebook.py -v

Code Quality

# Linting
uv run ruff check streamlit notebook

# Type checking
uv run mypy streamlit

# Format code
uv run ruff format streamlit notebook

Project Structure

├── notebook/                      # Jupyter notebook demos
│   ├── kyc_conversation_flow_demo.ipynb
│   └── test_notebook.py
├── streamlit/                     # Web applications
│   ├── app.py                     # Full app with PostgreSQL
│   └── app_simple.py              # Simplified demo app
├── pyproject.toml                 # Project configuration
├── README.md                      # This file
├── .env                           # Environment variables (create from .env.example)
└── docker-compose.yml             # PostgreSQL for local development

KYC Fields

Required Fields

  • First name, Last name
  • Date of birth (must be 18+)
  • Nationality
  • Email, Phone
  • Address (street, city, country)
  • Employment status
  • Income range
  • Source of funds
  • Politically exposed person status

Optional Fields

  • Address postal code
  • Tax ID

Environment Variables

Variable Description Default
ANTHROPIC_API_KEY Anthropic API key Required
DATABASE_URL PostgreSQL connection URL postgresql://kyc_user:kyc_password@localhost:5432/kyc_db
CLAUDE_MODEL Claude model to use claude-sonnet-4-20250514
DEBUG Enable debug mode false
LOG_LEVEL Logging level INFO

License

Private repository - Digital AI Finance

Contributing

  1. Create a feature branch
  2. Make changes
  3. Run tests and linting
  4. Submit a pull request