API Documentation:
Parrot-Chat Endpoint

https://calvinistparrot.com/api/parrot-chat

The Parrot Chat endpoint provides real-time conversational interactions by streaming responses. It handles creating chat sessions, processing user messages, maintaining context, and integrating multiple theological agents including a final review stage ("Calvin's Review"). Essential doctrines are upheld, including:

• The Trinity: We believe in one God, eternally existing in three persons—Father, Son, and Holy Spirit.
• The Character of God: God is holy, supreme, sovereign, immutable, faithful, good, patient, gracious, merciful, loving, and just; His wrath against sin is real.
• The Authority of Scripture: The Bible is the inspired, inerrant, and infallible Word of God, serving as the ultimate authority in all matters of faith and practice.
• The Deity and Humanity of Christ: We affirm that Jesus Christ is truly God and truly man (Vera Deus, vera homo).
• The Incarnation and Virgin Birth: We affirm that Jesus Christ took on human nature through miraculous conception by the Holy Spirit and was born of the Virgin Mary.
• The Atonement (Christ's Saving Work): Christ's sacrificial death on the cross is necessary and sufficient to reconcile sinners to God.
• The Gospel: We proclaim that salvation is secured by Christ's historical death, burial, and resurrection on the third day, demonstrating His victory over sin and death.
• Justification by Faith: Individuals are justified solely by grace alone through faith alone in Christ alone, apart from works.
• The Resurrection: We affirm the bodily resurrection of Jesus Christ, confirming His divinity and victory over sin and death.
• Christ's Return and Final Judgment: Jesus Christ will return personally and bodily to judge the living and the dead, culminating in the renewal of all things.

1. Chat Session Initialization

   There are two ways to start a new chat:

   • From Parrot QA: Initialize with both question and answer
   • From Chat Interface: Initialize with just a question

2. Chat Continuation

   • Uses stored chat history to maintain context
   • Processes messages through multiple agents and tools
   • Streams real-time responses with progress updates

3. Denomination Handling

   • Each denomination maps to a specific system prompt
   • Affects how the AI interprets and responds to questions
   • Maintains core doctrinal consistency while respecting denominational distinctives

Request Structure

Send a JSON payload with these possible fields:

• userId (string): Unique identifier for the user.
• chatId (string, optional): Identifier for an existing chat session.
• message (string): The user's chat message.
• initialQuestion (string, optional): For starting a new chat session.
• initialAnswer (string, optional): Initial answer for a new chat session.
• denomination (string, optional): The theological perspective. Possible values:
  • reformed-baptist (Reformed Baptist perspective - default)
  • presbyterian (Presbyterian perspective)
  • wesleyan (Wesleyan perspective)
  • lutheran (Lutheran perspective)
  • anglican (Anglican perspective)
  • pentecostal (Pentecostal/Charismatic perspective)
  • non-denom (Non-Denominational Evangelical perspective)
• isAutoTrigger (boolean, optional): Indicates if the message is auto-triggered (for conversation continuity).

Response Stream Format

The API streams different event types as JSON objects:

1. Progress Updates - Status messages during processing

   {"type": "progress", "title": "Looking for articles", "content": "Searching for: predestination"}

2. Parrot Messages - Main response content (streamed in chunks)

   {"type": "parrot", "content": "The doctrine of predestination..."}

3. Calvin's Review - Theological review feedback

   {"type": "calvin", "content": "This explanation aligns with Reformed theology..."}

4. Reference Materials - Related articles and resources

   {"type": "gotQuestions", "content": "* [What is predestination?](https://www.gotquestions.org/predestination.html)"}

5. Stream Completion

   {"type": "done"}

1. Initialize from Parrot QA

POST /api/parrot-chat
{
  "userId": "user123",
  "initialQuestion": "What is predestination?",
  "initialAnswer": "Predestination refers to...",
  "denomination": "reformed-baptist"
}

2. Initialize from Chat Interface

POST /api/parrot-chat
{
  "userId": "user123",
  "initialQuestion": "What is predestination?"
}

Response:

{
  "chatId": "chat123"
}

Complete Flow Example

1. Start a new chat and get the chatId:

   // In main-chat/page.tsx
   const handleStartNewChat = async () => {
     const response = await fetch('/api/parrot-chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ 
       userId: "user123", 
       initialQuestion: "What is predestination?" 
      }),
     });
     const { chatId } = await response.json();
     router.push(`/main-chat/${chatId}`);  // Navigate to chat page
   };

2. Chat page loads and auto-triggers the initial question:

   // In main-chat/[chatId]/page.tsx
   useEffect(() => {
     // When we detect only a user message with no response yet
     if (messages.length === 1 && messages[0].sender === "user" && !autoSentRef.current) {
      autoSentRef.current = true;
      // Auto-trigger the API call with the isAutoTrigger flag
      handleSendMessage({ 
       message: messages[0].content, 
       isAutoTrigger: true 
      });
     }
   }, [messages, handleSendMessage]);
   
   // Actual API call with isAutoTrigger flag
   const handleSendMessage = async ({ message, isAutoTrigger }) => {
     const response = await fetch("/api/parrot-chat", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
       chatId: "chat123",  // From URL params
       message: "What is predestination?",  // Initial question
       isAutoTrigger: true  // This tells the API not to store the message again
      }),
     });
     
     // Handle streaming response...
   };

3. API processes the request differently with isAutoTrigger:
   • When isAutoTrigger: true, the API doesn't save the message again (it's already stored)
   • The API processes the message and streams the response
   • The client receives and displays the streaming response

3. Continue Conversation

POST /api/parrot-chat
{
  "userId": "user123",
  "chatId": "chat123",
  "message": "How does it relate to free will?"
}

4. Fetch Chat History

GET /api/parrot-chat?chatId=chat123

Response:

{
  "chat": {
   "id": "cm7p6rik1001emqp0slgxgu1j",
   "userId": "6754db6b00119ba9e0da",
   "conversationName": "Understanding Predestination",
   "denomination": "reformed-baptist",
   "createdAt": "2025-02-28T19:48:22.321Z",
   "modifiedAt": "2025-02-28T19:48:45.855Z"
  },
  "messages": [
   {
    "id": "cm7p6rimi001gmqp0liuisq27",
    "chatId": "cm7p6rik1001emqp0slgxgu1j",
    "sender": "user",
    "content": "What is predestination?",
    "timestamp": "2025-02-28T19:48:22.410Z"
   },
   {
    "id": "cm7p6rqc0001imqp0h9gywt2x",
    "chatId": "cm7p6rik1001emqp0slgxgu1j",
    "sender": "gotQuestions",
    "content": "* [Providence and Predestination - Monergism](https://www.monergism.com/reformation-theology/blog/providence-and-predestination)\n* [What is predestination? - GotQuestions.org](https://www.gotquestions.org/predestination.html)\n* [Predestination and the Work of Jesus Considered | Monergism](https://www.monergism.com/predestination-and-work-jesus-considered)\n* [What is Predestination? - Monergism](https://www.monergism.com/what-predestination)\n* [What does the Bible say about predestination vs. free will?](https://www.gotquestions.org/predestination-vs-free-will.html)",
    "timestamp": "2025-02-28T19:48:32.401Z"
   },
   {
    "id": "cm7p6rxq0001kmqp0kdxt3qvt",
    "chatId": "cm7p6rik1001emqp0slgxgu1j",
    "sender": "calvin",
    "content": "Your summary of predestination captures...",
    "timestamp": "2025-02-28T19:48:41.938Z"
   },
   {
    "id": "cm7p6rzqs001mmqp0jrawhfi1",
    "chatId": "cm7p6rik1001emqp0slgxgu1j",
    "sender": "parrot",
    "content": "Predestination is...",
    "timestamp": "2025-02-28T19:48:44.596Z"
   }
  ]
}

Front-end Integration Example

const handleStream = async (chatId: string, message: string) => {
  const response = await fetch('/api/parrot-chat', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({ chatId, message })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
   const { value, done } = await reader.read();
   if (done) break;
   
   const lines = decoder.decode(value).split('\n');
   for (const line of lines) {
    if (!line.trim()) continue;
    
    const event = JSON.parse(line);
    switch (event.type) {
      case 'progress':
       updateProgress(event.title, event.content);
       break;
      case 'parrot':
       appendParrotMessage(event.content);
       break;
      case 'calvin':
       showCalvinReview(event.content);
       break;
      case 'gotQuestions':
       showReferences(event.content);
       break;
      case 'done':
       finishStream();
       break;
    }
   }
  }
};

For complete implementation examples, see:

• Main Chat Page
• Chat Session Page

The endpoint supports the following denomination:

1. Reformed Baptist (default)
2. Presbyterian
3. Wesleyan
4. Lutheran
5. Anglican
6. Pentecostal/Charismatic
7. Non-Denominational Evangelical

Each mode tailors its responses according to distinct theological perspectives on secondary issues while sharing a common foundation on core doctrines.

Reformed Baptist

• Baptism: You practice believer's baptism (credo baptism) by immersion, viewing it as an outward sign of inward grace.
• Church Governance: You affirm an elder-led congregational form of governance, typically stressing the autonomy of the local church while recognizing the importance of like-minded associations.
• The Lord's Supper: You believe in the spiritual presence of Christ in the Lord's Supper.
• Spiritual Gifts: You believe in the cessation of spiritual gifts. Believing the miraculous gifts ceased with the apostles, though a minority might be cautious continuationists
• Role of Women in the Church: You adhere to complementarianism.
• Views on Sanctification: You emphasize progressive sanctification by the Holy Spirit, rooted in God’s grace and empowered by the means of grace (Word, prayer, fellowship).
• Continuity and Discontinuity: You hold to covenant theology (sometimes called “1689 Federalism”), seeing continuity between Old and New Covenants while distinguishing the “newness” in Christ.
• Security of Salvation: You believe in the perseverance of the saints—those truly in Christ will be kept by God’s power and not finally fall away.
• The Atonement (How it Works): You hold strongly to penal substitutionary atonement, often emphasizing particular redemption (also called “limited atonement”).

For further questions or support, please reach out!

This is open source, so if you're interested in helping me development this, check out the GitHub repo.