DEV Community

Vivek Jaiswal
Vivek Jaiswal

Posted on

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

#api #architecture #ai #opensource

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

Grammar API Banner

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

  1. Grammar Agent - Powered by LanguageTool, handles rule-based grammar validation
  2. Semantic Agent - Uses LLMs (GPT-4, Claude, Azure OpenAI) for context understanding
  3. Style Agent - Analyzes writing style and provides improvement suggestions
  4. Linguistic Agent - Advanced language detection with ML models
  5. 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
Enter fullscreen mode Exit fullscreen mode

🧠 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"
}
Enter fullscreen mode Exit fullscreen mode

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"
    }
}
Enter fullscreen mode Exit fullscreen mode

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:

  1. In-Memory Cache (Redis) - Sub-millisecond response times
  2. Pattern Cache - Learns from common corrections
  3. Session Cache - User-specific patterns and preferences 
# First request: ~250ms (LanguageTool processing)
# Cached request: ~5ms (Redis cache hit)
Enter fullscreen mode Exit fullscreen mode

📊 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"
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Benefits:

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

Performance Optimizations

  1. Connection Pooling: Reusable database and Redis connections
  2. Async/Await: Non-blocking I/O for all operations
  3. Singleton Pattern: Single LanguageTool instance per language
  4. 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"
}
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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();
}
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

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()
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
  }'
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests (we maintain 80%+ coverage)
  5. 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?

A:

  • 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?

A:

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?

  1. Try it out: Clone the repo and run it locally
  2. Give feedback: Open an issue or start a discussion
  3. Contribute: Pick a "good first issue" and submit a PR
  4. 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.

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

Resources

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! 🚀

Top comments (0)