Apache Maka API Documentation: Complete Guide to Public Interfaces and Runtime Usage

Yes, Apache Maka exposes a stable public API through the @maka/runtime package, with SessionManager serving as the main façade for session management and turn orchestration, while internal implementations remain free to evolve behind the public seam.

Apache Maka organizes its TypeScript codebase around a stable public seam that protects consumers from internal refactoring. The official Apache Maka API documentation is distributed across architecture guides, package READMEs, and source code barrels that explicitly define supported entry points. All public interfaces are re-exported through root index files, allowing developers to interact with the system without knowledge of internal file layouts.

Public API Entry Points

The @maka/runtime package serves as the primary interface for Apache Maka consumers. According to the source code, the package explicitly declares its public API through barrel exports in packages/runtime/src/index.ts, while keeping implementation details in sub-directories.

SessionManager Facade

The SessionManager class in packages/runtime/src/session-manager.ts acts as the central façade for all runtime interactions. This class provides external APIs for creating sessions, sending messages, and managing turn orchestration. Consumers instantiate this class directly to control the conversation lifecycle.

BackendRegistry and AgentBackend

The BackendRegistry (located in packages/runtime/src/backend-registry.ts) implements a registry pattern for plugging in model backends. Developers can register custom implementations of the AgentBackend interface to support different AI providers or testing mocks. The default production implementation, AiSdkBackend, resides in packages/runtime/src/ai-sdk-backend.ts and handles communication with external model providers.

RuntimeKernel and Built-in Tools

The RuntimeKernel in packages/runtime/src/runtime-kernel.ts manages the core orchestration layer that runs individual turns and coordinates events. For tool access, the buildBuiltinTools() factory function in packages/runtime/src/builtin-tools.ts creates the standard tool suite including web-search and file-access capabilities. The WorkspaceExecutor in packages/runtime/src/workspace-executor.ts abstracts filesystem and shell side-effects for these tools.

UI Components via @maka/ui

The @maka/ui package exports a stable component library through its barrel at packages/ui/src/index.ts. Only components explicitly included in this index file are part of the public API, ensuring backward compatibility for UI integrations.

Where to Find Official Documentation

Apache Maka distributes its API documentation across several markdown files in the repository rather than a single hosted site.

Architecture Overview

The ARCHITECTURE.md file at the repository root provides a high-level component diagram showing how SessionManager functions as the public entry point. This document defines the conceptual boundaries between public APIs and internal implementation details.

Package READMEs

The packages/runtime/README.md explicitly states which exports constitute the supported public API and which sub-paths are considered internal. This file serves as the contract for semantic versioning guarantees.

Technical Walkthroughs

The docs/archive/maka-core-tech-walkthrough.md contains a detailed walkthrough of the public API surface, explaining the relationship between SessionManager and the internal kernel. This document demonstrates how the public façade delegates to RuntimeKernel for turn execution.

Practical Usage Examples

The following examples demonstrate how to interact with the Apache Maka API using the public exports from @maka/runtime and @maka/ui.

Creating Sessions and Sending Messages

To begin using the runtime, import SessionManager and BackendRegistry from the package barrel:

import { SessionManager, BackendRegistry, AiSdkBackend } from '@maka/runtime';

// Register the default AI SDK backend (e.g., OpenAI)
BackendRegistry.register('openai', new AiSdkBackend({
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY!,
}));

// Instantiate the public façade
const manager = new SessionManager({});

// Create a new session
const sessionId = await manager.createSession({ name: 'demo-session' });

// Send a user message; turn orchestration runs inside the runtime kernel
const response = await manager.sendMessage(sessionId, {
  role: 'user',
  content: 'What is the capital of France?'
});

console.log('Assistant reply:', response.content);

Key files referenced: SessionManager (packages/runtime/src/session-manager.ts), BackendRegistry (packages/runtime/src/backend-registry.ts), AiSdkBackend (packages/runtime/src/ai-sdk-backend.ts).

Registering Custom Backends

You can extend the system with custom backends by implementing the AgentBackend interface:

import { BackendRegistry, AgentBackend, SessionManager } from '@maka/runtime';

class MockBackend implements AgentBackend {
  async streamChat(_messages: unknown[]) {
    return { content: 'Mock answer', done: true };
  }
}

// Register under a custom name
BackendRegistry.register('mock', new MockBackend());

// Use the mock backend for a new session
const manager = new SessionManager();
await manager.setBackend('mock');
const sid = await manager.createSession();
const reply = await manager.sendMessage(sid, { role: 'user', content: 'Hello' });
console.log(reply.content); // → "Mock answer"

Key file: AgentBackend interface is defined in packages/runtime/src/types.ts and re-exported by the barrel.

Integrating UI Components

Import components from the @maka/ui barrel for use in React applications:

import { Button } from '@maka/ui';

export function MyApp() {
  return (
    <Button onClick={() => alert('Clicked!')}>
      Click me
    </Button>
  );
}

Only components exported through packages/ui/src/index.ts are part of the stable public API.

Summary

• Apache Maka exposes a stable public API through the @maka/runtime and @maka/ui packages, with all entry points re-exported through root barrel files.
• SessionManager in packages/runtime/src/session-manager.ts serves as the primary façade for session CRUD operations and message handling.
• BackendRegistry and the AgentBackend interface enable pluggable model backends, with AiSdkBackend provided as the default production implementation.
• Official documentation resides in ARCHITECTURE.md, packages/runtime/README.md, and docs/archive/maka-core-tech-walkthrough.md, which collectively define the public seam and usage patterns.
• The buildBuiltinTools() factory and WorkspaceExecutor provide standardized tool capabilities with abstracted side-effect management.

Frequently Asked Questions

Where is the Apache Maka API documentation hosted?

Apache Maka does not currently maintain a separate hosted documentation site. Instead, the official Apache Maka API documentation lives directly in the repository at ARCHITECTURE.md, packages/runtime/README.md, and the docs/ directory. These markdown files define the public API contract and provide architectural context.

What is the main entry point for the Apache Maka runtime API?

The SessionManager class exported from @maka/runtime serves as the main entry point. According to the source code in packages/runtime/src/session-manager.ts, this class provides the public façade for creating sessions, sending messages, and managing turn orchestration, while delegating execution to the internal RuntimeKernel.

How do I create a custom backend for Apache Maka?

Implement the AgentBackend interface from @maka/runtime, then register your implementation using BackendRegistry.register(). As implemented in packages/runtime/src/backend-registry.ts, this registry pattern allows you to plug in alternative model providers or testing mocks without modifying the core runtime code.

Are the UI components in @maka/ui part of the stable API?

Yes, but only components explicitly exported from packages/ui/src/index.ts are considered part of the stable public API. The package employs a barrel export pattern to ensure that internal component refactoring does not break consumer imports, making the index file the authoritative source for supported UI components.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}