🧠 Building an Enterprise-Grade Grammar API with AI/ML Integration

Vivek Jaiswal — Fri, 31 Oct 2025 11:35:26 +0000

How I Built a Production-Ready Grammar Checking API with Multi-Language Support, LLM Integration, and Advanced NLP

TL;DR: I built an open-source, production-ready Grammar API with multi-agent AI systems, LLM integration, and enterprise features like PII detection, intelligent caching, and multi-language support. This article walks through the architecture, design decisions, and how you can use or contribute to it.

GitHub: github.com/vivekjaiswal-ai/grammar-api

The Problem: Why Another Grammar API?

As developers, we've all used grammar checking tools. But when you need to integrate grammar checking into your application at scale, you quickly run into limitations:

Language Barriers: Most APIs support only English or a handful of languages
No AI Integration: Traditional rule-based checkers miss context and nuance
Privacy Concerns: Sending sensitive data to third-party APIs isn't always an option
Cost at Scale: Per-request pricing models become expensive fast
Limited Customization: One-size-fits-all solutions don't fit enterprise needs

I wanted to build something different - an AI-first, privacy-conscious, production-ready grammar API that developers could self-host or extend.

The Solution: A Multi-Agent AI Architecture

The Grammar API is built on a multi-agent AI system where specialized agents handle different aspects of text analysis:

🤖 Core AI Agents

Grammar Agent - Powered by LanguageTool, handles rule-based grammar validation
Semantic Agent - Uses LLMs (GPT-4, Claude, Azure OpenAI) for context understanding
Style Agent - Analyzes writing style and provides improvement suggestions
Linguistic Agent - Advanced language detection with ML models
PII Detection Agent - Identifies and anonymizes sensitive information using Presidio

Each agent operates independently but contributes to a unified validation result, providing comprehensive feedback.

Key Features That Set It Apart

🌍 Multi-Language Support

Support for 27+ languages including English, Spanish, French, German, Chinese, Japanese, Arabic, and more.

# Automatic language detection
POST /api/v1/validate
{
    "text": "Este texto tiene un error gramatical.",
    "auto_detect_language": true
}

# Returns Spanish grammar suggestions automatically

🧠 AI/ML Integration

The API supports multiple LLM providers for advanced semantic analysis:

# Use GPT-4 for context-aware suggestions
POST /api/v1/validate
{
    "text": "The company are performing well.",
    "validation_level": "advanced",
    "enable_llm_enhancement": true,
    "llm_provider": "openai"
}

Response includes:

Rule-based grammar corrections
AI-powered style improvements
Context-aware semantic suggestions
Confidence scores for each suggestion

🔒 Privacy-First PII Detection

Built-in PII detection and anonymization for sensitive data:

POST /api/v1/validate
{
    "text": "Contact John Doe at john@email.com or 555-1234.",
    "pii_detection": {
        "enabled": true,
        "anonymize": true,
        "sensitivity_level": "high"
    }
}

Automatically detects and handles:

Names, emails, phone numbers
Credit cards, SSNs, IP addresses
Locations, dates, and custom entities
Creates audit logs for compliance

⚡ Intelligent Caching System

Multi-layer caching strategy for optimal performance:

In-Memory Cache (Redis) - Sub-millisecond response times
Pattern Cache - Learns from common corrections
Session Cache - User-specific patterns and preferences

# First request: ~250ms (LanguageTool processing)
# Cached request: ~5ms (Redis cache hit)

📊 Batch Processing

Efficient batch validation for high-throughput scenarios:

POST /api/v1/validate/batch
{
    "texts": [
        {"text_id": "doc1", "text": "First document..."},
        {"text_id": "doc2", "text": "Second document..."},
        {"text_id": "doc3", "text": "Third document..."}
    ],
    "validation_level": "advanced"
}

Processes multiple documents concurrently with automatic load balancing.

Architecture Deep Dive

Clean Architecture + Domain-Driven Design

The codebase follows Clean Architecture principles with clear separation of concerns:

src/
├── core/              # Business logic & domain models
│   ├── domain/        # Domain entities & value objects
│   └── use_cases/     # Application use cases
├── infrastructure/    # External integrations
│   ├── database/      # PostgreSQL with SQLAlchemy
│   ├── cache/         # Redis caching layer
│   └── external/      # LanguageTool, LLM providers
└── api/              # FastAPI REST endpoints
    └── v1/           # API version 1

Benefits:

Easy to test (dependency injection throughout)
Pluggable components (swap LLM providers, databases)
Maintainable at scale (clear boundaries and responsibilities)

Performance Optimizations

Connection Pooling: Reusable database and Redis connections
Async/Await: Non-blocking I/O for all operations
Singleton Pattern: Single LanguageTool instance per language
Query Optimization: Indexed database queries with eager loading

Monitoring & Observability

Built-in structured logging with correlation IDs:

{
    "timestamp": "2025-10-31T10:30:45.123Z",
    "level": "INFO",
    "correlation_id": "abc-123",
    "endpoint": "/api/v1/validate",
    "processing_time_ms": 89,
    "cache_hit": true,
    "language": "en-US"
}

Comprehensive health checks for all dependencies:

GET /health
# Returns detailed status of:
# - Database connection pool
# - Redis cache operations
# - Language detection service
# - LLM service availability
# - System resources (CPU, memory, disk)

Real-World Use Cases

1. Content Management Systems

Integrate grammar checking into your CMS:

// JavaScript/TypeScript example
async function validateContent(content) {
    const response = await fetch('http://localhost:8000/api/v1/validate', {
        method: 'POST',
        headers: {
            'X-API-Key': 'gapi_your_key_here',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            text: content,
            validation_level: 'advanced'
        })
    });
    return await response.json();
}

2. Form Validation

Real-time grammar checking in web forms:

// React example
const [errors, setErrors] = useState([]);

const handleTextChange = debounce(async (text) => {
    const result = await validateContent(text);
    setErrors(result.errors);
}, 500);

3. Automated Document Processing

Batch process documents for quality assurance:

# Python example
import httpx

async def process_documents(documents):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            'http://localhost:8000/api/v1/validate/batch',
            json={'texts': documents},
            headers={'X-API-Key': 'gapi_your_key_here'}
        )
        return response.json()

4. Customer Support Systems

Validate agent responses before sending:

# Check for grammar and PII before sending
result = validate_text(
    agent_response,
    pii_detection={'enabled': True, 'anonymize': True}
)

if result.errors:
    # Show corrections to agent
    pass
if result.metadata.pii_detection.has_pii:
    # Alert supervisor about PII exposure
    pass

Getting Started in 5 Minutes

Prerequisites

Python 3.12+
PostgreSQL 15+
Redis 7+

Quick Setup

# Clone the repository
git clone https://github.com/vivekjaiswal-ai/grammar-api.git
cd grammar-api

# Install dependencies (using uv for speed)
pip install uv
uv sync

# Set up environment
cp .env.example .env
# Edit .env with your database credentials

# Run database migrations
uv run alembic upgrade head

# Create an API key
uv run python scripts/create_api_key.py

# Start the server
uv run python main.py

The API is now running at http://localhost:8000!

Your First API Call

curl -X POST "http://localhost:8000/api/v1/validate" \
  -H "X-API-Key: gapi_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This sentence have a error.",
    "validation_level": "advanced"
  }'

Response:

{
    "text_id": "abc-123",
    "processing_time_ms": 89,
    "errors": [
        {
            "error_type": "grammar",
            "severity": "high",
            "message": "The verb 'have' is plural.",
            "suggestions": [
                {"text": "This sentence has", "confidence": 0.8}
            ]
        }
    ],
    "quality_score": 0.75,
    "confidence_score": 0.95
}

Technical Decisions & Trade-offs

Why FastAPI?

Performance: One of the fastest Python frameworks (thanks to Starlette and Pydantic)
Type Safety: Full type hints and automatic validation
Documentation: Auto-generated OpenAPI/Swagger docs
Async Support: Native async/await for high concurrency

Why PostgreSQL + Redis?

PostgreSQL: ACID compliance, JSON support, complex queries, battle-tested
Redis: Sub-millisecond reads, perfect for caching, pub/sub for future features

Why Multi-Agent Architecture?

Traditional monolithic grammar checkers are rigid. By splitting concerns into specialized agents:

Modularity: Add new agents without touching existing code
Scalability: Scale individual agents based on demand
Maintainability: Each agent has a single responsibility
Extensibility: Easy to plug in new LLM providers or rule engines

Trade-offs

Complexity: More components to manage (DB, Redis, LanguageTool)
Resource Usage: LanguageTool requires ~500MB RAM per language
Initial Setup: More configuration than a simple API

But you gain:

Full control over your data (self-hosted)
No per-request costs (infrastructure costs only)
Unlimited customization (open source)
Production-grade reliability (proper error handling, retries, circuit breakers)

Performance Benchmarks

Tested on 12-core AMD, 16GB RAM, Windows 11:

Scenario	Response Time	Throughput
Single validation (cached)	~5ms	~200 req/s
Single validation (uncached)	~100ms	~50 req/s
Batch (10 texts, cached)	~50ms	~100 batch/s
Batch (10 texts, uncached)	~800ms	~12 batch/s
With LLM enhancement	~1500ms	~6 req/s

Note: First request per language downloads LanguageTool data (~250MB), subsequent requests are instant.

Contributing & Community

This is an open-source project and contributions are welcome! Here's how you can help:

🐛 Report Bugs

Found an issue? Open a GitHub issue

💡 Suggest Features

Have an idea? Start a discussion

🔧 Contribute Code

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests (we maintain 80%+ coverage)
Submit a pull request

Areas we'd love help with:

Additional LLM provider integrations (Gemini, Mistral, etc.)
More language-specific rules and patterns
Performance optimizations
UI/Dashboard for API management
Mobile SDKs (iOS, Android)
Client libraries (Ruby, Go, PHP, etc.)

📚 Improve Documentation

Fix typos or unclear explanations
Add code examples in different languages
Create tutorials for specific use cases
Translate documentation

See: CONTRIBUTING.md for detailed guidelines.

Roadmap

Q4 2025

✅ Core API with multi-language support
✅ Multi-agent AI architecture
✅ PII detection and anonymization
✅ Comprehensive documentation
✅ Open source release

Q1 2026

[ ] Dashboard UI for API key management
[ ] Webhooks for async processing
[ ] Custom rule engine (user-defined grammar rules)
[ ] Docker Compose for one-command setup
[ ] Kubernetes deployment templates

Q2 2026

[ ] Real-time collaborative checking (WebSocket API)
[ ] Plugin system for custom agents
[ ] Machine learning model fine-tuning
[ ] Multi-tenant support
[ ] SaaS version (hosted option)

Q3-Q4 2026

[ ] Browser extensions (Chrome, Firefox, Edge)
[ ] IDE plugins (VSCode, JetBrains)
[ ] Mobile SDKs
[ ] GraphQL API
[ ] Offline mode support

Vote on features: GitHub Discussions

Lessons Learned

Building this API taught me several important lessons:

1. Async/Await Is Your Friend

Moving from synchronous to asynchronous code improved throughput by 3-4x. The key was making all I/O operations (database, Redis, HTTP) non-blocking.

2. Caching Strategy Matters

A naive cache implementation cached entire responses. But by caching at the agent level (individual grammar rules, language detection results), I achieved much higher hit rates.

3. Error Handling Is Not Optional

In production, everything fails: databases disconnect, Redis times out, external APIs go down. Implementing proper:

Retries with exponential backoff
Circuit breakers
Fallback strategies
Graceful degradation

Made the difference between a fragile prototype and a production-ready system.

4. Documentation Is a Feature

Good docs reduce support burden and increase adoption. I spent almost as much time on documentation as on code - and it was worth it.

5. Type Safety Catches Bugs

Using Pydantic for request/response validation and mypy for static type checking caught dozens of bugs before they reached production.

Enterprise Features

While this is an open-source project, it's built with enterprise needs in mind:

Security

✅ API key authentication with SHA-256 hashing
✅ Rate limiting (per key, per IP, per endpoint)
✅ CORS configuration
✅ PII detection and audit logging
✅ SQL injection prevention (parameterized queries)
✅ Input validation and sanitization

Reliability

✅ Database connection pooling
✅ Redis connection resilience
✅ Health checks for all dependencies
✅ Graceful shutdown handling
✅ Automatic retry logic
✅ Circuit breakers for external services

Observability

✅ Structured JSON logging
✅ Correlation IDs for request tracing
✅ Performance metrics
✅ Error tracking and alerting
✅ Health check endpoints
✅ API usage analytics

Scalability

✅ Horizontal scaling (stateless design)
✅ Database indexing and query optimization
✅ Multi-layer caching strategy
✅ Async processing for high concurrency
✅ Batch processing support
✅ Load balancing ready

FAQ

Q: Is this production-ready?

A: Yes! It's running in production at QBits Marketing Research, handling thousands of validations daily.

Q: Can I use this commercially?

A: Absolutely! It's MIT licensed - use it freely in commercial projects.

Q: How much does it cost to run?

A: Infrastructure only. For ~10K requests/day:

Small VPS: ~$20/month
PostgreSQL: Free (self-hosted) or ~$15/month (managed)
Redis: Free (self-hosted) or ~$10/month (managed) Total: ~$45/month vs ~$500+/month for third-party APIs at scale.

Q: What about LLM costs?

A: LLM enhancement is optional. If enabled:

OpenAI GPT-4: ~$0.03 per 1K tokens (~$0.0015 per validation)
Anthropic Claude: ~$0.015 per 1K tokens (~$0.0008 per validation)
Azure OpenAI: Similar pricing with enterprise SLAs

Most users run without LLM for 95% of validations (LanguageTool is free and fast).

Q: How accurate is it?

LanguageTool base: ~85% precision on grammar/spelling
With LLM enhancement: ~95% precision on context and style
Language detection: ~99.9% accuracy (using fasttext models)

Q: Can I contribute even if I'm a beginner?

A: Yes! We have "good first issue" labels for beginner-friendly tasks. Documentation improvements, tests, and examples are always welcome.

Q: What if I need help?

📧 Email: vivekjaiswal994@gmail.com
💬 GitHub Discussions: Ask questions
🐛 GitHub Issues: Report bugs

Tech Stack Summary

Backend Framework: FastAPI (Python 3.12+)

Database: PostgreSQL 15+ with SQLAlchemy ORM

Cache: Redis 7+ for multi-layer caching

Grammar Engine: LanguageTool (27+ languages)

PII Detection: Microsoft Presidio

Language Detection: fasttext + lingua-language-detector

LLM Integration: OpenAI, Anthropic, Azure OpenAI

Validation: Pydantic v2 with type safety

Migrations: Alembic

ASGI Server: Uvicorn with auto-reload

Testing: pytest with 80%+ coverage

Code Quality: mypy, ruff, black, isort

Logging: structlog with JSON formatting

Conclusion

Building a production-grade API is about more than just "making it work." It's about:

Architecture: Choosing patterns that scale and are maintainable
Performance: Optimizing hot paths and implementing intelligent caching
Reliability: Handling failures gracefully and building resilience
Security: Protecting user data and preventing abuse
Developer Experience: Great documentation and intuitive APIs
Community: Building something others want to use and contribute to

The Grammar API represents 6 months of development, countless iterations, and a deep dive into NLP, AI/ML, and distributed systems. I'm excited to share it with the developer community.

What's Next?

Try it out: Clone the repo and run it locally
Give feedback: Open an issue or start a discussion
Contribute: Pick a "good first issue" and submit a PR
Spread the word: Star the repo and share with your network

Connect With Me

I'm Vivek Jaiswal, Founder & Technology Director at QBits Marketing Research, specializing in AI/ML, Cloud Architecture, and LLM Integration.

🌐 Website: vivekjaiswal.ai
📧 Email: vivekjaiswal994@gmail.com
💼 LinkedIn: in/vivekjaiswal-ai
🐦 Twitter: @vivekjaiswal_ai
💻 GitHub: @vivekjaiswal-ai

If you're working on AI/ML projects, building LLM applications, or need help with cloud architecture, I'd love to connect!

Resources

GitHub Repository: github.com/vivekjaiswal-ai/grammar-api
Full Documentation: Getting Started Guide
API Reference: API Documentation
Contributing Guide: How to Contribute
Changelog: Version History

If you found this useful, please:

⭐ Star the GitHub repository
👏 Clap for this article on Medium
💬 Leave a comment with your thoughts
🔄 Share with your network

Thank you for reading! 🙏

Building in public and sharing knowledge is what makes the developer community amazing. Let's build something great together.

Published: October 31, 2025

Tags: #AI #MachineLearning #NLP #FastAPI #Python #OpenSource #LLM #API #CloudComputing #SoftwareArchitecture

P.S.: If you're building an application that needs grammar checking, spell checking, or text validation - give this API a try. It's free, open source, and production-ready. And if you need custom features or enterprise support, reach out - I'm always happy to help! 🚀

DEV Community: Vivek Jaiswal