Skip to content

README.md

Latest commit

 

History

History
315 lines (233 loc) · 8.34 KB

README.md

File metadata and controls

315 lines (233 loc) · 8.34 KB
Raw

Agentic AI System

A production-ready AI chat system built with FastAPI, LangGraph, and LangChain. Features conversational AI with contextual memory, Google OAuth authentication, and LangSmith tracing for observability.

Features

  • LangGraph-Powered Chat Agent - Conversational AI with tool-calling capabilities
  • Contextual Memory - MCP (Model Context Protocol) integration for persistent memory across conversations
  • Google OAuth Authentication - Secure user authentication with Google
  • Conversation Management - Persistent chat history with PostgreSQL
  • LangSmith Tracing - Full observability and monitoring of AI interactions
  • Auto-Discovery Architecture - Routes and middlewares automatically loaded
  • Database Migrations - Laravel-style Alembic migrations

Prerequisites

  • Python 3.10+
  • PostgreSQL database
  • Poetry for dependency management: 
    curl -sSL https://install.python-poetry.org | python3 -
  • OpenAI API Key (or other supported LLM provider)

Project Structure

.
├── app/
│   ├── main.py                     # FastAPI application entry point
│   ├── agentic/
│   │   ├── agents/                 # Agent implementations
│   │   │   └── chat_agent.py       # Chat agent logic
│   │   ├── graphs/                 # LangGraph workflow definitions
│   │   │   └── chat_agent_graph.py # Chat agent graph with tool nodes
│   │   └── states/                 # Agent state definitions
│   │       └── chat_agent_state.py # Chat agent state schema
│   ├── bootstrap/
│   │   ├── middlewares.py          # Auto-loads middlewares
│   │   └── routers.py              # Auto-loads routes
│   ├── config/
│   │   ├── app.py                  # Application configuration
│   │   ├── database.py             # Database configuration
│   │   ├── google.py               # Google OAuth configuration
│   │   ├── keycloak.py             # Keycloak configuration
│   │   ├── lang_smith.py           # LangSmith tracing configuration
│   │   └── mcp_config.py           # MCP server configuration
│   ├── controllers/
│   │   ├── auth_controller.py      # Authentication controller
│   │   ├── chat_controller.py      # Chat endpoint controller
│   │   └── conversation_controller.py # Conversation management
│   ├── middlewares/
│   │   ├── cors.py                 # CORS middleware
│   │   └── database.py             # Database session middleware
│   ├── models/
│   │   ├── user.py                 # User model
│   │   ├── conversation.py         # Conversation model
│   │   └── conversation_message.py # Message model
│   ├── prompts/
│   │   └── chat.md                 # Chat agent system prompt
│   ├── routes/
│   │   ├── api.py                  # API routes (chat, conversations)
│   │   └── auth.py                 # Authentication routes
│   ├── services/
│   │   ├── auth_service.py         # Google OAuth service
│   │   └── chat_service.py         # Chat processing service
│   └── utils/
│       ├── auth/                   # Authentication utilities
│       ├── helpers.py              # Helper functions (MCP tools, prompts)
│       ├── lang_smith_tracing.py   # LangSmith decorators
│       └── mcp_auth.py             # MCP authentication
├── database/
│   ├── connection.py               # Database connection setup
│   └── migrations/
│       └── versions/               # Alembic migration files
├── migrate.py                      # Migration CLI tool
├── run.py                          # Application runner
└── pyproject.toml                  # Poetry configuration

Getting Started

1. Clone the repository

git clone <your-repo-url>
cd agentic-ai-system

2. Install dependencies

poetry install

3. Configure environment variables

cp .env.example .env

Edit .env with your settings:

# Application
APP_PORT=8000
DEBUG=true

# Database (PostgreSQL)
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=agentic_ai
DB_USERNAME=postgres
DB_PASSWORD=postgres

# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:8000/auth/google/callback

# JWT Authentication
JWT_SECRET_KEY=your-secret-key-change-in-production
JWT_EXPIRATION_HOURS=24

# LLM Provider
OPENAI_API_KEY=your-openai-api-key

# LangSmith Tracing (optional)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your-langchain-api-key
LANGCHAIN_PROJECT="Agentic AI System"

# MCP Memory Server (optional)
MEMORY_MCP_URL=http://127.0.0.1:5002/mcp/

4. Set up the database

# Run migrations
python migrate.py

# Or fresh install (drops all tables first)
python migrate.py fresh

5. Run the application

Development mode (with hot-reload):

poetry run dev

Production mode:

poetry run start

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

API Documentation

Once the server is running:

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc

Key Endpoints

Method Endpoint Description
GET /auth/google/login Initiate Google OAuth login
GET /auth/google/callback OAuth callback handler
GET /api/user/profile Get authenticated user profile
POST /api/chat Send message to chat agent
GET /api/conversations List user conversations
GET /api/conversations/{id} Get conversation details
DELETE /api/conversations/{id} Delete a conversation

Database Migrations

Laravel-style migration commands:

# Run pending migrations
python migrate.py

# Drop all tables and re-run migrations
python migrate.py fresh

# Rollback last migration
python migrate.py rollback

# Show migration status
python migrate.py status

# Rollback all migrations
python migrate.py reset

Adding New Features

Adding a new route

Create a file in app/routes/ with a route_config and router:

from fastapi import APIRouter

route_config = {
    "prefix": "/users",
    "tags": ["Users"]
}

router = APIRouter()

@router.get("/")
def get_users():
    return {"users": []}

Routes are automatically discovered and registered.

Adding a new middleware

Create a file in app/middlewares/ with a setup function:

from fastapi import FastAPI

def setup(app: FastAPI):
    # Your middleware logic
    pass

Adding LangSmith tracing to services

Use the @trace_service decorator:

from app.utils.lang_smith_tracing import trace_service

class MyService:
    @trace_service("my_service", operation="my_operation", tags=["custom"])
    async def my_method(self):
        pass

Dependencies

Key dependencies:

  • FastAPI - Web framework
  • LangGraph - Agent workflow orchestration
  • LangChain - LLM integration framework
  • LangChain-MCP-Adapters - MCP protocol integration
  • SQLAlchemy - ORM for database operations
  • Alembic - Database migrations
  • LangSmith - Tracing and monitoring
  • python-jose - JWT token handling
  • google-auth-oauthlib - Google OAuth

Key Files

Security Notes

  • Generate a secure JWT_SECRET_KEY: openssl rand -hex 32
  • Update CORS origins in app/middlewares/cors.py for production
  • Never commit .env files with real credentials
  • Use environment-specific configurations for production

License

This project is open source and available under the MIT License.

Author

Tofayel Hyder Abhi

Contributing

Contributions, issues, and feature requests are welcome!