POST /api/v1/chat

{
  "question": "How does the authentication system work?",
  "repository": "repo_abc123",
  "session_id": "session_xyz"  // optional, for multi-turn conversations
}

{
  "answer": {
    "text": "The authentication system uses JWT tokens. When a user logs in via the SessionsController#create action, their credentials are verified against the User model. If valid, a JWT token is generated using the JwtService and returned to the client...",
    "confidence": 0.92
  },
  "references": [
    {
      "file_path": "app/controllers/sessions_controller.rb",
      "line_start": 15,
      "line_end": 28,
      "snippet": "def create\n  user = User.find_by(email: params[:email])..."
    },
    {
      "file_path": "app/services/jwt_service.rb",
      "line_start": 5,
      "line_end": 15,
      "snippet": "def self.encode(payload)\n  JWT.encode(payload, secret_key)..."
    }
  ],
  "session_id": "session_xyz789"
}

POST /api/v1/chat/sessions

{
  "repository": "repo_abc123",
  "context": "Exploring the payment system"
}

{
  "session_id": "session_xyz789",
  "repository": "repo_abc123",
  "created_at": "2024-01-15T10:30:00Z"
}

GET /api/v1/chat/sessions/:id

{
  "session_id": "session_xyz789",
  "repository": "repo_abc123",
  "messages": [
    {
      "role": "user",
      "content": "How does payment processing work?",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Payment processing is handled by the PaymentService...",
      "references": [...],
      "timestamp": "2024-01-15T10:30:02Z"
    }
  ]
}

POST /api/v1/explain

{
  "repository": "repo_abc123",
  "file": "app/services/payment_service.rb",
  "lines": {
    "start": 15,
    "end": 45
  }
}

{
  "explanation": {
    "summary": "This method processes a payment through Stripe and records the transaction.",
    "steps": [
      "1. Validates the payment amount is positive",
      "2. Creates a Stripe PaymentIntent with the amount and currency",
      "3. Confirms the payment using the provided payment method",
      "4. Creates a Transaction record in the database",
      "5. Returns the transaction or raises PaymentError on failure"
    ],
    "inputs": [
      { "name": "amount", "type": "Integer", "description": "Amount in cents" },
      { "name": "currency", "type": "String", "description": "ISO currency code" },
      { "name": "payment_method_id", "type": "String", "description": "Stripe payment method" }
    ],
    "outputs": {
      "success": "Transaction record",
      "failure": "Raises PaymentError"
    },
    "dependencies": [
      "Stripe gem",
      "Transaction model"
    ]
  }
}

POST /api/v1/generate-docs

{
  "repository": "repo_abc123",
  "file": "app/services/notification_service.rb"
}

{
  "documentation": {
    "overview": "NotificationService handles sending notifications across multiple channels...",
    "methods": [
      {
        "name": "send_email",
        "description": "Sends an email notification to a user",
        "parameters": [...],
        "examples": [...]
      }
    ],
    "usage_examples": [
      "NotificationService.new(user).send_email(:welcome)"
    ]
  }
}