Transaction Matching API

A FastAPI-based solution for matching transactions to users and semantic search of transaction descriptions.

Setup

Install Dependencies

pip install -r requirements.txt

Run the API

uvicorn app.main:app --reload

The API will be available at http://localhost:8000

API Documentation

Visit http://localhost:8000/docs for interactive Swagger documentation.

Endpoints

Task 1: Match Transaction to Users

GET /api/v1/match/{transaction_id}

Returns users matching the transaction description with fuzzy matching.

Response:

{
  "users": [
    {"id": "U4NNQUQIeE", "match_metric": 95.24},
    {"id": "U4Pps5wQzx", "match_metric": 62.5}
  ],
  "total_number_of_matches": 2
}
Proof : ![Image1](image.png)

Task 2: Semantic Search

POST /api/v1/semantic-search

Returns transactions with similar descriptions using embeddings.

Example:

curl -X POST http://localhost:8000/api/v1/semantic-search \
  -H "Content-Type: application/json" \
  -d '{"query": "payment from consultant", "top_k": 5}'

Response:

{
  "transactions": [
    {"id": "txn_001", "embedding": [0.123, -0.456, ...]},
    {"id": "txn_002", "embedding": [0.234, -0.567, ...]}
  ],
  "total_number_of_tokens_used": 1523
}
![Image2](image-1.png)

Solution Discussion

Task 1: Fuzzy User Matching

Approach:

• Extracts names from transaction descriptions using regex patterns
• Normalizes names by removing special characters and converting to lowercase
• Uses RapidFuzz library with three similarity metrics:
  • ratio: Full string comparison
  • partial_ratio: Substring matching (handles extra words)
  • token_sort_ratio: Word-order independent matching
• Returns matches above 60% threshold, sorted by relevance

Limitations:

1. Name Extraction: Regex patterns may miss non-standard formats or non-Latin characters
2. Cultural Names: Multi-part names (e.g., Chinese, Arabic) may not match well
3. Nicknames: "Bob" vs "Robert" won't match without a dictionary
4. Performance: O(n) complexity for each transaction (scales with user count)
5. Threshold Tuning: Fixed 60% threshold may need adjustment per use case

Edge Cases Handled:

• Typos (e.g., "Jhn Smith" → "John Smith")
• Extra spaces and punctuation
• Case sensitivity
• Missing data (empty names)

Task 2: Semantic Search

Approach:

• Uses Sentence-BERT model (all-MiniLM-L6-v2) for generating embeddings
• Computes cosine similarity between query and transaction descriptions
• Returns top-k most similar transactions with their embeddings
• Tracks total token count across all embeddings

Limitations:

1. Performance: Encodes every transaction on each request (no caching)
2. Memory: Stores full embeddings (384 dimensions) in response payload
3. Model Size: ~80MB model download on first run
4. Context Length: Limited to 256 tokens per transaction
5. Language: Model primarily trained on English text
6. Cold Start: First request is slow due to model loading

Potential Improvements:

• Pre-compute and cache transaction embeddings
• Use vector database (Pinecone, Weaviate) for efficient similarity search
• Return similarity scores instead of full embeddings
• Support multilingual models for international transactions

Task 3: Production Recommendations

Architecture Changes

1. Database Integration

   • Replace CSV files with PostgreSQL/MongoDB
   • Index transaction IDs and user names
   • Use connection pooling

2. Caching Layer

   • Redis for frequently accessed transactions
   • Pre-compute and cache embeddings
   • Cache user matching results (with TTL)

3. Vector Database

   • Use Pinecone/Weaviate/Qdrant for embedding storage
   • Enable ANN (Approximate Nearest Neighbor) search
   • Reduce search latency from O(n) to O(log n)

4. Model Optimization

   • Use ONNX Runtime for 2-3x faster inference
   • Quantize model to reduce size
   • Batch process embeddings
   • Consider smaller models for latency-critical paths

Scalability

1. Async Processing

   • Make embedding generation async
   • Use worker queues (Celery) for batch processing
   • WebSocket for real-time updates

2. Horizontal Scaling

   • Containerize with Docker
   • Deploy on Kubernetes
   • Load balancing across multiple instances
   • Separate read/write endpoints

3. Monitoring

   • Prometheus + Grafana for metrics
   • Track match quality, latency, throughput
   • Alert on model degradation
   • Log failed matches for retraining

Data Quality

1. Name Normalization Pipeline

   • Add nickname/alias dictionary
   • Handle international name formats
   • Phonetic matching (Metaphone/Soundex)
   • Entity resolution for duplicates

2. Model Improvements

   • Fine-tune on Deel transaction data
   • Active learning for edge cases
   • A/B test different embedding models
   • Ensemble multiple models

Security & Compliance

1. Authentication

   • API key authentication
   • OAuth2/JWT tokens
   • Rate limiting per client

2. Data Privacy

   • PII masking in logs
   • Encryption at rest and in transit
   • GDPR compliance for user data
   • Audit trails