README
¶
Photon examples
Runnable programs, each one a single main.go you can read in a sitting. They
use only Photon and the standard library.
go run ./examples/hello # from the repository root
All of them listen on :8080 (one at a time), and stop gracefully on Ctrl-C.
| Example | What it shows | Start here if... |
|---|---|---|
hello |
Routes, a path parameter, JSON, a token stream, Run |
you are new to Photon |
stream |
Every streaming technique: tokens, resume with Last-Event-ID, DropOldest metrics, back-pressure, errors after the first event, shutdown with Done() |
you are building anything that streams |
openai-proxy |
An OpenAI-compatible gateway that relays an upstream model and stops it when the client leaves. Runs without an API key. | you put a server in front of a model |
agent |
An agent's thinking, tool calls, and answer as typed events, with a browser UI | you are streaming agent steps to a frontend |
api |
Groups, DecodeJSON, Error, photonerr, auth on part of the tree, request logging |
you are building a JSON API |
middleware |
CORS, rate limiting, bearer auth, roles - and the tests that prove the ordering | you are porting middleware |
security |
What the defaults stop, demonstrated with requests you can send | you want to see the limits work |
production |
Health vs readiness, JSON logs, timeouts, graceful drain | you are deploying |
openai-backend |
A complete OpenAI-compatible backend: tenants, quotas, metrics, Dockerfile. A separate module. | you want a larger, realistic codebase |
Start a project from an example
The photon CLI copies an example into a new module:
go install github.com/agenticmarket/photon/cmd/photon@latest
photon init my-agent -template agent # agent, openai-proxy, api, or minimal
cd my-agent && go mod tidy && go run .
Quick tour
go run ./examples/hello
curl localhost:8080/greet/Ada # {"message":"Hello, Ada!"}
curl -N localhost:8080/count # five events, then done
go run ./examples/openai-proxy
curl -N localhost:8080/v1/chat/completions -H 'Content-Type: application/json' \
-d '{"model":"demo","stream":true,"messages":[{"role":"user","content":"hi"}]}'
# Press Ctrl-C halfway: the gateway logs the upstream request being cancelled.
go run ./examples/agent
# open http://localhost:8080
go run ./examples/stream
curl -N localhost:8080/tokens
curl -N -H 'Last-Event-ID: 5' localhost:8080/resumable # starts at token 6
Use curl -N: without it, curl buffers output and a stream appears all at once
at the end, which looks exactly like a server that does not stream.
Documentation
¶
Overview ¶
Package examples holds photon's runnable examples. Each subdirectory is a standalone program; see README.md.
The package itself exists for one reason: `photon init` scaffolds new projects from these programs, and embedding them here means the templates are the examples - compiled and tested with the rest of the module - rather than string constants that can quietly stop compiling.
Index ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var FS embed.FS
FS holds the source of the template programs.
View Source
var Templates = map[string]string{
"minimal": "hello/main.go",
"api": "api/main.go",
"agent": "agent/main.go",
"openai-proxy": "openai-proxy/main.go",
}
Templates maps a `photon init -template` name to the example it copies.
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Command agent streams an AI agent's work to a browser as it happens: what it is thinking, which tools it calls, what they return, and the answer, token by token.
|
Command agent streams an AI agent's work to a browser as it happens: what it is thinking, which tools it calls, what they return, and the answer, token by token. |
|
Command api is a small JSON API: grouped routes with middleware, JSON in and out, structured errors, and authentication on part of the tree.
|
Command api is a small JSON API: grouped routes with middleware, JSON in and out, structured errors, and authentication on part of the tree. |
|
Command hello is the smallest useful photon server.
|
Command hello is the smallest useful photon server. |
|
Command middleware shows how middleware composes in photon, and that it is ordinary net/http middleware.
|
Command middleware shows how middleware composes in photon, and that it is ordinary net/http middleware. |
|
Command openai-proxy is an OpenAI-compatible gateway: it accepts Chat Completions requests, forwards them to an upstream model server, and relays the streamed answer to the client token by token.
|
Command openai-proxy is an OpenAI-compatible gateway: it accepts Chat Completions requests, forwards them to an upstream model server, and relays the streamed answer to the client token by token. |
|
Command production shows the parts of running a server that are not the handler: lifecycle, health checks, timeouts, and logging that an operator can actually read.
|
Command production shows the parts of running a server that are not the handler: lifecycle, health checks, timeouts, and logging that an operator can actually read. |
|
Command security shows what photon protects you from by default, and the few things it deliberately leaves to you.
|
Command security shows what photon protects you from by default, and the few things it deliberately leaves to you. |
|
Command stream is a tour of photon's server-sent events.
|
Command stream is a tour of photon's server-sent events. |
Click to show internal directories.
Click to hide internal directories.