flagship_author

Flagship author rule

Applies when you're adding or editing anything under flagships/<name>/.

File layout (enforced)

flagships/<name>/
├── pyproject.toml            # [project.scripts] entrypoint ks-cookbook-<slug>
├── README.md                 # title, tags, seed-data block, walkthrough
├── src/<module>/
│   ├── __main__.py           # argparse → agent.draft_*()
│   ├── agent.py              # pydantic-ai Agent + system prompt + MCP wiring
│   └── schema.py             # pydantic output model with Citation field(s)
└── sample_inputs/            # at least one concrete example input

Don't create additional top-level files inside the flagship unless there's a specific reason.

README template (required sections, in this order)

# <Vertical>: <Flagship Name>

**Tags:** `vertical` `subdomain` `framework`

<one-paragraph what-and-why>

## Seed data required

This demo reads from a folder in your Knowledge Stack tenant. You need to create
that folder and upload the expected documents **before** running.

**Expected corpus:** <one-line description>

Set-up steps:
1. Sign up at [app.knowledgestack.ai](https://app.knowledgestack.ai).
2. Create a folder in the dashboard and copy its folder ID.
3. Upload the documents described above.
4. Issue an API key from the dashboard and put it in `.env` as `KS_API_KEY`.
5. Run: `<CORPUS_FOLDER_ID=<id> make demo-<slug>>`

Full corpus matrix: [`https://github.com/knowledgestack/ks-cookbook/wiki/seed-data`](https://github.com/knowledgestack/ks-cookbook/wiki/seed-data).

## Run
<make command + override examples>

## Framework
<pydantic-ai | LangGraph | raw-OpenAI | raw-Anthropic | CrewAI | …>

## Bring your own data
<short note on pointing the demo at a different folder>

Agent wiring (copy this shape)

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio
from .schema import Memo

SYSTEM_TEMPLATE = """..."""  # include the four prompt invariants

async def draft(*, corpus_folder_id: str, model: str, ...) -> Memo:
    mcp = MCPServerStdio(
        command=os.environ.get("KS_MCP_COMMAND", "uvx"),
        args=(os.environ.get("KS_MCP_ARGS", "knowledgestack-mcp") or "").split(),
        env={"KS_API_KEY": os.environ["KS_API_KEY"],
             "KS_BASE_URL": os.environ.get("KS_BASE_URL", "")},
    )
    agent = Agent(
        model=f"openai:{model}",
        mcp_servers=[mcp],
        system_prompt=SYSTEM_TEMPLATE.replace("__CORPUS_FOLDER_ID__", corpus_folder_id),
        output_type=Memo,
    )
    async with agent.run_mcp_servers():
        result = await agent.run(user_prompt)
    return result.output