LinkedIn Post Generator

An AI-powered tool that generates, refines, and optimizes LinkedIn posts using Google Gemini and LangGraph.

Features

• AI-Powered Generation: Generate 3 diverse LinkedIn post options from a single topic
• Iterative Refinement: Refine posts based on your feedback until perfect
• Session Management: Maintain state across multiple refinement iterations
• RESTful API: Clean, well-documented API endpoints
• Type-Safe: Full type annotations with Pydantic models
• Production-Ready: Comprehensive error handling, structured logging, and tests

Architecture

┌─────────────────┐
│   FastAPI App   │
│   (REST API)    │
└────────┬────────┘
         │
┌────────▼────────┐
│ Session Service │
│  (In-Memory)    │
└────────┬────────┘
         │
┌────────▼────────┐
│   LangGraph     │
│  State Machine  │
└────────┬────────┘
         │
┌────────▼────────┐
│  Gemini LLM     │
│   Provider      │
└─────────────────┘

Tech Stack

• Framework: FastAPI
• LLM Orchestration: LangGraph
• LLM Provider: Google Gemini 2.5 Pro
• Validation: Pydantic
• Testing: Pytest
• Linting: Ruff
• Package Manager: uv

Getting Started

Prerequisites

• Python 3.12+
• uv package manager
• Google Gemini API key

Installation

1. Clone the repository:

git clone https://github.com/yourusername/linkedin-agent.git
cd linkedin-agent

2. Set up the backend:

cd backend
uv sync --dev

3. Create a .env file in the backend directory:

GOOGLE_API_KEY=your_gemini_api_key_here
LOG_LEVEL=INFO

Running the Application

Development Mode

cd backend
uv run uvicorn src.main:app --reload

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

Using Docker

docker-compose up

• Backend API: http://localhost:8088
• Frontend: http://localhost:8090

API Documentation

Once running, visit:

• Swagger UI: http://localhost:8000/docs (development) or http://localhost:8088/docs (Docker)
• ReDoc: http://localhost:8000/redoc (development) or http://localhost:8088/redoc (Docker)

API Usage

1. Create a Session and Generate Posts

curl -X POST "http://localhost:8000/sessions" \
  -H "Content-Type: application/json" \
  -d '{"topic": "The importance of clean code in software development"}'

Response:

{
  "id": "uuid-here",
  "topic": "The importance of clean code in software development",
  "options": [
    {
      "id": "opt-1",
      "content": "Clean code is not just about making code work..."
    },
    {
      "id": "opt-2",
      "content": "Writing maintainable code is an investment..."
    },
    {
      "id": "opt-3",
      "content": "Code quality matters because..."
    }
  ],
  "selected_option_id": null,
  "final_post": null
}

2. Get Session Status

curl "http://localhost:8000/sessions/{session_id}"

3. Refine a Post

curl -X POST "http://localhost:8000/sessions/{session_id}/refine" \
  -H "Content-Type: application/json" \
  -d '{
    "option_id": "opt-1",
    "refinement_prompt": "Make it shorter and add an emoji"
  }'

4. Finalize a Post

curl -X POST "http://localhost:8000/sessions/{session_id}/finalize" \
  -H "Content-Type: application/json" \
  -d '{"option_id": "opt-2"}'

5. Delete a Session

curl -X DELETE "http://localhost:8000/sessions/{session_id}"

Development

Project Structure

backend/
├── src/
│   ├── api/
│   │   ├── routes/
│   │   │   ├── health.py         # Health check endpoint
│   │   │   └── generation.py     # Session management endpoints
│   │   └── error_handlers.py     # Global error handlers
│   ├── core/
│   │   ├── llm/
│   │   │   ├── base.py            # LLM provider interface
│   │   │   └── gemini.py          # Gemini implementation
│   │   ├── graph/
│   │   │   ├── state.py           # LangGraph state definition
│   │   │   ├── nodes.py           # Graph nodes (generate, refine, finalize)
│   │   │   └── builder.py         # Graph construction
│   │   ├── prompts/
│   │   │   └── templates.py       # Prompt templates
│   │   ├── exceptions.py          # Custom exceptions
│   │   └── logging.py             # Logging configuration
│   ├── models/
│   │   └── schemas.py             # Pydantic models
│   ├── services/
│   │   └── session.py             # Session storage service
│   ├── config.py                  # App configuration
│   └── main.py                    # FastAPI app
├── tests/
│   ├── test_session_service.py
│   ├── test_exceptions.py
│   └── test_api.py
├── pyproject.toml
├── pytest.ini
└── Dockerfile

Running Tests

cd backend
uv run pytest

With coverage report:

uv run pytest --cov=src --cov-report=html

Code Quality

# Lint with Ruff
uv run ruff check src/

# Format with Ruff
uv run ruff format src/

Error Handling

The API uses custom exceptions with proper HTTP status codes:

• 400 Bad Request: Invalid input (empty topic, invalid refinement)
• 404 Not Found: Session or option not found
• 503 Service Unavailable: LLM provider errors
• 500 Internal Server Error: Unexpected errors

All errors return JSON in this format:

{
  "error": "ErrorClassName",
  "message": "Human-readable error message",
  "path": "/api/endpoint"
}

Logging

Structured logging with key-value pairs:

timestamp=2025-12-27T10:30:45 level=INFO logger=src.api.routes.generation message=Creating session session_id=abc-123 topic=Clean code
timestamp=2025-12-27T10:30:47 level=INFO logger=src.api.routes.generation message=Session created successfully session_id=abc-123 duration_ms=2341 options_count=3

Configure log level via environment variable:

LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR

Roadmap

• Frontend (React/Next.js)
• Persistent storage (PostgreSQL/Redis)
• User authentication
• Rate limiting
• Multiple LLM provider support
• Post scheduling integration
• Analytics and metrics

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT

Acknowledgments

• Built with FastAPI
• Powered by Google Gemini
• Orchestrated with LangGraph