decepticon-sdk 1.1.2__tar.gz

decepticon_sdk-1.1.2/.gitignore

@@ -0,0 +1,117 @@
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# IDE and Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Python specific
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Node
+node_modules/
+
+# etc
+sliver-py/
+/src/
+config/*.local.*
+reference/
+demo.tape
+
+# Decepticon runtime data
+.decepticon/
+.dogfood/
+workspace/
+.bg-shell/
+
+.langgraph_api/
+.omc/
+.ouroboros/
+.gstack/
+.claude/
+clients/ee/
+
+# Project-specific Claude Code instructions (private)
+CLAUDE.md
+references/octogent
+clients/launcher/decepticon
+
+# Benchmark
+# Per-run artefacts (timestamped batch + evidence/ + reports/) are local-only.
+# Curated per-challenge results (XBEN-*-24/) and the LEVEL3 index are committed.
+# LangSmith trace dumps live as public share URLs in READMEs — never committed.
+benchmark/results/*
+!benchmark/results/.gitkeep
+!benchmark/results/XBEN-*-24/
+!benchmark/results/README.md
+benchmark/results/XBEN-*-24/evidence/langsmith_trace.json
+benchmark/results/XBEN-*-24/evidence/iter14_pass.json
+benchmark/results/XBEN-*-24/evidence/*_iter*.json
+# Per-run timestamped subdirs inside XBEN-*-24/ are local dev artefacts.
+# The flat root (report.json / report.md / evidence/summary.{json,md}) is the
+# committed PASS record — see benchmark/results/README.md for the policy.
+benchmark/results/XBEN-*-24/2[0-9][0-9][0-9][0-9][0-9][0-9][0-9]_*/
+benchmark/workspaces/
+
+# Codex / OMX runtime artefacts (never committed)
+.omx/
+.env.bak.*
+benchmark/results/XBEN-*-24/run-loop*.log
+
+# Git worktrees
+.worktrees/

decepticon_sdk-1.1.2/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: decepticon-sdk
+Version: 1.1.2
+Summary: Decepticon plugin author SDK: protocols, fixtures, scaffolding
+Project-URL: Homepage, https://github.com/PurpleAILAB/Decepticon
+Project-URL: Repository, https://github.com/PurpleAILAB/Decepticon
+Author: Decepticon Team
+License: Apache-2.0
+Keywords: agents,ai,plugins,red-team,sdk,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: decepticon-core
+Requires-Dist: typer[all]>=0.9.0
+Provides-Extra: fixtures
+Requires-Dist: decepticon; extra == 'fixtures'
+Provides-Extra: testing
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'testing'
+Requires-Dist: pytest>=8.0.0; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# decepticon-sdk
+
+The Decepticon plugin author entrypoint. Re-exports the `decepticon-core`
+contracts, ships pytest fixtures, and provides a scaffolding CLI for
+creating new plugin packages.
+
+A complete plugin can be written importing only from `decepticon_sdk`:
+no underscore-prefixed framework internals required.
+
+See the umbrella [`README.md`](../../README.md) and the design spec at
+[`docs/superpowers/specs/2026-05-23-core-framework-sdk-split-design.md`](../../docs/superpowers/specs/2026-05-23-core-framework-sdk-split-design.md).
+
+## Install
+
+```bash
+pip install decepticon-sdk
+```
+
+For test fixtures and scaffolding:
+
+```bash
+pip install "decepticon-sdk[testing]"      # FakeBackend / FakeLLM
+pip install "decepticon-sdk[fixtures]"     # live framework-backed fixtures
+```

decepticon_sdk-1.1.2/README.md

@@ -0,0 +1,24 @@
+# decepticon-sdk
+
+The Decepticon plugin author entrypoint. Re-exports the `decepticon-core`
+contracts, ships pytest fixtures, and provides a scaffolding CLI for
+creating new plugin packages.
+
+A complete plugin can be written importing only from `decepticon_sdk`:
+no underscore-prefixed framework internals required.
+
+See the umbrella [`README.md`](../../README.md) and the design spec at
+[`docs/superpowers/specs/2026-05-23-core-framework-sdk-split-design.md`](../../docs/superpowers/specs/2026-05-23-core-framework-sdk-split-design.md).
+
+## Install
+
+```bash
+pip install decepticon-sdk
+```
+
+For test fixtures and scaffolding:
+
+```bash
+pip install "decepticon-sdk[testing]"      # FakeBackend / FakeLLM
+pip install "decepticon-sdk[fixtures]"     # live framework-backed fixtures
+```

decepticon_sdk-1.1.2/decepticon_sdk/__init__.py

@@ -0,0 +1,107 @@
+"""decepticon-sdk — plugin author entrypoint for the Decepticon framework.
+
+A complete Decepticon plugin can be written importing only from this
+package: every protocol, contract, registry, and helper plugin authors
+need is exported here. No underscore-prefixed framework internals are
+required.
+
+Phase 3 surface:
+
+  * ``decepticon_sdk`` (this module) — re-exports the public
+    ``decepticon-core`` API (types, protocols, contracts, registries,
+    plugin loader). Tracks the framework's release version (current
+    series: 1.1.x → 1.1.2 with this redesign; shim removal at 2.0.0).
+    Public names listed in ``__all__`` are SemVer-stable.
+  * ``decepticon_sdk.testing`` — pytest fixtures and fakes
+    (``FakeBackend``, ``FakeLLM``, ``FakeSandbox``) for hermetic
+    plugin tests that don't need a live framework.
+
+Deferred from Phase 3 (follow-up commits):
+
+  * ``decepticon-sdk plugin new --kind=...`` scaffolding CLI
+  * Runnable example plugin per ``kind`` under ``examples/``
+"""
+
+from __future__ import annotations
+
+# Re-export the decepticon-core contracts so plugin authors only need
+# a single import line:
+#
+#     from decepticon_sdk import (
+#         BackendProtocol, MiddlewareProtocol, ToolContribution,
+#         PluginBundle, SubAgentSpec, RoleRegistry, ...
+#     )
+from decepticon_core.contracts.contributions import (
+    MiddlewareContribution,
+    PromptContribution,
+    SafetyDeclaration,
+    SubAgentContribution,
+    ToolContribution,
+)
+from decepticon_core.contracts.slots import (
+    SAFETY_CRITICAL_SLOTS,
+    SLOTS_PER_ROLE,
+    MiddlewareSlot,
+)
+from decepticon_core.plugin_loader import (
+    PluginBundle,
+    SubAgentSpec,
+    is_bundle_enabled,
+)
+from decepticon_core.protocols import (
+    AgentProtocol,
+    BackendProtocol,
+    CallbackProtocol,
+    LLMProtocol,
+    MiddlewareProtocol,
+    SandboxProtocol,
+    ToolProtocol,
+)
+from decepticon_core.registry import (
+    PluginConflictWarning,
+    PluginInfo,
+    PluginRegistry,
+    RoleRegistry,
+    RoleResolution,
+    RoleSpec,
+    SafetyRegistry,
+    SkillSourceRegistry,
+)
+
+__version__ = "0.0.0"
+
+__all__ = [
+    # Protocols (decepticon_core.protocols)
+    "AgentProtocol",
+    "BackendProtocol",
+    "CallbackProtocol",
+    "LLMProtocol",
+    "MiddlewareProtocol",
+    "SandboxProtocol",
+    "ToolProtocol",
+    # Slot enum + constants (decepticon_core.contracts.slots)
+    "MiddlewareSlot",
+    "SAFETY_CRITICAL_SLOTS",
+    "SLOTS_PER_ROLE",
+    # Plugin contributions (decepticon_core.contracts.contributions)
+    "MiddlewareContribution",
+    "PromptContribution",
+    "SafetyDeclaration",
+    "SubAgentContribution",
+    "ToolContribution",
+    # Plugin loader (decepticon_core.plugin_loader)
+    "PluginBundle",
+    "SubAgentSpec",
+    "is_bundle_enabled",
+    # Registries (decepticon_core.registry)
+    "PluginConflictWarning",
+    "PluginInfo",
+    "PluginRegistry",
+    "RoleRegistry",
+    "RoleResolution",
+    "RoleSpec",
+    "SafetyRegistry",
+    "SkillSourceRegistry",
+    # Version
+    "__version__",
+]

decepticon_sdk-1.1.2/decepticon_sdk/scaffold/__init__.py

@@ -0,0 +1,21 @@
+"""Plugin scaffolding CLI — ``decepticon-sdk plugin new --kind=...``.
+
+Phase 3 of the core/framework/sdk split (per
+``docs/superpowers/specs/2026-05-23-core-framework-sdk-split-design.md``)
+ships a typer-based generator so plugin authors run one command and
+get a buildable plugin package: pyproject.toml, src/<name>/__init__.py
+wired to the right entry-point group, and a short README.
+
+Six plugin kinds covered: ``tool``, ``middleware``, ``agent``,
+``callback``, ``skill``, ``prompt``.
+
+Usage:
+
+    decepticon-sdk plugin new --kind=middleware --name=my-plugin --path=./my-plugin
+"""
+
+from __future__ import annotations
+
+from decepticon_sdk.scaffold.cli import app
+
+__all__ = ["app"]

decepticon_sdk-1.1.2/decepticon_sdk/scaffold/cli.py

@@ -0,0 +1,114 @@
+"""``decepticon-sdk plugin new`` — typer-based scaffold CLI.
+
+Generates a buildable plugin package for one of the six supported
+plugin kinds. The output directory contains ``pyproject.toml``,
+``README.md``, and ``src/<module>/__init__.py`` wired to the matching
+``decepticon.<group>`` entry-point group.
+
+Sample run::
+
+    decepticon-sdk plugin new --kind=middleware --name=my-plugin --path=./my-plugin
+    cd my-plugin
+    uv build
+    pip install dist/*.whl
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from decepticon_sdk.scaffold.templates import TEMPLATES, pyproject_for
+
+app = typer.Typer(
+    name="decepticon-sdk",
+    help="Decepticon plugin author SDK — scaffold + utilities.",
+    no_args_is_help=True,
+)
+
+plugin_app = typer.Typer(name="plugin", help="Plugin scaffolding subcommands.")
+app.add_typer(plugin_app)
+
+
+def _normalize_module_name(plugin_name: str) -> str:
+    """Convert ``my-plugin`` (PyPI-style) into ``my_plugin`` (module-style)."""
+    return plugin_name.replace("-", "_")
+
+
+@plugin_app.command("new")
+def plugin_new(
+    kind: str = typer.Option(
+        ...,
+        "--kind",
+        help=f"Plugin kind. One of: {', '.join(sorted(TEMPLATES))}",
+    ),
+    name: str = typer.Option(
+        ...,
+        "--name",
+        help="Plugin name (PyPI-style, e.g. 'my-decepticon-plugin').",
+    ),
+    path: Path = typer.Option(
+        ...,
+        "--path",
+        help="Target directory. Created if absent.",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Overwrite existing files in --path.",
+    ),
+) -> None:
+    """Scaffold a new Decepticon plugin package."""
+    if kind not in TEMPLATES:
+        raise typer.BadParameter(f"unknown --kind={kind!r}; expected one of {sorted(TEMPLATES)}")
+    template = TEMPLATES[kind]
+    module_name = _normalize_module_name(name)
+
+    target = path.resolve()
+    src_dir = target / "src" / module_name
+    pyproject_path = target / "pyproject.toml"
+    readme_path = target / "README.md"
+    init_path = src_dir / "__init__.py"
+
+    if not force and pyproject_path.exists():
+        raise typer.BadParameter(f"{pyproject_path} already exists; pass --force to overwrite")
+
+    src_dir.mkdir(parents=True, exist_ok=True)
+
+    pyproject_path.write_text(
+        pyproject_for(
+            plugin_name=name,
+            module_name=module_name,
+            group=template.entry_point_group,
+        ),
+        encoding="utf-8",
+    )
+    readme_path.write_text(
+        template.readme_body.format(
+            plugin_name=name,
+            kind=kind,
+            entry_point_group=template.entry_point_group,
+        ),
+        encoding="utf-8",
+    )
+    init_path.write_text(
+        template.module_body.format(plugin_name=module_name),
+        encoding="utf-8",
+    )
+
+    typer.echo(f"created decepticon plugin '{name}' (kind={kind}) at {target}")
+    typer.echo(f"  pyproject:    {pyproject_path.relative_to(target.parent)}")
+    typer.echo(f"  module:       {init_path.relative_to(target.parent)}")
+    typer.echo(f"  entry-point:  {template.entry_point_group}")
+    typer.echo("")
+    typer.echo("Next steps:")
+    typer.echo(
+        f"  cd {target.relative_to(Path.cwd()) if target.is_relative_to(Path.cwd()) else target}"
+    )
+    typer.echo("  uv build")
+    typer.echo("  pip install dist/*.whl")
+
+
+if __name__ == "__main__":
+    app()

decepticon_sdk-1.1.2/decepticon_sdk/scaffold/templates.py

@@ -0,0 +1,250 @@
+"""Inline templates for the ``decepticon-sdk plugin new`` scaffolder.
+
+Each plugin ``kind`` maps to a ``ScaffoldTemplate`` that knows the
+entry-point group, the stub module body, and the README copy. Inline
+templates (no Jinja2) keep the SDK install lean — string ``.format()``
+covers everything the scaffolder needs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ScaffoldTemplate:
+    """One plugin-kind scaffold spec."""
+
+    kind: str
+    entry_point_group: str
+    module_body: str
+    readme_body: str
+
+
+_TOOL_BODY = '''"""Custom tool contributed to Decepticon."""
+
+from __future__ import annotations
+
+from decepticon_sdk import ToolProtocol
+
+
+class HelloTool:
+    """Minimal ToolProtocol-compliant tool."""
+
+    name = "{plugin_name}"
+    description = "Hello-world tool scaffolded by decepticon-sdk."
+
+    def invoke(self, input: object, *, config: object | None = None) -> object:
+        del config
+        return f"hello from {{self.name}}: {{input}}"
+
+
+def get_tools(role: str | None = None, **_: object) -> list[ToolProtocol]:
+    """Plugin factory called by the framework's tool loader."""
+    del role
+    return [HelloTool()]
+'''
+
+
+_MIDDLEWARE_BODY = '''"""Custom middleware contributed to Decepticon."""
+
+from __future__ import annotations
+
+from decepticon_sdk import MiddlewareProtocol, MiddlewareSlot
+
+
+class HelloMiddleware:
+    """Minimal MiddlewareProtocol-compliant middleware."""
+
+    name = "{plugin_name}"
+    slot: MiddlewareSlot | str = MiddlewareSlot.SKILLS
+    priority = 150
+
+    def wrap_model_call(self, state: object, runtime: object, config: object) -> object:
+        return state
+
+
+def get_middleware(role: str | None = None, **_: object) -> list[MiddlewareProtocol]:
+    """Plugin factory called by the framework's middleware loader."""
+    del role
+    return [HelloMiddleware()]
+'''
+
+
+_AGENT_BODY = '''"""Custom agent contributed to Decepticon."""
+
+from __future__ import annotations
+
+
+def get_agent() -> object:
+    """Plugin factory returning a compiled agent (LangGraph CompiledGraph).
+
+    Replace this stub with your real agent construction — see
+    ``decepticon.agents.standard.recon.create_recon_agent`` for an
+    example of the framework's factory pattern.
+    """
+    raise NotImplementedError(
+        "{plugin_name}: replace get_agent() with your compiled-graph factory"
+    )
+
+
+# LangGraph platform discovers ``graph`` as the module-level attribute.
+graph = None
+'''
+
+
+_CALLBACK_BODY = '''"""Custom callback handler contributed to Decepticon."""
+
+from __future__ import annotations
+
+
+class HelloCallback:
+    """Minimal CallbackProtocol-compliant handler."""
+
+    def on_llm_start(self, *args: object, **kwargs: object) -> None:
+        return None
+
+    def on_llm_end(self, *args: object, **kwargs: object) -> None:
+        return None
+
+    def on_tool_start(self, *args: object, **kwargs: object) -> None:
+        return None
+
+    def on_tool_end(self, *args: object, **kwargs: object) -> None:
+        return None
+
+
+def get_callbacks(role: str | None = None, **_: object) -> list[HelloCallback]:
+    """Plugin factory called by the framework's callback loader."""
+    del role
+    return [HelloCallback()]
+'''
+
+
+_SKILL_BODY = '''"""Skill source paths contributed by this plugin.
+
+The framework reads ``/skills/<bundle>/<role>/`` paths via the
+``SkillsMiddleware``. Plugins ship skill markdown files as package data
+and register the path prefix here.
+"""
+
+from __future__ import annotations
+
+
+def get_skill_sources(role: str | None = None) -> list[str]:
+    """Plugin factory called by the framework's skill loader."""
+    del role
+    return ["/skills/{plugin_name}/"]
+'''
+
+
+_PROMPT_BODY = '''"""Prompt fragments contributed to one or more roles."""
+
+from __future__ import annotations
+
+from decepticon_sdk import PromptContribution
+
+
+def get_contribution() -> PromptContribution:
+    """Plugin factory called by the framework's prompt loader."""
+    return PromptContribution(
+        fragments={{"recon": "<{plugin_name}>...</{plugin_name}>"}},
+        mode="append",
+        roles=("recon",),
+    )
+'''
+
+
+_README_TEMPLATE = """# {plugin_name}
+
+A Decepticon plugin ({kind}) scaffolded by ``decepticon-sdk plugin new``.
+
+## Build + install
+
+```bash
+uv build
+pip install dist/*.whl
+```
+
+After install, the framework's plugin loader discovers this contribution
+via the ``{entry_point_group}`` entry-point group.
+
+## Test
+
+```bash
+pip install decepticon-sdk[testing]
+pytest
+```
+
+Use ``decepticon_sdk.testing.FakeBackend`` / ``FakeLLM`` / ``FakeSandbox``
+to write hermetic tests that don't need a live framework.
+"""
+
+
+TEMPLATES: dict[str, ScaffoldTemplate] = {
+    "tool": ScaffoldTemplate(
+        kind="tool",
+        entry_point_group="decepticon.tools",
+        module_body=_TOOL_BODY,
+        readme_body=_README_TEMPLATE,
+    ),
+    "middleware": ScaffoldTemplate(
+        kind="middleware",
+        entry_point_group="decepticon.middleware",
+        module_body=_MIDDLEWARE_BODY,
+        readme_body=_README_TEMPLATE,
+    ),
+    "agent": ScaffoldTemplate(
+        kind="agent",
+        entry_point_group="decepticon.agents",
+        module_body=_AGENT_BODY,
+        readme_body=_README_TEMPLATE,
+    ),
+    "callback": ScaffoldTemplate(
+        kind="callback",
+        entry_point_group="decepticon.callbacks",
+        module_body=_CALLBACK_BODY,
+        readme_body=_README_TEMPLATE,
+    ),
+    "skill": ScaffoldTemplate(
+        kind="skill",
+        entry_point_group="decepticon.skills",
+        module_body=_SKILL_BODY,
+        readme_body=_README_TEMPLATE,
+    ),
+    "prompt": ScaffoldTemplate(
+        kind="prompt",
+        entry_point_group="decepticon.prompts",
+        module_body=_PROMPT_BODY,
+        readme_body=_README_TEMPLATE,
+    ),
+}
+
+
+def pyproject_for(*, plugin_name: str, module_name: str, group: str) -> str:
+    """Return a buildable pyproject.toml for the scaffolded plugin."""
+    return f"""[project]
+name = "{plugin_name}"
+version = "0.0.1"
+description = "Decepticon plugin scaffolded by decepticon-sdk."
+readme = "README.md"
+license = {{ text = "Apache-2.0" }}
+requires-python = ">=3.13"
+
+dependencies = [
+    "decepticon-sdk",
+]
+
+[project.entry-points."{group}"]
+{module_name} = "{module_name}"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{module_name}"]
+"""
+
+
+__all__ = ["TEMPLATES", "ScaffoldTemplate", "pyproject_for"]