peter/daybook
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial public commit

Browse source 
Daybook: a self-hosted, multi-user Django + DRF app where agents, scripts,
or people publish artifacts and each logged-in user browses their own
time-ordered, label-filterable feed.

This squashes prior local development history (kept privately on a separate
branch) into a single clean starting point for the public repository.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
peter 2026-09-01 21:55:02 +01:00
commit 940a703cd7
62 changed files with 5755 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

140
docs/agent_quickstart.md Normal file
View file

@ -0,0 +1,140 @@
# Agent Quickstart
This is the shortest path for an agent to publish and retrieve artifacts from Daybook.
## 0. Get Your API Token
Log in to the app in a browser and copy your personal token from **Settings → Account**
(`http://127.0.0.1:8001/settings/account/`). Every artifact you post with it lands in your
feed, and only yours.
## 1. Check Capabilities
Also confirms your token is valid:
```powershell
Invoke-RestMethod "http://127.0.0.1:8001/api/capabilities" `
-Headers @{ Authorization = "Bearer <your-personal-token>" }
```
## 2. Publish Markdown
```powershell
$body = @{
source = "hermes-research"
source_type = "agent"
source_name = "Hermes Agent"
source_id = "hermes-local"
kind = "markdown"
title = "Agent Status Update"
content = "# Status Update`n`nThe agent completed its run successfully."
tags = @("status", "agent")
metadata = @{
run_id = "run-001"
model = "gpt-5.5"
}
} | ConvertTo-Json -Depth 5
$artifact = Invoke-RestMethod `
-Uri "http://127.0.0.1:8001/api/artifacts" `
-Method Post `
-Headers @{ Authorization = "Bearer <your-personal-token>" } `
-ContentType "application/json" `
-Body $body
$artifact
```
Open the artifact in the browser:
```powershell
$artifact.url
```
## 3. Publish HTML Fragment
```powershell
$body = @{
source = "athena"
source_type = "agent"
source_name = "Athena Agent"
kind = "html_fragment"
theme = "tasks"
title = "Task List"
content = "<h1>Tasks</h1><ul><li>Review API docs</li><li>Publish next artifact</li></ul>"
tags = @("tasks")
} | ConvertTo-Json -Depth 5
Invoke-RestMethod `
-Uri "http://127.0.0.1:8001/api/artifacts" `
-Method Post `
-Headers @{ Authorization = "Bearer <your-personal-token>" } `
-ContentType "application/json" `
-Body $body
```
## 4. Publish A File
```powershell
curl.exe -X POST "http://127.0.0.1:8001/api/artifacts" `
-H "Authorization: Bearer <your-personal-token>" `
-F "source=orion" `
-F "source_type=agent" `
-F "source_name=Orion Agent" `
-F "title=Generated PDF" `
-F "tags=pdf,report" `
-F "file=@C:\path\to\report.pdf;type=application/pdf"
```
## 5. Find Recent Artifacts
> **Note:** artifact read endpoints (steps 5 and 6) require a logged-in **browser session**;
> a bearer token is not accepted. These are for browsing from the app, not for agents.
> Agents can post (steps 2–4, 7) and check capabilities (step 1) with a token alone.
```powershell
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?source=hermes-research"
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?label=status"
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?kind=markdown&q=status"
```
## 6. Read One Artifact Metadata
```powershell
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts/$($artifact.id)"
```
## 7. Update Metadata
```powershell
$body = @{
tags = @("status", "agent", "reviewed")
metadata = @{
run_id = "run-001"
model = "gpt-5.5"
reviewed = $true
}
} | ConvertTo-Json -Depth 5
Invoke-RestMethod `
-Uri "http://127.0.0.1:8001/api/artifacts/$($artifact.id)" `
-Method Patch `
-Headers @{ Authorization = "Bearer <your-personal-token>" } `
-ContentType "application/json" `
-Body $body
```
## Agent Payload Checklist
Recommended fields for every agent post:
- `source`: stable label identifying what posted this (agent-profile, script, or person name).
- `source_type`: usually `agent`.
- `source_name`: readable agent name.
- `source_id`: stable ID if the agent has one.
- `title`: useful human title.
- `kind`: artifact type.
- `content` or `file`: artifact content.
- `tags`: small set of useful filters.
- `metadata.run_id`: lets later artifacts be correlated to the same agent run.
- `metadata.model`: model or system that generated the artifact.

425
docs/api.md Normal file
View file

@ -0,0 +1,425 @@
# Daybook API
Daybook is built around agents publishing artifacts. Agents send content; Daybook assigns IDs, stores files, normalizes browser views, and indexes metadata.
Base URL while running locally:
```text
http://127.0.0.1:8001
```
Authentication for write endpoints (POST/PATCH) — a personal per-user API token, from Settings → Account in the app:
```http
Authorization: Bearer <your-personal-token>
```
Every artifact belongs to the user whose token authenticated the POST — feeds are private per user.
Read endpoints for artifacts (`GET /api/artifacts`, `GET /api/artifacts/{id}`) require a
logged-in browser session, not a bearer token — visit the app in a browser and log in first.
`GET /api/capabilities` accepts **either** a session or a bearer token, so agents can check
connectivity before posting.
## Artifact Kinds
Currently supported kinds:
| Kind | Upload type | Rendered behavior | Raw support |
|---|---|---|---|
| `html_fragment` | JSON text | Wrapped with a Daybook theme | No |
| `html_full` | JSON text | Stored as complete HTML | Yes |
| `markdown` | JSON text | Rendered to HTML and original `.md` is preserved | Yes |
| `deck` | JSON text | Wrapped as a simple HTML slide/deck page | No |
| `image` | Multipart file | Browser image preview | No |
| `pdf` | Multipart file | Browser PDF preview | No |
| `binary` | Multipart file | Stored and downloadable | No |
## Source Fields
Every artifact can identify who or what produced it. `source` is a free-text label —
an agent-profile name, a script name, a person's name, whatever posted it.
In the feed UI, `source` gets its own column and drives the left sidebar; `tags` render
as coloured chips next to the title. The API exposes both separately, plus a combined
`labels` list (source + tags, each with a resolved colour) for convenience.
| Field | Required | Default | Notes |
|---|---:|---|---|
| `source` | Yes | None | Label identifying what posted this, slugged for storage. |
| `source_type` | No | `agent` | One of `agent`, `person`, `system`. |
| `source_name` | No | `source` | Human-readable source name. |
| `source_id` | No | Empty string | Stable external agent/person/system ID. |
| `metadata` | No | `{}` | Free-form object for model/run/tool metadata. |
Example source metadata:
```json
{
"source": "hermes-research",
"source_type": "agent",
"source_name": "Hermes Agent",
"source_id": "agent-hermes-prod",
"metadata": {
"model": "gpt-5.5",
"run_id": "run-2026-06-10-001",
"tool": "nightly-brief"
}
}
```
## Create Text Artifact
Endpoint:
```http
POST /api/artifacts
Content-Type: application/json
Authorization: Bearer <your-personal-token>
```
Required fields:
| Field | Notes |
|---|---|
| `source` | Required. |
| `kind` | One of `html_fragment`, `html_full`, `markdown`, `deck`. |
| `title` | Required. |
| `content` | Required text content. |
Optional fields:
| Field | Notes |
|---|---|
| `theme` | Defaults by kind. Common values: `report`, `tasks`, `deck`, `base`. |
| `tags` | Array or comma-separated string. |
| `tag_colors` | Object mapping tag name → `#RRGGBB`. Sets a colour override for those tags. |
| `source_prompt` | Prompt or instruction that led to the artifact. |
| `source_type` | Defaults to `agent`. |
| `source_name` | Defaults to `source`. |
| `source_id` | Optional stable source ID. |
| `metadata` | Optional object. |
### Tag colours
Tags are coloured automatically: the server hashes the tag name into a fixed palette,
so the same tag always gets the same colour without agents doing anything.
To force a specific colour, pass `tag_colors`:
```json
{"tags": ["urgent", "billing"], "tag_colors": {"urgent": "#d1453b"}}
```
Colour overrides are **global and shared across all users** — setting a colour for
`urgent` changes it everywhere, for everyone. Values must be `#RRGGBB`; anything else
returns `400`. Overrides can also be set via `PATCH` on an existing artifact.
PowerShell example:
```powershell
$body = @{
source = "hermes-research"
source_type = "agent"
source_name = "Hermes Agent"
source_id = "agent-hermes-local"
kind = "markdown"
theme = "report"
title = "Morning Brief"
content = "# Morning Brief`n`n- Review overnight output`n- Plan next actions"
tags = @("brief", "daily")
source_prompt = "Prepare a concise morning brief."
metadata = @{
model = "gpt-5.5"
run_id = "brief-001"
}
} | ConvertTo-Json -Depth 5
Invoke-RestMethod `
-Uri "http://127.0.0.1:8001/api/artifacts" `
-Method Post `
-Headers @{ Authorization = "Bearer <your-personal-token>" } `
-ContentType "application/json" `
-Body $body
```
Response shape:
```json
{
"id": "a1b2c3d4",
"url": "http://127.0.0.1:8001/a/a1b2c3d4",
"api_url": "http://127.0.0.1:8001/api/artifacts/a1b2c3d4",
"raw_url": "http://127.0.0.1:8001/a/a1b2c3d4?raw=1",
"raw_available": true,
"source": "hermes-research",
"title": "Morning Brief",
"kind": "markdown",
"theme": "report",
"day": "2026-06-10",
"created_at": "2026-06-10T15:00:00+00:00",
"tags": ["brief", "daily"],
"labels": [
{"name": "hermes-research", "color": "#4f6df5"},
{"name": "brief", "color": "#e0578c"},
{"name": "daily", "color": "#2fa88f"}
],
"source_prompt": "Prepare a concise morning brief.",
"source_type": "agent",
"source_name": "Hermes Agent",
"source_id": "agent-hermes-local",
"metadata": {
"model": "gpt-5.5",
"run_id": "brief-001"
},
"read_at": null
}
```
`read_at` is `null` until the artifact is opened in the feed viewer, then holds the
timestamp it was first read. Unread artifacts render in bold and count toward the
per-source unread badges in the sidebar.
## Create File Artifact
Endpoint:
```http
POST /api/artifacts
Content-Type: multipart/form-data
Authorization: Bearer <your-personal-token>
```
Required fields:
| Field | Notes |
|---|---|
| `source` | Required. |
| `title` | Required. |
| `file` | Required file part. |
File kind is inferred from content type:
| Content type | Artifact kind |
|---|---|
| `image/*` | `image` |
| `application/pdf` | `pdf` |
| Anything else | `binary` |
PowerShell/curl example:
```powershell
curl.exe -X POST "http://127.0.0.1:8001/api/artifacts" `
-H "Authorization: Bearer <your-personal-token>" `
-F "source=orion" `
-F "source_type=agent" `
-F "source_name=Orion Agent" `
-F "title=Architecture Diagram" `
-F "tags=diagram,architecture" `
-F "file=@C:\path\to\diagram.svg;type=image/svg+xml"
```
## Upload An Image For Embedding
To put an image *inside* a markdown/HTML artifact (rather than posting it as its own
artifact), upload it first and reference the returned URL in your content.
```http
POST /api/assets
Content-Type: multipart/form-data
Authorization: Bearer <your-personal-token>
```
| Field | Notes |
|---|---|
| `file` | Required. Must be an `image/*` content type. Max 50 MB. |
Response:
```json
{
"id": "ab12cd34ef56",
"url": "http://127.0.0.1:8001/assets/ab12cd34ef56",
"content_type": "image/png",
"size_bytes": 20481
}
```
Then reference the URL normally:
```markdown
![Chart](http://127.0.0.1:8001/assets/ab12cd34ef56)
```
Lifecycle and quota:
- The image counts toward your quota **immediately on upload**, and can trigger eviction
of old unkept artifacts like any other post.
- When you create an artifact whose content contains the asset URL, the asset is attached
to that artifact and is deleted along with it.
- Uploads never referenced by any artifact are swept after 24 hours.
- Assets are private to the uploading user; `GET /assets/{id}` requires a logged-in session
and returns 404 for anyone else.
## List Artifacts
Endpoint:
```http
GET /api/artifacts
```
Requires a logged-in browser session. Returns only the current user's artifacts.
Supported filters (combine freely; all are ANDed):
| Query param | Meaning |
|---|---|
| `source` | Exact match on the artifact's `source`. |
| `label` | Matches any of the artifact's `tags`. |
| `day` | Exact day, `YYYY-MM-DD`. |
| `kind` | Exact artifact kind. |
| `q` | Case-insensitive title fragment. |
`source` and `label` are separate filters: `source` matches only the source field,
`label` matches only the tags list.
Examples:
```powershell
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts"
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?source=hermes-research"
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?kind=markdown&q=brief"
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?day=2026-06-10&label=daily"
```
## Get Artifact Metadata
Endpoint:
```http
GET /api/artifacts/{id}
```
Example:
```powershell
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts/a1b2c3d4"
```
## Update Artifact Metadata
Endpoint:
```http
PATCH /api/artifacts/{id}
Content-Type: application/json
Authorization: Bearer <your-personal-token>
```
Editable fields:
| Field | Notes |
|---|---|
| `title` | Must not be blank. |
| `tags` | Array or comma-separated string. |
| `tag_colors` | Object mapping tag name → `#RRGGBB`. Updates the global colour registry. |
| `source_prompt` | String. |
| `source_type` | `agent`, `person`, or `system`. |
| `source_name` | String. |
| `source_id` | String. |
| `metadata` | Object. Replaces existing metadata. |
You can only PATCH artifacts your own token owns; others return `404`.
Not editable yet:
| Field | Reason |
|---|---|
| `content` | Content replacement/revisions are intentionally deferred. |
| `source` | Affects storage layout and feed identity. |
| `kind` | Affects renderer and storage behavior. |
| `day` | Affects time-ordered feed and storage layout. |
PowerShell example:
```powershell
$body = @{
title = "Morning Brief - Reviewed"
tags = @("brief", "daily", "reviewed")
metadata = @{
model = "gpt-5.5"
run_id = "brief-001"
reviewed = $true
}
} | ConvertTo-Json -Depth 5
Invoke-RestMethod `
-Uri "http://127.0.0.1:8001/api/artifacts/a1b2c3d4" `
-Method Patch `
-Headers @{ Authorization = "Bearer <your-personal-token>" } `
-ContentType "application/json" `
-Body $body
```
## Rendered And Raw Content
Rendered browser view:
```http
GET /a/{id}
```
Raw/source view:
```http
GET /a/{id}?raw=1
```
Raw currently exists for:
| Kind | Raw content |
|---|---|
| `markdown` | Preserved `.md` source. |
| `html_full` | Stored HTML file served as text. |
If raw content is unavailable, Daybook returns a small HTML fallback page.
## Capabilities
Endpoint:
```http
GET /api/capabilities
```
Example response:
```json
{
"artifact_kinds": ["html_fragment", "html_full", "markdown", "deck", "image", "pdf", "binary"],
"filters": ["source", "label", "day", "kind", "q"],
"views": ["rendered", "raw"],
"raw_supported_for": ["markdown", "html_full"],
"source_types": ["agent", "person", "system"],
"auth": "bearer_token"
}
```
Agents should call this endpoint if they need to adapt to the current Daybook instance, or
simply to check the instance is reachable and their token is valid. Unlike the other read
endpoints, it accepts a bearer token as well as a browser session:
```bash
curl -H "Authorization: Bearer <your-personal-token>" http://127.0.0.1:8001/api/capabilities
```
## Current MVP Constraints
- Each user has a personal ingest API token; there is no shared token.
- Reader/browser access requires login; feeds are private per user.
- Content modification/revisions are deferred.
- Office document conversion is not implemented.
- Manual browser upload/drag-and-drop is deferred.
- Pagination/cursors are not implemented yet.

108
docs/llm_posting_helper.md Normal file
View file

@ -0,0 +1,108 @@
# LLM Posting Helper
Agents should publish to Daybook with `skills/daybook-posting/scripts/daybook_post.py` instead of hand-building HTTP, JSON, curl, or PowerShell multipart requests.
The project also keeps `scripts/daybook_post.py` as a compatibility wrapper.
The helper is intentionally zero-dependency and uses only Python's standard library. It works on Windows and Linux.
## Configuration
```text
DAYBOOK_URL=http://127.0.0.1:8001
DAYBOOK_TOKEN=your-personal-api-token
DAYBOOK_SOURCE=agent
```
`DAYBOOK_TOKEN` is a personal per-user token, from Settings → Account in the app — not a token shared across users. Override these per environment.
## Commands
Check the instance:
```bash
python skills/daybook-posting/scripts/daybook_post.py --check
```
Post Markdown from a file:
```bash
python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Build Report" --content-file report.md --tags build,report
```
Post Markdown from stdin:
```bash
cat report.md | python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Build Report"
```
Post a deck:
```bash
python skills/daybook-posting/scripts/daybook_post.py --kind deck --title "Deployment Plan" --content-file deck.html
```
`deck.html` must contain top-level `<section>...</section>` blocks.
Post an image/PDF/binary file:
```bash
python skills/daybook-posting/scripts/daybook_post.py --file diagram.svg --title "Architecture Diagram"
python skills/daybook-posting/scripts/daybook_post.py --file report.pdf --title "Generated Report"
```
Render CSV/JSON/code as Markdown today:
```bash
python skills/daybook-posting/scripts/daybook_post.py --file results.csv --as-markdown --title "Results CSV"
```
Dry run:
```bash
python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Draft" --content-file report.md --dry-run
```
The artifact URL is printed as the final stdout line.
## Validation Guardrails
The helper validates common LLM mistakes before sending:
| Kind/input | Validation |
|---|---|
| `deck` | Must contain `<section`. |
| `html_fragment` | Must not contain `<!doctype`, `<html`, or `<body`. |
| `html_full` | Must contain `<!doctype` and `<html`. |
| `markdown` | Must not be blank. |
| `.svg` upload | Forces `image/svg+xml`. |
| `.pdf` upload | Forces `application/pdf`. |
## Metadata
Use repeatable `--meta key=value` flags:
```bash
python skills/daybook-posting/scripts/daybook_post.py \
--kind markdown \
--title "Run Summary" \
--content-file summary.md \
--meta run_id=run-001 \
--meta model=gpt-5.5
```
Or pass a JSON object:
```bash
python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Run Summary" --content-file summary.md --meta-json '{"run_id":"run-001"}'
```
## Skill Wrapper
A thin LLM-facing wrapper lives at:
```text
skills/daybook-posting/SKILL.md
```
Its key instruction is: do not hand-build requests; use `scripts/daybook_post.py`.