Skip to content
Merged
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
2 changes: 2 additions & 0 deletions .serena/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
/cache
/project.local.yml
187 changes: 187 additions & 0 deletions .serena/project.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,187 @@
# the name by which the project can be referenced within Serena/when chatting with the LLM.
project_name: "agentship"

# list of language servers to start when using the LSP backend; choose from:
# ada al angular ansible astro
# bash bsl clojure cpp cpp_ccls
# crystal csharp csharp_omnisharp cue dart
# deno elixir elm erlang fortran
# fsharp gdscript gleam go groovy
# haskell haxe hlsl html java
# json julia julia_fatou kotlin latex
# lean4 lua lua_emmylua luau markdown
# matlab msl nextflow nix ocaml
# pascal perl php php_devsense php_phpactor
# php_phpantom powershell python python_basedpyright python_jedi
# python_pyrefly python_ty qml r rego
# ruby ruby_solargraph rust scala scss
# solidity svelte swift systemverilog terraform
# toml typescript typescript_vts vue wolfram
# yaml zig
# (This list may be outdated; generated with scripts/print_language_list.py;
# For the current list, see values of the LanguageServerId enum here:
# https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py)
# For some languages, there are several alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
# Note:
# - For C, use cpp
# - For JavaScript, use typescript
# - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root)
# - For Astro projects, use astro (subsumes typescript/javascript for .astro projects; requires npm)
# - For Svelte projects, use svelte (subsumes typescript/javascript for .svelte projects; requires npm)
# - For Deno projects, use deno (serves the same .ts/.js files as typescript; requires the deno CLI on PATH)
# - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three)
# - For Free Pascal/Lazarus, use pascal
# - External Python adapters may add further registered IDs; install the adapter package first
# and then use its ID here, for example: example
# Special requirements:
# Some language servers require additional setup/installations.
# See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
# When using multiple language servers, the first language server that supports a given file will be used for that file.
# The first language server is the default language and the respective language server will be used as a fallback.
# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
language_servers:
- python

# the encoding used by text files in the project
# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
encoding: "utf-8"

# optional shell command to run before the language backend (LSP or JetBrains) is initialised.
# the command runs in the project root directory and is only executed if the project is trusted
# (see trusted_project_path_patterns in the global configuration).
# serena waits for the command to exit: a non-zero exit code is logged as an error but does not
# abort activation. a per-project timeout (activation_command_timeout, default 180s) is the safety
# backstop for non-terminating commands; on expiry the process is killed and activation continues.
# example: activation_command: "npx nx run-many -t build"
activation_command:

# maximum time in seconds to wait for activation_command to complete before killing it (default 180s).
# must be a positive number.
activation_command_timeout: 180.0

# line ending convention to use when writing source files.
# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
line_ending:

# The language backend to use for this project.
# If not set, the global setting from serena_config.yml is used.
# Valid values: LSP, JetBrains
# Note: the backend is fixed at startup. If a project with a different backend
# is activated post-init, an error will be returned.
language_backend:

# The interface through which the agent (LLM) accesses Serena's functionality (overrides the global setting).
# Valid values: tools, REPL (see the global configuration for details); leave empty to use the global setting.
# Note: the interface is fixed at startup. If a project is activated post-init, its setting is not applied.
agent_interface:

# whether to use project's .gitignore files to ignore files
ignore_all_files_in_gitignore: true

# advanced configuration option allowing to configure language server-specific options.
# Maps the language key to the options.
# The settings are considered only if the project is trusted (see global configuration to define trusted projects).
# See https://oraios.github.io/serena/02-usage/050_configuration.html#language-server-specific-settings
ls_specific_settings: {}

# list of workspace folder paths (LSP backend only).
# These folders will be used to build up Serena's symbol index.
# Paths must be within the project root and should thus be relative to the project root.
# Furthermore, the paths should not be filtered by ignore settings.
# Default setting: The entire project root folder (".") is considered.
# In (large) monorepos, this can be used to index only subfolders of the project root, e.g.
# ls_workspace_folders:
# - "./subproject1"
# - "./subproject2"
ls_workspace_folders:
- "."

# list of additional workspace folder paths for cross-package reference support.
# Paths can be absolute or relative to the project root.
# Each folder is registered as an LSP workspace folder, enabling language servers to discover
# symbols and references across package boundaries, but these folders are not indexed by Serena,
# i.e. the respective symbols will not be found using Serena's symbol search tools.
# Example:
# additional_workspace_folders:
# - ../sibling-package
# - ../shared-lib
ls_additional_workspace_folders: []

# list of additional paths to ignore in this project.
# Same syntax as gitignore, so you can use * and **.
# Important: quote patterns that start with `*`, otherwise YAML treats them as aliases.
# Example:
# ignored_paths:
# - "examples/**"
# - ".worktrees/**"
# - "**/bin/**"
# - "**/obj/**"
# Note: global ignored_paths from serena_config.yml are also applied additively.
ignored_paths: []

# whether the project is in read-only mode
# If set to true, all editing tools will be disabled and attempts to use them will result in an error
# Added on 2025-04-18
read_only: false

# list of tool names to exclude.
# This extends the existing exclusions (e.g. from the global configuration)
# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
excluded_tools: []

# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
# This extends the existing inclusions (e.g. from the global configuration).
# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
included_optional_tools: []

# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
# This cannot be combined with non-empty excluded_tools or included_optional_tools.
# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
fixed_tools: []

# list of APIs (facades or facade methods, e.g. "lsp" or "lsp.find_symbol") to exclude from the REPL.
# This extends the existing exclusions (e.g. from the global configuration).
excluded_apis: []

# list of APIs (facades or facade methods, e.g. "lsp" or "lsp.get_diagnostics_for_symbol") to include in the REPL
# that would otherwise be disabled (particularly optional methods, which are disabled by default).
# This extends the existing inclusions (e.g. from the global configuration).
included_apis: []

# list of mode names that are to be activated by default, overriding the setting in the global configuration.
# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
# for this project.
# This setting can, in turn, be overridden by CLI parameters (--mode).
# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
default_modes:

# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
added_modes:

# initial prompt for the project. It will always be given to the LLM upon activating the project
# (contrary to the memories, which are loaded on demand).
initial_prompt: ""

# time budget (seconds) per tool call for the retrieval of additional symbol information
# such as docstrings or parameter information.
# This overrides the corresponding setting in the global configuration; see the documentation there.
# If null or missing, use the setting from the global configuration.
symbol_info_budget:

# list of regex patterns which, when matched, mark a memory entry as read‑only.
# Extends the list from the global configuration, merging the two lists.
read_only_memory_patterns: []

# list of regex patterns for memories to completely ignore.
# Matching memories will not appear in list_memories or activate_project output
# and cannot be accessed via read_memory or write_memory.
# To access ignored memory files, use the read_file tool on the raw file path.
# Extends the list from the global configuration, merging the two lists.
# Example: ["_archive/.*", "_episodes/.*"]
ignored_memory_patterns: []
31 changes: 22 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<p align="center">
<img src="branding/banners/github-readme-banner@3x.png" alt="AgentShip – production plumbing for AI agents, without the rewrite" width="100%">
<img src="branding/banner/github-readme-banner@2x.png" alt="AgentShip — production plumbing for AI agents, without the rewrite" width="100%">
</p>

<p align="center">
Expand All @@ -8,12 +8,20 @@
</p>

<p align="center">
<a href="https://pypi.org/project/agentship-sdk/"><img src="https://img.shields.io/pypi/v/agentship-sdk?style=flat&color=3776AB" alt="PyPI"></a>
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat&logo=python&logoColor=white" alt="Python 3.13+"></a>
<a href="https://www.langchain.com/langgraph"><img src="https://img.shields.io/badge/LangGraph-engine-121212?style=flat&logo=langchain&logoColor=white" alt="LangGraph"></a>
<a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-tools-FF6B35?style=flat" alt="MCP"></a>
<a href="https://opentelemetry.io/"><img src="https://img.shields.io/badge/OpenTelemetry-tracing-425CC7?style=flat&logo=opentelemetry&logoColor=white" alt="OpenTelemetry"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-yellow.svg" alt="License: Apache 2.0"></a>
<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>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-A685EE?labelColor=0D1317" alt="License: Apache 2.0"></a>
</p>

<p align="center">
<a href="https://agent-ship.dev"><b>agent-ship.dev</b></a> ·
<a href="docs">Docs</a> ·
<a href="examples">Examples</a> ·
<a href="deploy/RAILWAY.md">Deploy</a> ·
<a href="postman">Postman</a>
</p>

---
Expand Down Expand Up @@ -154,7 +162,7 @@ adapter is the single place that does — so replacing LangGraph is one package,
no key, which is why the conformance matrix can tell a capability an engine *declares* from one
it actually *has*.

**Not in this picture, because it is not built yet:** voice, long-term memory, guardrails/PII,
**Not in this picture, because it is not built yet:** long-term memory, guardrails/PII,
sandboxing, evals, and the ADK / Pydantic AI adapters. See [Status](#status).

---
Expand Down Expand Up @@ -273,7 +281,7 @@ agentship db upgrade # apply checkpoint migrations (gated)
## Status

**Early — `0.x`, so the API can change between minor versions.** Pin exactly if that matters
to you (`agentship-sdk==0.0.2`, the latest on PyPI). The next release will be `0.0.3`; see
to you (`agentship-sdk==0.0.4`, the latest on PyPI). See
[RELEASING](docs/RELEASING.md#versioning).

> **`0.0.1` is yanked.** It reserved the six names on PyPI but could not run an agent —
Expand All @@ -293,3 +301,8 @@ before anything is called done. Test first, one task per commit, CI green — se
## Licence

[Apache 2.0](LICENSE).

The fonts vendored under [`branding/fonts/`](branding/fonts/) and `docs/assets/fonts/` are
redistributed under the SIL Open Font License 1.1, with each licence kept beside them. The
AgentShip name and logo are project trademarks, which Apache 2.0 does not grant rights to — see
[`branding/README.md`](branding/README.md#licensing).
75 changes: 75 additions & 0 deletions branding/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# AgentShip branding

The canonical copy of the AgentShip brand kit, vendored here so the README, the docs site and
Studio all draw on one set of files. The upstream kit (`agentship-brand-kit`) carries the full
guidelines in `BRAND.md`; this file covers what lives here and which file to reach for.

## Layout

```
logo/svg/ vector logos — use these first
logo/png/ raster exports, app icons, apple-touch-icon
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)
```

## Which logo

| Place | File |
|---|---|
| Dark background — README banner, Studio, docs dark mode | `logo/svg/agentship-lockup-horizontal-on-dark.svg`, `agentship-mark-on-dark.svg` |
| Light background — PyPI, slides, print | `logo/svg/agentship-lockup-horizontal-on-light.svg`, `agentship-mark-on-light.svg` |
| One-colour contexts — stamps, small badges | `agentship-mark-mono-black.svg`, `agentship-mark-mono-white.svg` |
| Square or centred layouts | `logo/svg/agentship-lockup-stacked-*.svg` |
| App icon, PWA, store listings | `logo/png/agentship-app-icon-{1024,512,192}.png` |
| iOS home screen | `logo/png/apple-touch-icon-180.png` |
| Browser tab | `logo/svg/favicon.svg`, with `logo/favicon.ico` as fallback |

The wordmark in the SVG lockups is outlined, so a lockup renders correctly without the display
font installed.

## Where these are consumed

- `README.md` — `branding/banner/github-readme-banner@2x.png`
- Docs site — `docs/assets/` (mark, favicon), `docs/assets/fonts/`, `docs/stylesheets/agentship.css`,
wired up in `mkdocs.yml`
- Studio — palette and favicon are inlined in
`packages/agentship-service/src/agentship_service/static/studio.html`, which is deliberately a
single no-build file, so it carries the token *values* rather than importing `tokens/tokens.css`

Copies under `docs/` are copies on purpose: MkDocs only publishes what is inside `docs_dir`. If a
token value changes here, update `docs/stylesheets/agentship.css` and Studio's `:root` block too.

## Rules worth repeating

- The accent `#A685EE` is one colour, for emphasis: the mark's top block, links, focus rings,
active states. Never a large background fill. On light backgrounds use `#6A47C2` instead — the
dark-mode accent does not carry enough contrast as text on Paper.
- No pure white text (use Fog `#E8EEF0`), no pure black ground (use Ink `#0D1317`).
- No gradients, glows, or emoji.
- Do not recolour, rotate, stretch, outline or shadow the mark, rearrange its blocks, or set the
wordmark in another typeface. Clearspace: one container block (~16% of mark height) all round.
Minimum size: mark 16px, horizontal lockup 96px wide.

## Licensing

The AgentShip source is Apache 2.0 (see [`../LICENSE`](../LICENSE)). The fonts vendored in
`fonts/` are **not** ours and are redistributed under the SIL Open Font License 1.1, with each
licence kept beside them:

| Font | Licence |
|---|---|
| Bricolage Grotesque | [`fonts/LICENSE-bricolage-grotesque.txt`](fonts/LICENSE-bricolage-grotesque.txt) |
| Instrument Sans | [`fonts/LICENSE-instrument-sans.txt`](fonts/LICENSE-instrument-sans.txt) |
| JetBrains Mono | [`fonts/LICENSE-jetbrains-mono.txt`](fonts/LICENSE-jetbrains-mono.txt) |

The same three licence files sit in `docs/assets/fonts/`, next to the copies the docs site serves.
Keep a licence file with any copy of the fonts you make — the OFL requires it.

The AgentShip name, wordmark, mark and logo files are project trademarks rather than code. Apache
2.0 grants no trademark rights (section 6). Use them to refer to or link to AgentShip; do not use
them as the identity of a fork, or modified, for a derivative product.
Binary file added branding/banner/github-readme-banner.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added branding/banner/github-readme-banner@2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added branding/banner/github-social-preview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed branding/banners/docs-header.png
Binary file not shown.
Binary file removed branding/banners/docs-header@2x.png
Binary file not shown.
Binary file removed branding/banners/docs-header@3x.png
Binary file not shown.
Binary file removed branding/banners/github-banner.png
Binary file not shown.
Binary file removed branding/banners/github-banner@2x.png
Binary file not shown.
Binary file removed branding/banners/github-banner@3x.png
Binary file not shown.
Binary file removed branding/banners/github-readme-banner.png
Binary file not shown.
Binary file removed branding/banners/github-readme-banner@2x.png
Binary file not shown.
Binary file removed branding/banners/github-readme-banner@3x.png
Binary file not shown.
Binary file removed branding/banners/linkedin-banner.png
Binary file not shown.
Binary file removed branding/banners/linkedin-banner@2x.png
Binary file not shown.
Binary file removed branding/banners/linkedin-banner@3x.png
Binary file not shown.
Binary file removed branding/banners/social-preview.png
Binary file not shown.
Binary file removed branding/banners/social-preview@2x.png
Binary file not shown.
Binary file removed branding/banners/social-preview@3x.png
Binary file not shown.
Binary file removed branding/banners/substack-banner.png
Binary file not shown.
Binary file removed branding/banners/substack-banner@2x.png
Binary file not shown.
Binary file removed branding/banners/substack-banner@3x.png
Binary file not shown.
Binary file removed branding/favicons/favicon-128.png
Binary file not shown.
Binary file removed branding/favicons/favicon-16.png
Binary file not shown.
Binary file removed branding/favicons/favicon-180.png
Binary file not shown.
Binary file removed branding/favicons/favicon-192.png
Binary file not shown.
Binary file removed branding/favicons/favicon-256.png
Diff not rendered.
Binary file removed branding/favicons/favicon-32.png
Diff not rendered.
Binary file removed branding/favicons/favicon-48.png
Diff not rendered.
Binary file removed branding/favicons/favicon-512.png
Diff not rendered.
Binary file removed branding/favicons/favicon-64.png
Diff not rendered.
Loading
Loading