narrative-ai-framework 0.1.9

AI-powered voice diary framework: STT, TTS, LLM, RAG, and voice-agent engines

Narrative AI SDK

---

🔑 LLM Engine (nai.llm)

Requirements:

• API Key from OpenAI, Google (Gemini), or Anthropic.
• Install dependencies: pip install narrative-ai-framework

generate()

Detailed Description	Inputs	Returns
The primary function for text generation. It abstracts the complexity of different providers, allowing you to generate text from a simple prompt. It handles model routing and response parsing automatically.	prompt (str), model (str, optional), max_tokens (int, optional)	LLMResponse (Object with .text property)

import narrative_ai as nai
import asyncio

async def main():
    # 1. Setup API Key
    nai.llm.set_api_key("your-api-key", provider="openai")
    
    # 2. Call generate
    response = await nai.llm.generate("Explain black holes in simple terms.")
    print(f"Result: {response.text}")

if __name__ == "__main__":
    asyncio.run(main())

generate_stream()

Detailed Description	Inputs	Returns
Generates text response chunk-by-chunk. This is essential for building real-time chat applications where you want to show the AI's output as it's being thought of.	prompt (str), model (str, optional)	AsyncIterator[str]

import narrative_ai as nai
import asyncio

async def main():
    nai.llm.set_api_key("your-api-key", provider="openai")
    
    print("Streaming: ", end="")
    async for chunk in nai.llm.generate_stream("Write a short poem."):
        print(chunk, end="", flush=True)

if __name__ == "__main__":
    asyncio.run(main())

---

🎙️ STT Engine (nai.stt)

Requirements:

• API Key for cloud providers (ElevenLabs) OR local hardware for Whisper.
• Install extra dependencies: pip install "narrative-ai-framework[stt]"

transcribe()

Detailed Description	Inputs	Returns
Converts an entire audio file (MP3, WAV, etc.) into structured text. It handles audio normalization and sends it to the configured transcription engine.	audio_path (str), language (str, optional)	STTResult (Object with .text property)

import narrative_ai as nai
import asyncio

async def main():
    # 1. Configure provider
    nai.stt.set_api_key("your-elevenlabs-key", provider="elevenlabs")
    
    # 2. Transcribe file
    result = await nai.stt.transcribe("meeting_recording.mp3")
    print(f"Transcript: {result.text}")

if __name__ == "__main__":
    asyncio.run(main())

---

🔊 TTS Engine (nai.tts)

Requirements:

• API Key for providers (OpenAI, ElevenLabs).
• Install extra dependencies: pip install "narrative-ai-framework[tts]"

synthesize()

Detailed Description	Inputs	Returns
Converts text into realistic speech. It returns the local file path to the generated audio file. You can specify different voices depending on the provider.	text (str), voice (str, optional)	str (Absolute path to the audio file)

import narrative_ai as nai
import asyncio

async def main():
    # 1. Setup TTS
    nai.tts.set_api_key("your-openai-key", provider="openai")
    
    # 2. Generate Audio
    audio_path = await nai.tts.synthesize("Hello, welcome to Narrative AI.", voice="alloy")
    print(f"Audio saved at: {audio_path}")

if __name__ == "__main__":
    asyncio.run(main())

---

📚 RAG & Memory (nai.rag)

Requirements:

• Vector Database access (Pinecone, Qdrant) OR Local storage.
• API Key for Embeddings (OpenAI, Cohere).

remember()

Detailed Description	Inputs	Returns
Indexes a StructuredDocument into your vector store. It automatically generates embeddings and stores the content so the AI can 'recall' it later.	document (StructuredDocument), doc_id (str, optional)	bool (True if indexing succeeded)

import narrative_ai as nai
import asyncio

async def main():
    # 1. Setup Embeddings
    nai.rag.set_api_key("your-cohere-key", provider="cohere")
    
    # 2. Process a file first
    doc = await nai.input_processor.process("knowledge_base.pdf")
    
    # 3. Store in memory
    success = await nai.rag.remember(doc, doc_id="kb_v1")
    print(f"Document indexed: {success}")

if __name__ == "__main__":
    asyncio.run(main())

recall()

Detailed Description	Inputs	Returns
Searches your long-term memory for relevant information based on a query. It returns the most similar text blocks to be used as context for the LLM.	query (str), top_k (int, default=5)	RichContext (Object containing relevant snippets)

import narrative_ai as nai
import asyncio

async def main():
    nai.rag.set_api_key("your-key", provider="cohere")
    
    # Search memory
    context = await nai.rag.recall("What is the company's leave policy?")
    print(f"Retrieved Context: {context.formatted_text}")

if __name__ == "__main__":
    asyncio.run(main())

---

🛠️ Input Processor (nai.input_processor)

Requirements:

• No special keys needed, but depends on other engines (OCR, STT) for specific file types.

process()

Detailed Description	Inputs	Returns
The multimodal 'brain'. It analyzes the file extension or metadata of any source and automatically routes it to OCR (for images/PDFs) or STT (for audio).	source (Path, URL, or Bytes)	StructuredDocument

import narrative_ai as nai
import asyncio

async def main():
    # One function for any file type!
    doc = await nai.input_processor.process("complex_data.zip")
    print(f"Extracted {len(doc.content_blocks)} blocks of information.")

if __name__ == "__main__":
    asyncio.run(main())

---

🤖 Voice Mode (nai.voice_mode)

Requirements:

• LiveKit Server URL and API Credentials.

start_agent()

Detailed Description	Inputs	Returns
Launches the real-time agent worker. This connects your LLM, STT, and TTS engines into a seamless low-latency voice conversation loop.	None	None (Runs indefinitely)

import narrative_ai as nai

# 1. Configure LiveKit
nai.voice_mode.set_livekit_config(
    url="wss://your-project.livekit.cloud",
    api_key="your-api-key",
    api_secret="your-api-secret"
)

# 2. Set Agent Identity
nai.voice_mode.set_agent_name("Narrative Assistant")

# 3. Start the loop
# nai.voice_mode.start_agent()

---

🎨 VLM Engine (nai.vlm)

Requirements:

• Vision-capable model key (Gemini Pro Vision, GPT-4V).

analyze_image()

Detailed Description	Inputs	Returns
Allows the AI to 'see'. You pass an image and a prompt, and the engine performs visual reasoning to answer your question.	image (Path or Bytes), prompt (str)	VLMResponse

import narrative_ai as nai
import asyncio

async def main():
    nai.vlm.set_api_key("your-key")
    response = await nai.vlm.analyze_image("chart.png", "What are the sales trends in this graph?")
    print(response.text)

if __name__ == "__main__":
    asyncio.run(main())

---

License

MIT License.