3mper0rr/cosmicengineai

1. High-level shape

Cosmic Engine is a mixed C/C++ runtime with a small core and pluggable execution paths. The main binary appears to be a terminal-oriented AI runtime that can drive text generation and, separately, an image-generation pipeline. The repo is split into a low-level runtime layer, provider adapters, telemetry/stream inspection, and optional Python tooling.

2. Primary entry point

src/main.c is the likely CLI entry into the runtime. From there, requests flow into the engine/router layer rather than directly into a provider. The README’s usage suggests the binary accepts a mode such as llm prompt, which then selects the relevant backend path.

3. Core runtime / orchestration layer

src/engine.c, src/engine.h, and src/engine_router.c look like the central dispatch layer. This is where model requests are normalized, routed, and handed off to the correct backend or provider implementation. src/orchestrator/orchestrator.cpp plus its headers suggest a higher-level coordination layer, likely responsible for composing backend selection, request lifecycle, and provider capability decisions.

4. Backend abstraction

src/backend.cpp/.h and src/http.c/.h form the abstraction boundary between the engine and transport/provider-specific execution. This is likely where the runtime isolates generic request handling from the details of HTTP calls, streaming, and backend-specific response handling. The repository’s README explicitly calls out a “HTTP backend abstraction layer.”

5. Provider implementation boundary

The concrete text provider currently present is Groq. src/providers/groq/stream.c/.h is the provider-specific streaming adapter, likely responsible for reading Server-Sent Events, parsing chunks, and extracting deltas from the Groq API response. This is the main place where provider-specific wire format handling lives.

6. Streaming and observability

Streaming is a first-class subsystem, not just an output detail. The README highlights raw chunk inspection, delta extraction, SSE handling, and TTFB measurement. That functionality appears to be split across src/telemetry.cpp/.hpp and src/telemetry/telemetry.c/.h, with src/probe.cpp/.hpp likely measuring transport timing or chunk arrival behavior. The architecture therefore includes an observability lane alongside the request lane.

7. Bridging C and C++

src/bridge.cpp/.hpp likely provides glue between the C runtime pieces and the C++ orchestration/telemetry components. This matters architecturally because the repo is not a single-language codebase; the bridge probably keeps the C entry/runtime layers interoperable with C++ orchestration and higher-level utilities.

8. Image-generation path

Image generation is separate from the LLM text path. src/img_backend.c/.h appears to encapsulate image-provider access, and the README says HuggingFace Inference API is the current image provider. The image path is also supported by optional Python tooling in tools/run_img.py, indicating that image workflows may be partially externalized from the C/C++ core.

9. Configuration and runtime dependencies

src/config.h likely centralizes compile-time or environment-driven configuration, including API keys and provider toggles. The runtime depends materially on libcurl for outbound HTTP. The README shows environment-based configuration for GROQ_API_KEY and HF_TOKEN, so secrets and provider selection are runtime inputs rather than baked into the binary.

10. External services

The main external dependency today is the Groq API for streaming LLM inference. HuggingFace Inference API is used for image generation. Ollama is mentioned as planned/partial, and OpenRouter/Gemini are listed as future or experimental providers, so the architecture is explicitly designed to expand across multiple inference vendors.

11. Execution flow for text generation

A typical text request likely flows: CLI entry point → engine/router → backend abstraction → Groq provider stream handler → HTTP/SSE transport → telemetry/probe capture → terminal output. The important architectural point is that response streaming and measurement happen during transport, not only after completion.

12. Execution flow for image generation

The image path is more loosely coupled: the core runtime or a helper backend invokes the image backend, while the Python tooling can stand up the environment and run the HuggingFace-based generation script. This suggests image generation is adjacent to, but not fully embedded in, the C/C++ runtime core.

13. Tooling and developer workflow

makefile builds the native runtime; tools/menu.sh and tools/ollama_cloud.sh appear to support setup or provider workflows; tools/run_img.py supports the Python image pipeline. So the repo has two operational modes: a compiled native runtime for text/streaming, and a Python-assisted path for image generation.

14. Notable structural constraint

The repository contains several * copia.* files, which look like backups or alternate snapshots of core modules. For architecture diagrams, the stable conceptual modules are the non-copia files: main/runtime, engine/router, backend/HTTP, provider streams, telemetry/probe, orchestrator, and image backend.