Metadata-Version: 2.4
Name: suphia
Version: 0.1.4
Summary: A deterministic, cross-platform agent skill publisher.
License-File: LICENSE
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Suphia

**Suphia** is a compatibility layer for AI agent ecosystems.

It provides a **set of tools** that allow developers to work with
**multiple, fast-evolving AI agents** using a **single source of truth**
for context and configuration — without duplication.

Suphia is designed to keep context **close to your code**, while adapting
that context to many different agents and formats.

---

## The Problem Suphia Solves

AI development today rarely involves just one agent.

Developers often experiment with:
- Claude
- Gemini
- Copilot
- OpenCode
- Codex
- new or experimental agents
- changing formats and conventions

Each agent introduces:
- different discovery rules
- different configuration formats
- different expectations about layout

Without Suphia, developers end up:
- copying context files again and again
- restructuring repos for each tool
- losing alignment between code and context

Suphia exists so you **adapt once**, not agent-by-agent.

---

## Suphia’s Core Idea

> Keep **one canonical source of context**, close to your code,
> and project it outward to any agent that needs it.

Suphia does not enforce a single format.
It provides **adapters and tooling** so agents can coexist.

---

## What Suphia Is

- A **CLI toolset**
- A **Python module library**
- An **adapter layer** between agent ecosystems

Suphia can be:
- used directly via CLI
- integrated into other frameworks
- embedded in automation or CI

---

## What Suphia Is Not

- An agent runtime
- A prompt framework
- A vendor-specific solution

Suphia complements agents — it does not replace them.

---

## Initial Focus: Skills

Suphia v1 starts with **skills** as a practical, high-impact use case.

It allows you to:

- Place skills anywhere in your repo
- Keep them near relevant code
- Discover them recursively
- Publish them into agent-specific discovery roots
- Avoid copying or rewriting skill files

This enables skill reuse across:
- Claude-style agents
- Copilot-style agents
- OpenCode and others

See `docs/SuphiaSkillLifecycleDesign.md` for the planned skill lifecycle model,
including bundle/extract workflows, the target registry, self-skills,
global/local/custom scopes, Windows/WSL support, and shared terminology.

Implemented CLI examples:

```bash
suphia skills validate --source .
suphia skills plan --source . --target generic --scope local
suphia skills publish --source . --target opencode --scope global
suphia skills bundle --source . --output skills.suphia --profile public --all
suphia skills bundle --source . --output selected.suphia --include lint
suphia skills bundle --output selected.suphia --select
suphia skills bundle --output selected.suphia --include "lint,docs-*" --include "re:^test-"
suphia skills extract skills.suphia --target generic --scope local --all
suphia skills extract skills.suphia --dest .claude/skills --include lint
suphia self install-skills --target generic --scope global
suphia targets list
suphia targets show vscode-copilot
suphia templates copy vscode-copilot/openai-compatible.template.json --dest ./template.json
suphia -v
```

After installing or upgrading with `uv tool install suphia` or
`uv tool upgrade suphia`, refresh Suphia's packaged usage skill explicitly:

```bash
suphia self install-skills --target generic --scope global
```

Package upgrades do not mutate skill copies already installed into agent roots.

Use `--security-policy policy.json` with `skills validate` or `skills bundle` to
add repository-specific denylist patterns or safe placeholder values without
storing secrets in the repository.

When `skills bundle --source` is omitted, Suphia auto-detects a skill source by
checking global user roots such as `~/.claude/skills` and
`~/.config/opencode/skills`, then the detected workspace/current path. Use
`--select` to show an arrow-key toggle menu with skill origin hints; use Space
to toggle, Enter to confirm, `all` to select every listed skill, and `q`/Esc to
abort. Use `--include` with exact names, comma-separated
lists, glob patterns, or regex patterns written as `re:<pattern>` or `/pattern/`.
Bundle and extract require explicit selection intent: use `--all`, `--include`,
or `--select`. Do not combine `--all` with selective options.
Combining `--include` with `--select` lists the matching candidate skills before
bundling. Bundles record whether they came from a global user root, local
workspace root, or custom path. During interactive extraction, Suphia lists
bundled skills first, then shows source metadata and lets you install to the
global user root, the current workspace root, or choose global/local per skill.
Per-skill mode shows one table of selected skills where Space toggles the
highlighted row between `global` and `local`, and Enter confirms the whole table.
Bundle and extract commands print highlighted scan, selection, write, and install
progress so long-running operations stay visible. After bundling, Suphia
prints next-step extract commands for another workspace or PC. After extraction,
it prints the install location and a validation command.

Project defaults can be stored in `suphia.json` or `.suphia.json`:

```json
{
  "target": "generic",
  "scope": "local",
  "profile": "public",
  "excludes": [".venv"],
  "security_policy": "suphia-security.json"
}
```

For Windows/WSL migration patterns, see `docs/WindowsWslMigration.md`.

---

## Installation

Suphia uses **`uv`** for Python tooling.

Install:

```bash
uv pip install suphia
