AI Integration Use Cases¶

Here is an overview of typical use cases where the Naftiko Fleet helps developers and platform teams deliver Spec-Driven Integration end-to-end — from authoring with Crafter, validating with Polychro, running with Ikanos, governing with Warden, and orchestrating across the estate with Skipper. Additional capabilities are being added as described in the Fleet roadmap, with component-level detail in the Ikanos roadmap and Polychro roadmap.

1. AI integration¶

Connect AI assistants to your systems through capabilities, so they can access trusted business data and actions without custom glue code.

How the Naftiko Fleet achieves this technically: - Declare upstream systems in capability.consumes (typically type: http) with namespace, baseUri, authentication, headers, and operation contracts — authored with Crafter and validated by Polychro. - Expose the same domain as type: mcp tools and/or type: api resources in capability.exposes, served at runtime by the Ikanos engine, so both AI agents and traditional clients use one integration layer. - Use call, with, steps, and JSONPath mapping in outputParameters to return normalized, task-ready payloads instead of raw provider responses.

Integrate AI

Key features¶

2. Rightsize AI context¶

Expose only the context an AI task needs, reducing noise, improving relevance, and keeping prompts efficient.

How the Naftiko Fleet achieves this technically: - Shape response payloads with typed outputParameters (string, object, array) and fine-grained JSONPath mapping expressions, executed by the Ikanos runtime. - Keep only relevant fields in exposed tool/resource schemas, while hiding irrelevant upstream fields from the AI surface — enforced through Polychro rulesets in CI. - Attach meaningful info.description, tool descriptions, and tags so discovery is semantic and context quality stays high.

Rightsize AI context

Key features¶

3. Elevate an existing API¶

Wrap a current API as a capability to make it easier to discover, reuse, and consume across teams and channels.

How the Naftiko Fleet achieves this technically: - Model the legacy/existing API once in consumes.resources.operations with explicit methods, paths, parameters, and body formats. - Add a stable capability namespace and expose curated resource paths/tools that are easier to consume than vendor-native endpoints — surfaced by the Ikanos engine. - Reshape not just data but also operation semantics: declare semantics (safe, idempotent, cacheable) on aggregate flows so the engine derives correct HTTP methods for REST adapters and hints for MCP tools automatically. - Enforce schema-based validation (capability-schema.json) with Polychro so the elevated contract remains consistent and machine-checkable.

Elevate existing APIs

Key features¶

4. Elevate Google Sheets API¶

Wrap Google Sheets as a capability so spreadsheet rows become a reusable, domain-specific API for traditional clients and AI agents.

How the Naftiko Fleet achieves this technically: - Consume the Google Sheets values endpoint in consumes.resources.operations, with templated spreadsheet_id and range path parameters plus API key injection through binds. - Transform raw row arrays from $.values into named objects using positional JSONPath mappings such as $[0], $[1], and $[2] inside typed outputParameters — evaluated by the Ikanos runtime. - Expose the normalized result through type: rest, type: mcp, or both, so one spreadsheet integration serves both application and agent use cases.

Elevate GSheets API

Key features¶

Declarative Google Sheets API consumption
Templated spreadsheet ID and A1 range parameters
API key injection via externalized bind values
Declarative row-to-object transformation
Positional JSONPath mapping from array columns to named fields
Typed JSON array exposure for downstream consumers
Dual-channel exposure from one capability
REST resource exposure for conventional clients
MCP tool exposure for AI agents

5. Compose AI context¶

Combine data from multiple APIs into one capability to deliver richer, task-ready context to AI clients.

How the Naftiko Fleet achieves this technically: - Register multiple consumed APIs with unique namespaces, then orchestrate cross-source calls using ordered steps in the Ikanos engine. - Bridge calls through step mappings and per-step input injection, so outputs from one source feed inputs of the next. - Return a single composed output model via mapped outputParameters, giving AI clients one coherent result.

Rightsize AI context

Key features¶

6. Rightsize a set of microservices¶

Create a simpler capability layer over many microservices to reduce client complexity and improve consistency.

How the Naftiko Fleet achieves this technically: - Aggregate multiple microservice endpoints under one exposed namespace and a small set of business-oriented resources/tools, served by the Ikanos engine. - Standardize auth/header behavior and parameter handling at capability level instead of duplicating logic in every client — with conventions enforced by Polychro rulesets. - Use orchestration and output shaping to hide service fragmentation and return consistent contracts.

Rightsize microservices

Key features¶

Declarative source HTTP adapter and target REST adapter
Support for source APIs with JSON payloads
Convert YAML, Protobuf, XML, Avro, and CSV payloads to JSON
Support sequence of steps with calls
Multiple consumed adapters per capability
Namespace-scoped auth, headers, and base URI per adapter
Unified parameter handling across microservices
Input parameters in query, header, path, cookie, and body
Regex pattern validation on string inputs

7. Rightsize a monolith API¶

Extract focused capabilities from a broad monolith API so consumers get only what they need for each use case.

How the Naftiko Fleet achieves this technically: - Select only required monolith operations in consumes and remap them to narrower exposed resources/tools. - Use output filtering/mapping to publish smaller, purpose-built payloads for each consumer scenario — executed by the Ikanos runtime. - Optionally forward selected routes with forward.targetNamespace to keep passthrough paths where full transformation is not needed.

Rightsize monolith APIs

Key features¶

Selective operation exposure from a broad API
Remap consumed operations to narrower exposed resources
Output filtering via typed parameters and JSONPath mapping
Forward proxy for pass-through routes
forward.targetNamespace for direct routing
Trusted header forwarding for security
Dual-channel exposure from one capability
REST resource exposure for conventional clients
MCP tool exposure for AI agents

8. Capability-driven context engineering¶

Design capabilities first for MCP clients, then map them to underlying APIs for a clean AI-native integration model.

How the Naftiko Fleet achieves this technically: - Define type: mcp exposure with server-level description and tool-level contracts (name, description, input/output parameters) — authored with Crafter and validated by Polychro. - Support MCP transports (http or stdio) through the Ikanos engine, so the same capability can run in remote server mode or local IDE/agent mode. - Wire tools to one or many consumed operations via call or orchestrated steps, without changing upstream APIs.

Capability-driven approach

Key features¶

9. Capability-driven API reusability¶

Start from existing APIs and define reusable capabilities on top, so API investments can power new AI and app experiences.

How the Naftiko Fleet achieves this technically: - Begin with consumed API declarations (baseUri, auth, resources, operations), then incrementally add exposed REST/MCP adapters served by the Ikanos engine. - Reuse existing security and configuration using binds with file or runtime injection and injected variables (e.g., {{API_TOKEN}}). - Add format-aware parsing and mapping (JSON, YAML, XML, CSV, TSV, PSV, Avro, Protobuf, HTML, Markdown support in the framework) to normalize diverse backends.

Capability-driven approach

Key features¶

10. Interoperate with OpenAPI¶

Bridge existing OpenAPI ecosystems with Naftiko capabilities: import OAS documents to bootstrap consumption adapters, and export REST adapters as standard OpenAPI specifications.

How the Naftiko Fleet achieves this technically: - Import an OpenAPI 3.0 or 3.1 document (or a Swagger 2.0 document, which is auto-converted) with ikanos import openapi, generating a ready-to-use consumes HTTP adapter with authentication, operations, input parameters, and output parameters pre-filled. - Export a REST exposes adapter with ikanos export openapi, producing a standards-compliant OAS document that can be shared with API gateways, developer portals, and documentation tools. - Use --adapter <namespace> to target a specific REST adapter when the capability exposes more than one.

Key features¶

11. Monitor and debug capabilities¶

Observe capability behavior in real time with built-in metrics, distributed traces, and health checks — configured entirely from the spec.

How the Naftiko Fleet achieves this technically: - Add a type: control adapter in capability.exposes to expose a management plane with health, metrics, traces, and diagnostic endpoints on a dedicated port of the Ikanos engine. - Configure capability.observability to enable OpenTelemetry-based distributed tracing and RED metrics (Rate, Errors, Duration) with configurable sampling and OTLP export. - Scrape Prometheus-format metrics from the control port's /metrics endpoint and inspect recent traces via /traces — no additional infrastructure code required.

Key features¶

12. Transform data between API calls¶

Reshape, filter, or aggregate data between consumed API calls using inline script steps — without building a separate microservice or writing Java code.

How the Naftiko Fleet achieves this technically: - Add type: script steps in orchestrated operations to transform data between call steps using JavaScript, Python, or Groovy, executed by the Ikanos engine. - Scripts run in sandboxed environments (GraalVM for JS/Python, SecureASTCustomizer for Groovy) with no filesystem or network access. - Previous step results are bound as variables; scripts assign to result to produce output for subsequent steps or mappings. - Govern execution centrally via the Control Port's management.scripting block — set defaults, timeouts, statement limits, and allowed languages.