PHPackages                             citomni/helloai - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. citomni/helloai

ActiveLibrary[Framework](/categories/framework)

citomni/helloai
===============

Lean chatbot API integration package for CitOmni: Unified chat request/response format, provider adapters, DB-backed cache, and reuse of the existing Curl infrastructure service.

v1.0.0.0(1mo ago)00MITPHPPHP ^8.2

Since Mar 29Pushed 1mo agoCompare

[ Source](https://github.com/citomni/helloai)[ Packagist](https://packagist.org/packages/citomni/helloai)[ Docs](https://github.com/citomni/helloai)[ GitHub Sponsors](https://github.com/LarsGMortensen)[ Fund](https://ko-fi.com/)[ RSS](/packages/citomni-helloai/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

CitOmni HelloAi
===============

[](#citomni-helloai)

`citomni/helloai` is a reusable CitOmni provider package for conversational AI integrations. It offers one compact, stable internal contract for chat-style requests and responses, so application code can work against a consistent structure rather than provider-specific JSON payloads. The package is intentionally narrow in scope: It is designed to be deterministic, explicit, and operationally useful, not a speculative "universal AI platform."

At its core, HelloAi separates application intent from provider transport. The application submits a normalized request, HelloAi resolves a profile, delegates provider translation to an adapter, performs the outbound HTTP call through the existing CitOmni cURL service, parses the provider response back into a common format, and optionally serves or stores the result through a database-backed cache. This design keeps the public surface area small while preserving room for provider-specific capabilities through explicit escape hatches.

Highlights
----------

[](#highlights)

- **Unified chat contract for CitOmni applications** with one compact internal request/response format across providers.
- **Profile-driven provider selection** so applications target stable profile ids rather than provider-specific payload logic.
- **Adapter-based translation layer** that keeps provider-specific JSON, headers, and response parsing out of application code.
- **Deterministic database-backed caching** keyed from the normalized request payload.
- **Operationally explicit logging and sanitization** with secret masking and useful execution context.
- **Reuse of the existing CitOmni cURL service** instead of introducing a parallel transport abstraction.
- **CLI integration out of the box** through `helloai:chat` for diagnostics, development, and scripting.

Why HelloAi
-----------

[](#why-helloai)

Most chatbot APIs differ in naming, request shape, option semantics, authentication headers, and response envelopes. Those differences are operationally real, but they should not leak into every controller, command, or application service. HelloAi exists to absorb that variability behind a single internal request/response model and a profile-based configuration layer. Profiles select concrete adapters and models; adapters perform provider-specific translation; the application stays focused on intent.

In practical terms, this yields four advantages:

- A single internal request format across providers.
- A single normalized response format for downstream application code.
- Explicit profile-driven configuration rather than implicit provider branching.
- Deterministic caching and logging without inventing a parallel transport stack.

Design principles
-----------------

[](#design-principles)

HelloAi follows a deliberately conservative architecture:

- **Profiles, not providers, are selected by the application.** A profile defines the adapter, model, endpoint, API credentials, and timeout policy.
- **Adapters own translation.** They build provider requests, headers, and response normalization.
- **The existing CitOmni cURL service remains the transport.** HelloAi does not introduce its own generic transport layer.
- **Validation is structural, not doctrinaire.** The package validates request shape and required fields, while leaving provider-specific extensibility available through explicit options.
- **Caching is deterministic.** Identical normalized requests map to identical cache keys.
- **Logging is explicit and sanitized.** Secrets are masked, but operationally relevant context remains available for debugging and observability.

Requirements
------------

[](#requirements)

- PHP **8.2+**
- `ext-json`
- `citomni/kernel`
- `citomni/infrastructure`
- A CitOmni application with the existing cURL service available
- MySQL or MariaDB for the supplied cache table if response caching is enabled

OPcache is strongly recommended in production.

Installation
------------

[](#installation)

```
composer require citomni/helloai
composer dump-autoload -o
```

Register the package provider in `config/providers.php`:

```