Back to Blog

Getting Started with Aiklyra: A Python Package for Conversation Flow Analysis

Welcome to our tutorial on using Aiklyra, a Python package designed to simplify conversation flow analysis. With Aiklyra, you can submit conversation data for asynchronous analysis, retrieve detailed results, process them into directed graphs, apply custom filters, and visualize the results interactively. In this guide, we’ll walk you through each step—from installation to visualization—with code examples and explanations.

Posted by

1. Installation

Before using Aiklyra, install the package using pip. In your terminal or within your notebook, run:

This command installs version 1.0.0 of the package while suppressing extra output for a cleaner installation process.

2. Initializing the Client and Submitting Conversation Analysis

Aiklyra uses an asynchronous workflow to process conversation data. First, you need to initialize the client by providing the API’s base URL. Then, you submit your conversation data for analysis. The API will queue your job and return a unique job ID.

Below is an example code snippet that demonstrates this process:

1

2from aiklyra.client import AiklyraClient
3from aiklyra.exceptions import AnalysisError, AiklyraAPIError
4import time
5

6# Initialize the client with the API base URL
7client = AiklyraClient(base_url="https://api.aiklyra.com")
8

9# Define sample conversation data between a delivery service support agent and its clients.
10conversation_data = {
11    "conversation_1": [
12        {"role": "user", "content": "Hello, good morning."},
13        {"role": "assistant", "content": "Good morning! How can I assist you today?"},
14        {"role": "user", "content": "I need help with the delivery fee on my order."},
15        {"role": "assistant", "content": "Sure, I'd be happy to help with your delivery fee issue. What seems to be the problem?"},
16        {"role": "user", "content": "I was charged more than expected on my last order."},
17        {"role": "assistant", "content": "It looks like there was an extra handling fee applied due to express shipping. I can adjust that for you."},
18        {"role": "user", "content": "That makes sense. Thank you for clarifying."},
19        {"role": "assistant", "content": "You're welcome! Have a great day and enjoy your delivery."}
20    ],
21    "conversation_2": [
22        {"role": "user", "content": "Hi there, good afternoon."},
23        {"role": "assistant", "content": "Good afternoon! How may I help you today?"},
24        {"role": "user", "content": "I need help with creating an account."},
25        {"role": "assistant", "content": "Absolutely, I can help with that. What issue are you facing?"},
26        {"role": "user", "content": "I’m not receiving the verification email when I try to sign up."},
27        {"role": "assistant", "content": "Please check your spam folder. If it's not there, I can resend the verification email."},
28        {"role": "user", "content": "I found it in spam. All sorted now, thanks!"},
29        {"role": "assistant", "content": "Great to hear that! Let us know if you need further assistance."}
30    ],
31    "conversation_3": [
32        {"role": "user", "content": "Hello, good evening."},
33        {"role": "assistant", "content": "Good evening! What can I do for you today?"},
34        {"role": "user", "content": "I need help with security measures for my account."},
35        {"role": "assistant", "content": "Of course, I can help with that. Could you tell me more about your concern?"},
36        {"role": "user", "content": "I'm worried about unauthorized access after noticing some unusual activity."},
37        {"role": "assistant", "content": "I recommend enabling two-factor authentication and reviewing your recent login history."},
38        {"role": "user", "content": "I'll set up 2FA right away. Thank you for the guidance."},
39        {"role": "assistant", "content": "You're welcome! Stay safe and secure."}
40    ],
41    "conversation_4": [
42        {"role": "user", "content": "Hi, good morning."},
43        {"role": "assistant", "content": "Good morning! How can I help you today?"},
44        {"role": "user", "content": "I need help with delivery time details."},
45        {"role": "assistant", "content": "Certainly! What questions do you have about delivery times?"},
46        {"role": "user", "content": "My order seems to be arriving later than the estimated time."},
47        {"role": "assistant", "content": "Sometimes delays occur due to weather or traffic. I can check the current status of your delivery."},
48        {"role": "user", "content": "It says it will be delivered by this evening. That works for me, thanks."},
49        {"role": "assistant", "content": "Glad I could help! Let us know if you need anything else."}
50    ],
51    "conversation_5": [
52        {"role": "user", "content": "Hello, good afternoon."},
53        {"role": "assistant", "content": "Good afternoon! How may I assist you today?"},
54        {"role": "user", "content": "I need help with the delivery fee."},
55        {"role": "assistant", "content": "Sure, I'd be happy to help. Can you describe the issue?"},
56        {"role": "user", "content": "The fee on my order seems unusually high."},
57        {"role": "assistant", "content": "There might be a promotional error. I will adjust the fee for you."},
58        {"role": "user", "content": "That sounds great, thank you."},
59        {"role": "assistant", "content": "Anytime! Enjoy your day and your delivery."}
60    ]
61    # ... Additional conversations can be added here
62}
63

64# Submit the analysis job
65try:
66    submission = client.submit_analysis(
67        conversation_data=conversation_data,
68        min_clusters=7,
69        max_clusters=10,
70        top_k_nearest_to_centroid=10,
71        role="Any"
72    )
73    print(f"Job submitted. Job ID: {submission.job_id}")
74except AnalysisError as e:
75    print(f"Analysis failed: {e}")
76except AiklyraAPIError as e:
77    print(f"API Error: {e}")
78

In this snippet, the submit_analysis method sends your conversation data to the API and returns a job_id if successful.

3. Checking Job Status

Once your job is submitted, you can check its status using the returned job ID. The job status response includes details such as:

  • Status: The current state of the task (e.g., PENDING, STARTED, SUCCESS, FAILURE, RETRY, REVOKED).
  • Estimated Wait Time: If the job is still pending.
  • Result: The analysis result (if the job is completed).
  • Error: Any error messages if the job fails.

Here's how you can check the job status:

1job_status = client.check_job_status(submission.job_id)
2print(job_status)

This call returns a JobStatusResponse object. If the job has completed, the analysis result is available within the result attribute.

4. Constructing and Retrieving the Graph

After retrieving the analysis result, the next step is to convert the analysis into a directed graph. The GraphProcessor class does exactly that by:

  • Extracting the transition matrix and intent mappings from the analysis result.
  • Building a directed graph (using NetworkX) where nodes represent intents and edges represent transition probabilities.

The following code snippet shows how to create and view the graph:

1from aiklyra.graph.processor import GraphProcessor
2

3# Extract the analysis result from the job status
4analysis = job_status.result
5

6# Create a GraphProcessor instance using the job status
7graph_processor = GraphProcessor(job_status)
8

9# Retrieve the constructed directed graph
10graph = graph_processor.get_graph()
11print(graph)

This call returns a JobStatusResponse object. If the job has completed, the analysis result is available within the result attribute.

5. Filtering the Graph

Aiklyra provides flexible graph filtering options to refine the graph by removing low-weight edges or applying custom filters. In this example, we use the FilterFR filter to remove edges below a specified weight and reconnect the graph.

1from aiklyra.graph.filters import FilterFR
2

3# Create a FilterFR instance with a minimum weight of 0.05 and top-k value of 1
4fr_filter = FilterFR(min_weight=0.05, top_k=1)
5

6# Apply the filter to the graph using the GraphProcessor
7filtered_graph = graph_processor.filter_graph(fr_filter)

This filtered graph now contains only the strongest connections between nodes, making the conversation flow clearer.

6. Visualizing the Graph Interactively

Finally, Aiklyra allows you to visualize the conversation graph interactively within your notebook. The interactive visualizer generates an HTML file that you can display directly.

1# Retrieve an interactive visualizer from the GraphProcessor
2visualizer = graph_processor.get_visualizer("interactive_visualizer")
3

4# Visualize the graph; the 'notebook=True' flag indicates that the output should be rendered in the notebook.
5visualizer.visualize(graph_processor.get_graph(), notebook=True)
6

7# Optionally, display the generated HTML content inline
8from IPython.display import HTML, display
9

10with open("graph.html", "r", encoding="utf-8") as f:
11    html_content = f.read()
12

13display(HTML(html_content))

The interactive visualization provides a user-friendly interface to explore the graph. You can zoom, pan, and interact with the graph to better understand the conversation flow.

tutorial visual

Conclusion

In this tutorial, you learned how to:

  • Install the Aiklyra package.
  • Initialize the client and submit conversation data for analysis.
  • Check the status of your analysis job.
  • Convert the analysis result into a directed graph.
  • Apply filtering to refine the graph.
  • Visualize the graph interactively in your notebook.

Aiklyra streamlines the process of analyzing complex conversation data, making it easier to extract meaningful insights and improve customer support workflows.

If you have any questions or need further assistance, feel free to reach out via our GitHub repository or contact our support team.

Happy Analyzing!

This blog post provides a comprehensive guide that mirrors the step-by-step process you’d follow in your notebook. Enjoy using Aiklyra and transforming your conversation data into actionable insights!