Metadata-Version: 2.4
Name: suphia
Version: 0.1.3
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 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.

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
