SEMOSS

An open source platform for building AI applications, connecting data, and running analytics.

SEMOSS (Semantic Open Source Software) brings models, databases, vector stores, storage providers, and custom functions into a common framework. Use it to build AI assistants and applications, work with enterprise data, and create repeatable analytical workflows through a web interface, APIs, or code.

This repository contains the core SEMOSS runtime: the Java execution engine, Pixel language and reactors, engine integrations, Python and R components, and container build definitions. Monolith exposes the runtime through a web application and APIs, and semoss-ui provides the user interface.

Documentation · Docker quick start · Build from source · Complete deployment examples · Issues

• Capabilities
• Architecture and related repositories
• Quick start with Docker
• Complete deployments
• Core concepts
• Building from source
• Running tests
• Configuration
• Repository layout
• Documentation
• Troubleshooting
• Contributing and support
• License

• AI and model integration. Connect language and embedding models through a shared engine interface. Combine model calls with data retrieval, functions, and application workflows.
• Data access and analytics. Query connected databases, combine data from multiple sources in frames, transform results, and use them in applications, notebooks, and automated workflows.
• Vector search and retrieval. Ingest documents and connect vector databases for semantic search and retrieval augmented generation.
• Applications and automation. Build applications, agents, and reusable workflows using Pixel, Java reactors, Python, R, and custom functions or APIs.
• Shared access controls. Manage access to engines, projects, and insights, with platform services for authentication, permissions, model usage logging, and auditing.
• Flexible deployment. Run locally with Docker Compose or deploy multiple application nodes with shared databases, object storage, and Redis or ZooKeeper coordination.

Available integrations and runtime features depend on the engines and services configured in your installation.

flowchart LR
    UI["semoss-ui"] --> Web["Monolith: web APIs and sessions"]
    Clients["API clients"] --> Web
    Web --> Core["Semoss: core runtime"]
    Core --> Engines["Models, databases, vectors, storage, functions"]
    Core --> Runtimes["Python and R runtimes"]
    Core --> State["System databases and shared assets"]

Monolith packages the core runtime as a Java dependency in its WAR. These are layers of the application; the diagram does not require a separate service for each box.

For a ready-to-run local platform, use the Docker examples below. To run backend code changes, use Monolith's local Docker examples.

The quickest way to try SEMOSS is the Docker Compose examples. They use a published SEMOSS image containing the web application and UI, so no local Java or frontend build is required.

• Git.
• Docker with a running daemon and Docker Compose v2 (docker compose).
• Access to pull container images, including the SEMOSS image from Quay.io.
• Available host ports 9090 for SEMOSS and 5432 for PostgreSQL.

git clone https://github.com/SEMOSS/Semoss.git
cd Semoss/docker-compose-examples

# Create the shared network if it does not already exist.
docker network inspect semoss-net >/dev/null 2>&1 || docker network create semoss-net

docker compose -f semoss-with-postgres.yml up -d
docker compose -f semoss-with-postgres.yml logs -f semoss

Wait for application startup, then open http://localhost:9090/#/. The example enables native registration for local use; follow the application's account setup and sign-in flow. PostgreSQL credentials in the Compose file are database credentials, not a SEMOSS user account.

This stack starts SEMOSS and PostgreSQL, initializes the system databases using init.sql, and persists application data in named Docker volumes. Python is enabled and R is disabled in these examples.

Check the stack or stop it from the same directory:

docker compose -f semoss-with-postgres.yml ps
docker compose -f semoss-with-postgres.yml down

down retains named volumes. Adding -v deletes those volumes and their data.

Use the selected filename with docker compose -f. Run one platform example at a time: the stacks share fixed container names and host ports, including with Monolith's local examples. Stop the current stack before switching. Cluster variants use service names semoss1 and semoss2 for logs.

The Compose guide documents supporting service ports, storage behavior, and configuration. The examples use development images and local credentials; configure credentials, authentication, and network exposure for your deployment before making it accessible to others.

The engine examples provide optional services and connection instructions for vector databases, ClickHouse, object storage, SFTP, and mail functions. Start only the services you need, then configure the corresponding engine in SEMOSS. These examples share the semoss-net Docker network with the platform examples.

For Kubernetes and infrastructure deployment, or semoss-artifacts property configuration, see SEMOSS-deployment.

A typical request travels from semoss-ui or an API client through Monolith to the core runtime. Pixel operations invoke reactors, which use engines and frames to perform the work. Results return through Monolith to the caller. See the backend architecture and Monolith integration.

Use JDK 21 and Apache Maven 3.9.x; the Java compiler targets 21 and CI uses Maven 3.9.9. Git and access to the Maven repositories declared in pom.xml are also required. Check the active toolchain with java -version and mvn -version.

From the repository root:

mvn clean install

This compiles the core, runs the default test selection, creates artifacts under target/, and installs them into your local Maven repository. For a build that skips test execution:

mvn clean install -DskipTests

The default dev profile is intended for local development. The deploy profile adds release packaging and signing steps; it is not needed for a local build. The development build also configures the repository's Git hooks.

Keep the two repositories next to each other:

workspace/
├── Semoss/
└── Monolith/

Build Semoss before Monolith. Their ci.version values must match because Monolith depends on org.semoss:semoss with the shaded-dependencies classifier. A successful mvn install here makes that artifact available to the local Monolith build.

Follow Monolith's Docker quick start to build both repositories and run the resulting local-monolith image. The published-image examples in this repository do not include unbuilt local source changes. Frontend development is documented in semoss-ui.

Run these commands from the repository root:

# Run the default unit test selection.
mvn test

# Run one test class.
mvn -Dtest=YearReactorUnitTests test

# Run verification, including the configured JaCoCo report step.
mvn verify

The default Maven profile selects **/*UnitTests.java from test/. This is not a promise that every integration test or external service is exercised. Tests for specific integrations may require additional services and configuration. Surefire results are written to target/surefire-reports/, and JaCoCo reports to target/site/jacoco/ when generated.

The running application uses a SEMOSS home directory for configuration, engine definitions, projects, and runtime assets. Container startup translates supported environment variables into the application's configuration; use the checked-in Compose files as concrete examples.

In the examples, CUSTOM_* variables configure the system databases; SETSOCIAL, ENABLE_NATIVE, and REDIRECT configure local login behavior; NETTY_PYTHON and NATIVE_PY_SERVER enable Python integration. MinIO variants add shared storage configuration, and the two-node variants add a coordination backend. Preserve the database names and connection settings consistently with the initialization SQL.

Start with the documentation index, then choose a path:

• Understand the runtime: architecture, Pixel, and engine abstractions.
• Extend the platform: write a reactor, work with databases, or use frames.
• Build AI integrations: model engines, vector engines, GenAI client, and Python GAAS tools.
• Develop the web application: Monolith and semoss-ui.
• Operate the platform: Docker examples and complete deployment examples.

Bug reports, documentation improvements, tests, and new integrations are welcome. Use Semoss issues for core runtime problems, Monolith issues for web/API problems, and semoss-ui issues for frontend problems.

For a change, keep the scope focused, include relevant tests and documentation, and describe the behavior and validation in your pull request. Follow the commit message conventions. When reporting a bug, include the revision or image tag, deployment topology, reproduction steps, and relevant logs with credentials and private data removed.

See LICENSE for the Apache License 2.0 terms. Retain applicable source-file and third-party dependency notices when redistributing the software.