spec2chat is a Python library for building task-oriented conversational systems based on PPTalk service specifications. It automatically transforms OpenAPI descriptions into dialogue flows with slot filling, service selection, and question generation, powered by GPT-based language models.

The library is designed to simplify the creation of chatbots that interact with web services, allowing developers to focus on business logic and user experience.

pip install spec2chat

After installing the library, you must download the following NLP resources required by spec2chat:

# Lexical database used for tag extraction
python -m nltk.downloader wordnet

# Lightweight English model for spaCy (required for tag and synonym detection)
python -m spacy download en_core_web_sm

# (Optional) Medium-size model for improved semantic similarity (used in slot ranking)
python -m spacy download en_core_web_md

The system expects a MongoDB database organized by domain (hotels, restaurants, etc.) with the following collections:

• services: OpenAPI specifications of the conversational services.
• intents: list of available intents per domain.
• slot_ranking: discriminative parameters with usage frequencies.

Before using the library, make sure to define the following environment variables:

export OPENAI_API_KEY=sk-...
export MONGODB_URI="mongodb://localhost:27017"

You can also use the .env.example file as a template.
Simply copy and rename it to .env:

cp .env.example .env

If you're using python-dotenv, it will be automatically loaded at runtime.

You can find sample data to populate your MongoDB database in the /data folder.
To load them automatically, run:

python scripts/load_example_data.py

The main public interface of spec2chat is the function:

from spec2chat import run_chatbot

This is the only function you need to orchestrate a complete, dynamic, task-oriented conversational flow based on OpenAPI service specifications.

All internal components (e.g., slot filling, intent detection, service selection, etc.) are encapsulated and managed automatically.

run_chatbot(user_input: str, **dialogue_state) -> dict

• On the first call, provide only the user's input:

  run_chatbot("I want a vegetarian restaurant")

• On subsequent calls, pass the updated dialogue state returned from the previous step (e.g. filledslots, intent, useranswers, etc.) along with the same user_input.

• Repeat until the returned object includes:

  { "end_of_conversation": true }

A dictionary representing the current state and next action of the dialogue.
See the Sample Outputs section for all possible formats.

from spec2chat.core.orchestrator import run_chatbot

user_input = "I want a cheap vegetarian restaurant"
user_answers = []

response = run_chatbot(user_input, user_answers=user_answers)
print(response)

Depending on the dialogue stage, run_chatbot() may return different structures:

{
  "questions": {
    "pricerange": "How much are you willing to spend?",
    "food": "What type of food are you looking for?"
  },
  "filledslots": {
    "food": "vegetarian"
  },
  "intent": "bookrestaurant",
  "userinput": "I want a cheap vegetarian restaurant",
  "dom": "restaurant",
  "reqslots": ["pricerange", "food"],
  "tasks": {
    "restaurant": "bookrestaurant"
  },
  "final": false
}

{
  "questions": {
    "time": "What time would you like the reservation?"
  },
  "filledslots": {
    "food": "vegetarian",
    "pricerange": "cheap"
  },
  "service_id": "660fe62a88cdb240e63e5114",
  "intent": "bookrestaurant",
  "dom": "restaurant",
  "tasks": {
    "restaurant": "bookrestaurant"
  },
  "final": true,
  "reqslots": ["food", "pricerange", "time"]
}

{
  "end_of_conversation": true
}

{
  "chatbot_answer": "That's an interesting question! Let me think...",
  "useranswers": [
    {
      "user": "Tell me about the Eiffel Tower",
      "chatbot": "The Eiffel Tower is a famous landmark in Paris..."
    }
  ],
  "dom": "out-of-domain"
}

spec2chat implements a complete conversational pipeline including:

1. Domain and intent detection
2. Initial slot filling via language models
3. Service selection based on discriminative parameters
4. Tag-based disambiguation and additional question generation
5. Final slot filling using predefined or refined questions
6. Multi-task management across domains
7. Support for open-domain interactions

spec2chat/
├── core/
│   └── orchestrator.py
├── db/
│   └── mongo.py
├── data/
│   ├── hotels.services.json
│   ├── hotels.intents.json
│   └── hotels.slot_ranking.json
├── examples/
│   ├── run_restaurant_example.py
│   ├── run_hotel_example.py
│   └── flask-client/
│       ├── app.py
│       └── static/
│           └── ...
├── scripts/
│   └── load_example_data.py
├── services/
│   ├── domain_manager.py
│   ├── intent_recognition.py
│   ├── slot_filling.py
│   ├── service_selection.py
│   ├── tag_filter.py
│   ├── slot_ranking.py
│   ├── open_domain.py
│   ├── question_generation.py
│   └── question_improvement.py
│   └── question_retrieval.py
├── utils/
│   └── openai_config.py
├── .env.example
├── README.md
├── setup.py
└── pyproject.toml

This repository includes several complete usage examples of the spec2chat library:

• 🧑‍🍳 Restaurant reservation example

  • examples/run_restaurant_example.py
  • Google Colab notebook: https://colab.research.google.com/drive/15xPmQ6CzkZe3-rLEp52qHLfRQHZACrxv

• 🏨 Hotel booking example

  • Python script: examples/run_hotel_example.py
  • Google Colab notebook: https://colab.research.google.com/drive/1c5_PjkPI3H7BMOMIc0Qf61D3_yAoYZl2

• 💬 Interactive web client using Flask

  • Flask client: examples/flask-client

This project is based on the research work published in:

Rodríguez-Sánchez, M.J., Callejas, Z., Ruiz-Zafra, A., Benghazi, K. (2025).
Combining Generative AI and PPTalk Service Specification for Dynamic and Adaptive Task-Oriented Chatbots.
In: Gaaloul, W., Sheng, M., Yu, Q., Yangui, S. (eds) Service-Oriented Computing. ICSOC 2024.
Lecture Notes in Computer Science, vol 15404. Springer, Singapore.
📎 https://doi.org/10.1007/978-981-96-0805-8_13