lemura

A provider-agnostic, premium agentic AI runtime for the modern web.

lemura is a robust, provider-agnostic npm package designed to encapsulate a full agentic AI runtime. It simplifies the complex orchestration of LLMs, tools, and context management into a single, cohesive interface.

❓ Why lemura?

• Zero Lock-in: Switch between OpenAI, Anthropic, Groq, or local Ollama instances by changing one line of code.
• Production Ready: Built-in context compression, tool retry logic, and execution budget enforcement.
• Developer First: Premium logging, native TypeScript types, and Model Context Protocol (MCP) support.

✨ Key Features

• 🧠 Dynamic Skill Market: Switch skills on/off at runtime via tags, names, or tool dependencies.
• 🔌 Native MCP Support: Connect to any Model Context Protocol server with custom header support (Auth).
• 🛡️ Tool Firewall: Fully integrated ask/accept/deny policy layer for secure tool execution.
• 🎯 Goal Maintenance: LLM-powered sub-goal decomposition and status tracking across turns.
• 🧹 Summary Injection: Automatically compresses history while ensuring the model never "forgets" the context.
• 🌊 Native Streaming: Token-by-token completion for smooth, responsive user experiences.
• 📊 Observability: Detailed tracing, token tracking, and structured logging with actionable hints.

🚀 Install

pnpm add lemura
# or
npm install lemura

⚙️ Environment Variables

The built-in OpenAICompatibleAdapter can be configured using environment variables. To load them from a .env file in Node.js, you'll typically need a library like dotenv:

npm install dotenv

Then at the very top of your entry point:

import 'dotenv/config';

Create a .env file in your project root:

# Provider Configuration (OpenAI, Groq, Together, Ollama, etc.)
LEMURA_API_KEY=your_api_key_here
LEMURA_BASE_URL=https://api.openai.com/v1
LEMURA_MODEL=gpt-4o-mini

# Fallbacks (Lemura also checks standard OpenAI variables)
OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

⚡ Quick Start

import { SessionManager, OpenAICompatibleAdapter } from 'lemura';

async function main() {
  const adapter = new OpenAICompatibleAdapter({
    baseUrl: 'https://api.openai.com/v1',
    apiKey: process.env.OPENAI_API_KEY || '',
    defaultModel: 'gpt-4o-mini'
  });

  const session = new SessionManager({
    adapter,
    model: 'gpt-4o-mini',
    maxTokens: 100000,
  });

  const response = await session.run('What is lemura?');
  console.log(response);

  // Or stream the final response token-by-token
  for await (const token of session.stream('What is lemura?')) {
    process.stdout.write(token);
  }
}

main();

🛠️ Quick Start: Creating a Tool

Adding tools to your agent is straightforward using the standard IToolDefinition interface.

import { IToolDefinition } from 'lemura';

const getWeather: IToolDefinition = {
  name: 'get_weather',
  description: 'Get the current weather for a specific city',
  parameters: {
    type: 'object',
    properties: {
      city: { type: 'string', description: 'The name of the city' }
    },
    required: ['city']
  },
  execute: async ({ city }) => {
    // Call your weather API here
    return `The weather in ${city} is sunny, 22°C.`;
  }
};

// Register it when creating the session
const session = new SessionManager({
  adapter,
  model: 'gpt-4o-mini',
  tools: [getWeather]
});

🧠 Core Concepts

Explore the architecture and advanced capabilities of lemura at lemura.makix.fr or browse the local guides:

• 🏁 Getting Started — Fundamental setup and concepts.
• 🧹 Context Management — Advanced compression strategies.
• 🔌 Adapters — Connecting to OpenAI, Groq, Anthropic, and more.
• 🛠️ Tools and Skills — Extending agent capabilities.
• 🎛️ Media Bridge — ASR, TTS, vision, and image generation.
• ⚡ Advanced Execution — Goal planning and continuation.

📦 API Overview

| Export | Description | |---|---| | SessionManager | The main entry point orchestrating the ReAct loop and tools. | | ContextManager | Manages the conversation history using compression strategies. | | OpenAICompatibleAdapter | Reference adapter for OpenAI, Groq, Together, etc. | | ToolRegistry | Registers and executes tools for the agent. | | SkillInjector | Loads and formats YAML/Markdown skills into system prompts. | | DefaultLogger | Colorized logger with Problem/Hints metadata support. |

🪵 Logging and Tracing

lemura features a premium, structured logging system designed for developer experience. It provides colorized output and actionable hints for errors.

import { SessionManager, DefaultLogger, LogLevel } from 'lemura';

const logger = new DefaultLogger();
logger.setLevel(LogLevel.DEBUG); // Set to show trace-level information

const session = new SessionManager({
  adapter,
  model: 'gpt-4o-mini',
  maxTokens: 100000,
  logger: logger // Inject the logger
});

When an error occurs (like an invalid API key), lemura provides beautiful, structured feedback:

2026-03-07T13:05:49.686Z [FATAL] Provider call failed: HTTP 401: Unauthorized
  PROBLEM: Authentication failed. The API key is invalid or missing.
  HINTS:
    - Ensure your API key is correctly configured in the adapter or environment variables.
    - Check if the API key has expired or been revoked.

🔌 Provider Adapters

lemura interacts with LLMs exclusively through the IProviderAdapter interface, ensuring zero lock-in.

| Adapter | Status | Description | |---|---|---| | OpenAICompatibleAdapter | ✅ Built-in | Wrapper for OpenAI and API-compatible endpoints. |

[!TIP] To write a custom adapter for another provider, see the Custom Adapter Recipe.

🤝 Contributing

We welcome contributions! Please read our Internal Rules and Documentation Guidelines before submitting a PR.

📄 License

Distributed under the MIT License. See LICENSE for more information.