img2card

Welcome to the img2card project! img2card is a unique Telegram Bot designed to simplify your contact management. It takes facade pictures or contact card pictures as input and generates vCard files (.ics), allowing you to easily add new contacts to your address book.

Functional Features

• Image to vCard: img2card can extract contact information from images and convert it into a vCard file. This feature supports a wide range of image formats and is designed to handle various styles of contact cards.

• Telegram Bot: img2card is primarily designed as a Telegram Bot, making it easily accessible from any device with Telegram installed. Simply send an image to the bot, and receive a vCard file in return.

Technical Features

img2card uses advanced image processing and text extraction algorithms to accurately extract contact information from images. Once the information is extracted, it is formatted into a vCard file which can be easily imported into most contact management applications.

📇 - vCard generation
👁️‍🗨️ - visual transcription using OpenAI GPT-4 vision model
🤖 - contact generation using OpenAI GPT-3.5 or GPT-4 model
🗺️ - places and venues lookup using [Serpapi](https://serpapi.com/) and [Geoapify](https://geoapify.com/) APIs
🔠 - prompt management using [Langchain](https://langchain.com/)
🔍 - openai tracing using [Langsmith](https://smith.langchain.com/)

Project Structure

The project is structured as follows:

• src/: This is where the main application code resides. It includes the following Python files:
  • bot.py: implementation of the Telegram bot
  • llm/agent.py: main logic for the Lanngchain agent
  • llm/places.py: place-related information
  • llm/prompt.py: prompts for the agent
  • settings.py: project settings
  • utils.py: utility functions used throughout the project
• tests/: This directory contains the test files for the project
• Dockerfile: Docker file

Getting Started

To start using img2card, you'll need to have Telegram installed on your device. Once you have Telegram, you can add the img2card bot to your contacts and start sending images.

User Guide

You can use both, desktop and mobile telegram applications, in order to create your contact cards. 0) Open img2card telegram bot

1. Start typing /start
2. Either drag and drop the image file into the chat window (desktop), or click on attachment (mobile/desktop)
3. Select the image "uncompressed", always. If you compress the image, the EXIF data is removed, and will make it harder to identify the business 3a) In case the application do not recognise the location of the picture (EXIF/GPS data), the bot will ask the user for his/her current location, as a proxy for the location of the picture
4. The model will check for any sigh, and it will extract the name of the business from it. Once is over, it will do an heuristic check to narrow down the business
5. Once enough data from the businees is retrieved, then the contact card will be generated

Server Guide

To get started with the Telegram bot, you'll need to install some Python dependencies using conda or miniconda:

conda install -f environment.yml
conda activate img2card

If you need to furhter develop the bot, install the development dependencies

conda activate img2card
pip install -r requirements_dev.txt

Running the bot requires to configure following environment variables:

AZURE_OPENAI_API_KEY=<api key from azure open ai>
AZURE_OPENAI_API_BASE=<api endopoint>


SERPAPI_API_KEY=<api key from https://serpapi.com/>
GEOAPIFY_API_KEY=<api key from https://geoapify.com/>

LANGSMITH_API_KEY=<api key from https://smith.langchain.com/>
LANGSMITH_ENDPOINT=
LANGSMITH_PROJECT=

TELEGRAM_TOKEN=
TELEGRAM_DEV_CHAT_ID=

Finaly, run following command:

python -m src.bot