Metadata-Version: 2.5
Name: henosis-engine
Version: 0.1.0
Summary: An open-source context engine for physical assets.
Project-URL: Homepage, https://www.henos.io
Project-URL: Documentation, https://www.henos.io/docs
Project-URL: Repository, https://github.com/henos-io/henosis
Project-URL: Issues, https://github.com/henos-io/henosis/issues
Author-email: Chris Bouras <chris.bouras@henos.io>
License-Expression: MIT
License-File: LICENSE
Keywords: asset-management,data-federation,digital-twin,duckdb,historian,industrial,knowledge-graph,mcp,model-context-protocol,ontology
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: common-expression-language>=0.7
Requires-Dist: dlt>=1.4
Requires-Dist: duckdb>=1.0
Requires-Dist: fastapi>=0.115
Requires-Dist: mcp>=2
Requires-Dist: pyarrow>=14
Requires-Dist: pydantic>=2.7
Requires-Dist: pytz
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.30
Provides-Extra: owl
Requires-Dist: rdflib>=7.0; extra == 'owl'
Provides-Extra: snowflake
Requires-Dist: snowflake-connector-python[pandas]>=3.0; extra == 'snowflake'
Description-Content-Type: text/markdown

# henosis

**One asset context. Every decision.**

*Open-source context engine for physical assets.*

Bring your operational systems together in one live, shared view so people,
software and AI agents can find answers and take action without moving your data.

**[henos.io](https://www.henos.io)** · [Docs](https://www.henos.io/docs) · [Quickstart](https://www.henos.io/docs/quickstart)

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/henos-io/henosis/main/logo/henosis-hero-dark.svg">
  <img alt="One asset context, every decision. People, applications and AI agents draw on shared asset context assembled from existing source systems, with actions flowing back to where the work happens." src="https://raw.githubusercontent.com/henos-io/henosis/main/logo/henosis-hero-light.svg">
</picture>

> **Early and under active development.** henosis is at an early stage and
> changing quickly — expect rough edges, and expect APIs, the ontology grammar
> and the CLI to change between releases. It is not yet recommended for
> production use.
>
> **Available today:** the henosis Engine, REST API, MCP server and developer
> Explorer. The end-user Canvas shown above is in development and is not yet
> publicly available.

## Built around how asset decisions are made

henosis organises information about your operation into five clear roles:

- **Identity** — what it is
- **Location** — where it is
- **Observation** — what it is doing, now and over time
- **Documents** — what is known about it
- **Relationships** — what it is connected to

These roles give each piece of information a clear purpose. Locations can appear on
maps, observations can be plotted over time, and relationships can be followed
directly. The meaning is built into the model instead of recreated in every tool.

A decision draws on those roles. An action can then write the result back to the
source system, making the new state available to the next decision.

## Engine, Explorer and Canvas

### Engine

The **Engine** is the open-source software in this repository. It compiles the YAML
model, resolves data from connected systems and serves the result through:

- **REST API** (`/v1`) for applications and integrations
- **MCP tools** (`/mcp`) for AI agents

Operational values stay in their source systems. The Engine stores the compiled
model, routing information and relationship index.

### Explorer

The **Explorer** is a developer interface included with the Engine. Use it to inspect
the ontology, test connections, exercise REST endpoints and browse entities while
building a model.

The Explorer is not an operational dashboard and is not the Canvas.

### Canvas

The **Canvas** is a separate end-user workspace being developed on top of the
Engine. It will bring maps, trends, entity details and agent-driven workflows into
one operational surface.

The Canvas is not included in this repository and is not yet publicly available.

## Why henosis

- **One model, multiple interfaces.** Applications use the REST API and AI agents
  call MCP tools today. The Canvas will bring the same model to people.
- **MIT licensed and self-hosted.** Run henosis in your own environment. Inspect,
  adapt and extend the code.
- **Read data where it lives.** henosis queries historians, maintenance records,
  maps and documents in their source systems. There is no migration or duplicate
  data layer.
- **Write actions back to source systems.** People and agents can act on what they
  find, with governed changes recorded where the work happens.

## Works with what you already run

Connect the systems that already hold your operational context:

| System | Connectors available today |
|---|---|
| Historians and signals | AVEVA PI Web API |
| Databases | PostgreSQL · MySQL · Snowflake · SQLite |
| Services and APIs | REST / HTTP APIs |
| Files and lakes | Parquet · CSV |
| Geospatial services | ArcGIS · WFS |
| Documents | Local file-backed documents |

Need another source? Register a connector without forking or changing the Engine
core. Snowflake support uses the optional `snowflake` dependency.

## Where it fits

A generic graph can show what is connected without defining what each connection
means. henosis gives information a clear role and provides tools for querying it,
so applications and agents spend less time working out where to look.

henosis complements an existing data foundation. It does not replace a warehouse,
knowledge graph, digital twin, dashboard or RAG system. It provides a live,
opinionated asset model that those systems can supply or consume.

## Install

henosis requires Python 3.11+. The package name is `henosis-engine`; the CLI command
is `henosis`.

```bash
uv tool install henosis-engine
```

Or install from source:

```bash
git clone https://github.com/henos-io/henosis.git
cd henosis
uv tool install .
```

## Quickstart

Create the included Cooper Basin example and start the local server:

```bash
henosis init cooper-basin
henosis serve -p cooper-basin --mcp
```

Open <http://127.0.0.1:8000> to explore the live model. Search across entity types,
then follow an asset's relationships, readings, location and documents.

The example is a synthetic upstream gas operation backed by local SQLite and
Parquet sources. `henosis init` creates the project, generates its data, compiles
the ontology and builds the relationship index.

Run `henosis init --list` to see the other worked examples. Each scaffolded project
is yours to edit, and its YAML files are the source of truth for the model. See
[Ontology and data sources](https://www.henos.io/docs/ontology-and-data-sources)
for the authoring guide.

## Connect an AI agent

Start the server with MCP mounted, then point your client at it through
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```bash
henosis serve -p cooper-basin --mcp
```

```json
{
  "mcpServers": {
    "henosis": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8000/mcp", "--http"]
    }
  }
}
```

This works with any MCP client and lets several clients share one running
server. Clients that speak Streamable HTTP natively can point at `/mcp` directly.

Alternatively, a client can launch henosis as a local subprocess over stdio,
which needs no server running and no Node:

```json
{
  "mcpServers": {
    "henosis": {
      "command": "henosis",
      "args": ["serve", "--stdio", "-p", "/absolute/path/to/cooper-basin"]
    }
  }
}
```

Use authentication and HTTPS for any deployment beyond localhost.

## Status

henosis is an early technical preview. The Engine, compiler, ontology store,
connectors, REST and MCP serving, CLI, developer Explorer and worked examples are
built and exercised against the included scenarios.

APIs may change during the preview. The Canvas remains in development and is not
yet available.

## Feedback

If this idea maps to a problem in your environment, open an issue or contact
[Chris Bouras](mailto:chris.bouras@henos.io).

## Security

The Engine does not yet include built-in authentication. `serve` binds to
`127.0.0.1` by default. Any deployment reachable beyond localhost needs
authentication and TLS in front of it.

To report a vulnerability, see [SECURITY.md](https://github.com/henos-io/henosis/blob/main/SECURITY.md).

## License

[MIT License](https://github.com/henos-io/henosis/blob/main/LICENSE).
