Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 35 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,17 @@
</p>

<p align="center">
<a href="https://pypi.org/project/agentship-sdk/"><img src="https://img.shields.io/pypi/v/agentship-sdk?label=PyPI&color=A685EE&labelColor=0D1317" alt="PyPI"></a>
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.13%2B-A685EE?labelColor=0D1317&logo=python&logoColor=E8EEF0" alt="Python 3.13+"></a>
<a href="https://www.langchain.com/langgraph"><img src="https://img.shields.io/badge/LangGraph-engine-A685EE?labelColor=0D1317&logo=langchain&logoColor=E8EEF0" alt="LangGraph"></a>
<a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-tools-A685EE?labelColor=0D1317" alt="MCP"></a>
<a href="https://opentelemetry.io/"><img src="https://img.shields.io/badge/OpenTelemetry-traces-A685EE?labelColor=0D1317&logo=opentelemetry&logoColor=E8EEF0" alt="OpenTelemetry"></a>
<!--
Ours are violet, so the accent still reads as "AgentShip"; the stack badges keep each
tool's own recognisable colour. Every badge shares labelColor=0D1317 (Ink), which is what
holds the row together. Six identical accent pills was the previous version, and it spent
the accent on everything, which is the same as spending it on nothing.
-->
<a href="https://pypi.org/project/agentship-sdk/"><img src="https://img.shields.io/pypi/v/agentship-sdk?label=PyPI&color=A685EE&labelColor=0D1317&logo=pypi&logoColor=E8EEF0" alt="PyPI"></a>
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.13%2B-3776AB?labelColor=0D1317&logo=python&logoColor=E8EEF0" alt="Python 3.13+"></a>
<a href="https://www.langchain.com/langgraph"><img src="https://img.shields.io/badge/LangGraph-engine-1C3C3C?labelColor=0D1317&logo=langchain&logoColor=E8EEF0" alt="LangGraph"></a>
<a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-tools-D97757?labelColor=0D1317&logo=modelcontextprotocol&logoColor=E8EEF0" alt="MCP"></a>
<a href="https://opentelemetry.io/"><img src="https://img.shields.io/badge/OpenTelemetry-traces-425CC7?labelColor=0D1317&logo=opentelemetry&logoColor=E8EEF0" alt="OpenTelemetry"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-A685EE?labelColor=0D1317" alt="License: Apache 2.0"></a>
</p>

Expand Down Expand Up @@ -41,10 +47,6 @@ you need something it lacks, you are rewriting.
> carries traces. We reimplement none of them — we wire them together and add the plumbing
> none of them ship.

<p align="center">
<img src="branding/hero/image.png" alt="AgentShip architecture" width="100%">
</p>

---

## Quick start
Expand Down Expand Up @@ -112,25 +114,36 @@ a kernel that imports no vendor library. Everything below is in the tree today
are seams with a contract and one implementation, not roadmap.

```mermaid
%%{init: {"theme":"base","themeVariables":{
"primaryColor":"#141C22","primaryTextColor":"#E8EEF0","primaryBorderColor":"#2A3944",
"lineColor":"#55656E","textColor":"#C9D5DB",
"clusterBkg":"#0D1317","clusterBorder":"#243039",
"edgeLabelBackground":"#141C22","tertiaryColor":"#141C22",
"fontFamily":"ui-sans-serif, system-ui, -apple-system, sans-serif","fontSize":"14px"
}}}%%
flowchart TB
classDef spec fill:#fef3c7,stroke:#b45309,stroke-width:2px,color:#7c2d12
classDef system fill:#ccfbf1,stroke:#0f766e,stroke-width:2.5px,color:#134e4a
classDef adapter fill:#dcfce7,stroke:#15803d,stroke-width:1.5px,color:#14532d
classDef ext fill:#f1f5f9,stroke:#64748b,stroke-width:1.5px,color:#334155
classDef obs fill:#dbeafe,stroke:#1e40af,stroke-width:1.5px,color:#1e3a8a
%% Brand palette. Every node is Panel (#141C22) with Fog text; only the STROKE carries
%% meaning, so the accent is spent once — on the kernel, which is what the diagram argues
%% for. Previously five pastel fills (amber, mint, green, slate, blue) rendered this as a
%% bright light-mode block in the middle of a dark-branded README.
classDef spec fill:#141C22,stroke:#34454F,stroke-width:1.5px,color:#E8EEF0
classDef system fill:#141C22,stroke:#A685EE,stroke-width:2px,color:#E8EEF0
classDef adapter fill:#141C22,stroke:#5CCFC0,stroke-width:1.5px,color:#E8EEF0
classDef ext fill:#141C22,stroke:#34454F,stroke-width:1px,color:#9FB0B9
classDef obs fill:#141C22,stroke:#34454F,stroke-width:1.5px,color:#C9D5DB

SPEC["<b>agent.yaml</b><br/><i>[AgentSpec]</i><br/>name · engine · prompt<br/>tools · members"]:::spec

CLI["<b>agentship-cli</b><br/><i>[Entry point]</i><br/>run · serve · doctor · verify"]:::spec
SVC["<b>agentship-service</b><br/><i>[FastAPI]</i><br/>:invoke :resume :stream<br/>WS /live · /a2a · Studio"]:::spec

subgraph CORE["agentship-core — imports no vendor library"]
subgraph CORE["agentship-core · imports no vendor"]
RT["<b>RunnableAgent</b><br/><i>[Runtime]</i><br/>one turn: run / stream / resume"]:::system
SEAM["<b>Seams</b><br/><i>[Contracts]</i><br/>auth · tenancy · tools<br/>observability · A2A"]:::system
CONF["<b>Conformance matrix</b><br/><i>[Build gate]</i><br/>fails on a capability<br/>declared but not held"]:::system
end

subgraph ENG["engine adapters — the only code that names a vendor"]
subgraph ENG["engine adapters"]
ECHO["<b>echo</b><br/><i>[Engine]</i><br/>no provider, no network"]:::adapter
LG["<b>langgraph</b><br/><i>[Engine]</i><br/>single · graph · autonomous"]:::adapter
end
Expand All @@ -153,6 +166,12 @@ flowchart TB
LG --> X2
LG --> X3
CORE -->|emits spans| OBS

%% The three containers, matching their contents: accent for the kernel, teal for the
%% adapters, dim for what we consume and never reimplement.
style CORE fill:#0D1317,stroke:#A685EE,stroke-width:1px
style ENG fill:#0D1317,stroke:#5CCFC0,stroke-width:1px
style EXT fill:#0D1317,stroke:#243039,stroke-width:1px
```

**Read it in one line:** your spec never names a vendor, the kernel never imports one, and the
Expand Down
Binary file removed branding/Architecture.png
Binary file not shown.
10 changes: 8 additions & 2 deletions branding/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,16 @@ logo/favicon.ico 16/32/48
banner/ 1280x400 README banner (@2x) and 1280x640 social preview
fonts/ self-hosted woff2/woff + fonts.css (SIL OFL — see Licensing)
tokens/ tokens.json, tokens.css, tailwind.preset.js, mkdocs-agentship.css
hero/image.png architecture illustration used in the README (a diagram, not a logo)
Architecture.png architecture illustration (a diagram, not a logo)
```

Two architecture illustrations used to live here, `hero/image.png` and `Architecture.png`.
Both are gone. They predated the rebuild and showed a system that does not exist — Google ADK,
OpenAI SDK and CrewAI as engines, a memory layer with vector stores, guardrails, eval datasets,
LLM-as-judge — and each carried a different old wordmark, one of them with a glow. The README's
architecture picture is now the Mermaid diagram in the README itself, which is generated from
the same facts the rest of the page is held to. If a raster diagram is needed again, draw it
from `tokens/` and keep it in step with that one.

## Which logo

| Place | File |
Expand Down
Binary file removed branding/hero/image.png
Binary file not shown.
16 changes: 16 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,22 @@ they were written before the project cut tagged releases.
## [Unreleased]

### Changed
- **The README's own picture advertised four things AgentShip cannot do.** `branding/hero/image.png`
sat directly under "The problem" and showed Google ADK, OpenAI SDK and CrewAI as engines, plus
Memory and Guardrails as components — against a README that states a few sections later that
none of those are built. It also carried the pre-rebuild wordmark with a glow. It is deleted,
along with the unreferenced `branding/Architecture.png`, which showed a third wordmark and an
ADK sidecar, a vector-store memory layer, eval datasets and LLM-as-judge. The architecture
picture is now only the Mermaid diagram, which is held to the same facts as the prose.
- **The badges were six identical violet pills, and the diagram was five pastel fills.** The
accent spent on everything is the accent spent on nothing, so the stack badges now carry each
tool's own colour over the shared Ink label, and the violet is kept for the two that are ours
(version, licence). The architecture diagram rendered as a bright light-mode block in the
middle of a dark-branded README; it is now Panel fills with Fog text, where only the border
carries meaning — the accent on the kernel, the code teal on the adapters. A Mermaid `init`
block sets the edge-label, cluster and line colours, which previously defaulted to light chips
and near-invisible arrows on a dark canvas. Checked by rendering it on both GitHub canvas
colours, which is also how the cluster titles were found to be colliding with their own nodes.
- **The project had two visual identities and no way to tell which was current.** `branding/`
carried a logo set that nothing in the tree referenced by the same name the README used, the
docs site was Material's stock teal with fonts fetched from Google, and Studio's tab icon was a
Expand Down
Loading