Metadata-Version: 2.4
Name: cisternal
Version: 0.1.1a4
Summary: Shared telemetry substrate and agent-asset export toolkit for the Praxia tool family
Author: Marielle Russo
License-Expression: MIT
Project-URL: Homepage, https://github.com/maraxen/cisternal
Project-URL: Repository, https://github.com/maraxen/cisternal
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cyclopts>=4.18.0
Requires-Dist: fastmcp==4.0.0a2
Requires-Dist: opentelemetry-api>=1.42.1
Requires-Dist: pyyaml>=6.0.2
Provides-Extra: otlp
Requires-Dist: opentelemetry-sdk>=1.42.1; extra == "otlp"
Requires-Dist: opentelemetry-semantic-conventions>=0.63b1; extra == "otlp"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.42.1; extra == "otlp"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.42.1; extra == "otlp"
Dynamic: license-file

# cisternal

**Status: alpha.** APIs may change without notice before `1.0`.

Cisternal is a shared telemetry substrate and agent-asset export toolkit for the Praxia tool family. It has two parts:

- **Telemetry** — a lightweight, non-blocking event pipeline (JSONL export, OTLP export, MCP-tool registration wrapper) for instrumenting Python tools and MCP servers.
- **Agent-asset export** — a CLI that takes a registry of MCP tools/commands and emits native plugin/config bundles for downstream coding-agent surfaces: Claude Code, Cursor, GitHub Copilot, and Antigravity.

## Install

```bash
pip install cisternal
```

For OTLP export support:

```bash
pip install "cisternal[otlp]"
```

## Telemetry quickstart

```python
import cisternal

cisternal.init()  # log_dir defaults to ~/.cisternal/logs, or env-resolved

with cisternal.span("my.operation", request_id="abc123"):
    do_work()

cisternal.emit_event("my.custom_event", tool="foo")
print(cisternal.status())
```

Check your effective telemetry configuration from the shell:

```bash
cisternal telemetry doctor
cisternal telemetry doctor --json --strict
```

### Registering MCP tools

```python
import cisternal

@cisternal.tool
def my_tool(x: int) -> int:
    return x * 2

registry = cisternal.wire(server, app, adapter=my_adapter)
```

`cisternal.tool` is a pure-metadata decorator — it returns the original function unchanged. `cisternal.wire()` snapshots the registry at call time and registers each tool on a FastMCP server (and optionally a Cyclopts CLI app), returning a `WiredRegistry` for introspection.

## Agent-asset export

```bash
# Preview what would be written, without touching disk
cisternal assets export --dry-run

# Write bundles for specific surfaces
cisternal assets export --out ./dist/agent-assets

# Inspect or validate an existing bundle
cisternal assets inspect
cisternal assets validate
```

### Install as a real Claude Code plugin

`cisternal assets export` only writes files — nothing picks them up until
something registers them. `cisternal assets install` does both steps: it
writes the bundle, then drives the real `claude` CLI to register it as a
local marketplace and install it, so its skills/agents/MCP config actually
load in a Claude Code session.

Requires a `[plugin.marketplace]` table in your manifest:

```toml
[plugin]
name = "my-plugin"
version = "1.0.0"

[plugin.marketplace]
name = "my-plugin-marketplace"

[plugin.marketplace.owner]
name = "Your Name"
```

```bash
cisternal assets install --manifest .praxia/manifest.toml
# writes the bundle to ./, then runs:
#   claude plugin marketplace add .
#   claude plugin install my-plugin@my-plugin-marketplace --scope project
```

Both underlying `claude` commands are idempotent — re-running `install` is
safe. `--scope project` (the default) registers the plugin in this
project's `.claude/settings.json`, so anyone who clones the repo needs only
one manual `claude plugin install my-plugin@my-plugin-marketplace` (Claude
Code's own trust-on-first-use step — not something this command tries to
bypass). To remove it later: `claude plugin uninstall
my-plugin@my-plugin-marketplace` and `claude plugin marketplace remove
my-plugin-marketplace`.

Supported export targets: **Claude Code**, **Cursor**, **GitHub Copilot**, **Antigravity**.

The CLI is fastmcp-free by design — `cisternal.cli` imports and runs even in environments without `fastmcp` installed; asset-export logic never depends on the telemetry/registration surface.

## Design notes

- Telemetry emission never raises: if the pipeline isn't initialized, `emit_event`/`span` are no-ops.
- Registry state is process-scoped — call `cisternal.clear_registry()` between tests to avoid cross-test contamination.
- The M2 wire-time MCP callable is a pure passthrough: telemetry and shape adaptation are exclusively owned by the telemetry middleware, never by the registration wrapper itself.

## License

MIT — see [LICENSE](LICENSE).
