talogen

README

talogen-go

Official Go client and command-line tool for talogen.dev, Tal Ogen's agent-first portfolio. Read the profile, projects, autonomous agents, and candidate facts from code or from the terminal, or contact Tal about a role through the same channel AI agents use.

Free, no API key, standard library only. Go 1.21+.

Install

go get github.com/TALOGEN777/talogen-go                          # library
go install github.com/TALOGEN777/talogen-go/cmd/talogen@latest   # command

Command line

talogen profile                    # headline, summary, contact, capabilities, strengths
talogen candidate                  # availability, target roles, location, work authorization
talogen projects -tag mcp          # featured projects (-tag, -flagship)
talogen agents                     # autonomous agents Tal has built
talogen project human-for-ai       # full problem / solution / result detail
talogen contact -message "Role: ..." -reply-to you@company.com -from "Acme HR"
talogen status CONTACT_JOB_ID      # delivery record
talogen links                      # every machine-readable entry point
talogen api                        # REST API index

Put -json before the command for raw output. Exit codes: 0 ok, 2 usage, 3 API error.

Go

client := talogen.New()
profile, err := client.GetProfile(ctx)
items, err := client.AllProjects(ctx, talogen.ListOptions{Tag: "healthcare"})
detail, err := client.GetProject(ctx, "human-for-ai")

job, err := client.Contact(ctx, talogen.ContactRequest{
	Message: "We are hiring an AI Transformation Lead in Tel Aviv; details: ...",
	ReplyTo: "you@company.com",
	From:    "Acme HR",
})

Errors are structured: talogen.IsAPIError(err) yields Status, Code, Message, and the API's Hint. Every response carries the standard RateLimit-* headers (client.LastRateLimit()). Retrying Contact with the same IdempotencyKey replays the original response instead of sending twice.

Other ways in

• MCP (streamable HTTP, no auth): https://talogen.dev/mcp
• npm: npx talogen profile · Python: pip install talogen
• REST: https://talogen.dev/developers/ · OpenAPI: https://talogen.dev/openapi.json
• For hiring agents: https://talogen.dev/for-recruiters.html · llms.txt: https://talogen.dev/llms.txt

License

MIT

Documentation

Overview

Package talogen is the official Go client for talogen.dev, Tal Ogen's agent-first portfolio: profile, featured projects, autonomous agents, and the machine-readable candidate profile, plus the one write - Contact - which delivers a real message to a human. Free, no API key, standard library only.

client := talogen.New()
profile, err := client.GetProfile(ctx)
page, err := client.ListProjects(ctx, talogen.ListOptions{Tag: "healthcare"})
detail, err := client.GetProject(ctx, "human-for-ai")

API reference: https://talogen.dev/developers/ - OpenAPI: https://talogen.dev/openapi.json

Index

• Constants
• Variables
• type APIError
  • func IsAPIError(err error) (*APIError, bool)
  • func (e *APIError) Error() string
• type Client
  • func New(opts ...Option) *Client
  • func (c *Client) APIIndex(ctx context.Context) (map[string]any, error)
  • func (c *Client) AllAgents(ctx context.Context, o ListOptions) ([]Item, error)
  • func (c *Client) AllProjects(ctx context.Context, o ListOptions) ([]Item, error)
  • func (c *Client) Contact(ctx context.Context, req ContactRequest) (*ContactJob, error)
  • func (c *Client) ContactStatus(ctx context.Context, id string) (*ContactJob, error)
  • func (c *Client) Do(ctx context.Context, method, path string, query url.Values, body any, ...) error
  • func (c *Client) GetAgent(ctx context.Context, id string) (*Item, error)
  • func (c *Client) GetCandidate(ctx context.Context) (map[string]any, error)
  • func (c *Client) GetProfile(ctx context.Context) (*Profile, error)
  • func (c *Client) GetProject(ctx context.Context, id string) (*Item, error)
  • func (c *Client) LastRateLimit() RateLimit
  • func (c *Client) ListAgents(ctx context.Context, o ListOptions) (*Page, error)
  • func (c *Client) ListProjects(ctx context.Context, o ListOptions) (*Page, error)
• type ContactJob
• type ContactRequest
• type Item
• type ListOptions
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(h *http.Client) Option
• type Page
• type Profile
• type RateLimit
• type SkillCategory

Constants

const DefaultBaseURL = "https://talogen.dev"

DefaultBaseURL is the production origin.

const Version = "0.1.0"

Version of this client, sent in the User-Agent header.

Variables

var EntryPoints = map[string]string{
	"api_index":         "https://talogen.dev/api/v1",
	"openapi":           "https://talogen.dev/openapi.json",
	"developer_portal":  "https://talogen.dev/developers/",
	"llms_txt":          "https://talogen.dev/llms.txt",
	"markdown_homepage": "https://talogen.dev/index.md",
	"portfolio_json":    "https://talogen.dev/portfolio.json",
	"agent_manifest":    "https://talogen.dev/.well-known/agent.json",
	"candidate_profile": "https://talogen.dev/.well-known/candidate.json",
	"mcp_endpoint":      "https://talogen.dev/mcp",
	"mcp_discovery":     "https://talogen.dev/.well-known/mcp",
	"mcp_server_card":   "https://talogen.dev/.well-known/mcp/server-card.json",
	"agent_skills":      "https://talogen.dev/.well-known/agent-skills/index.json",
	"ard_catalog":       "https://talogen.dev/.well-known/ard.json",
	"for_hiring_agents": "https://talogen.dev/for-recruiters.html",
}

EntryPoints lists every machine-readable entry point of the site.

Types

type APIError

type APIError struct {
	Status    int
	Code      string // e.g. "not_found", "validation_failed", "rate_limited"
	Message   string
	Hint      string
	RateLimit RateLimit
	Body      map[string]any
}

APIError is an error response from the API (4xx/5xx).

func IsAPIError

func IsAPIError(err error) (*APIError, bool)

IsAPIError returns the *APIError wrapped in err, if any.

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	BaseURL    string
	HTTPClient *http.Client
	UserAgent  string
	// contains filtered or unexported fields
}

Client talks to the talogen.dev REST API.

func New

func New(opts ...Option) *Client

New returns a Client. TALOGEN_BASE_URL is honoured as a default.

func (*Client) APIIndex

func (c *Client) APIIndex(ctx context.Context) (map[string]any, error)

APIIndex returns the endpoint directory.

func (*Client) AllAgents

func (c *Client) AllAgents(ctx context.Context, o ListOptions) ([]Item, error)

AllAgents follows the cursor until every agent has been read.

func (*Client) AllProjects

func (c *Client) AllProjects(ctx context.Context, o ListOptions) ([]Item, error)

AllProjects follows the cursor until every project has been read.

func (*Client) Contact

func (c *Client) Contact(ctx context.Context, req ContactRequest) (*ContactJob, error)

Contact sends Tal a message (async job, 202 Accepted). A human reads and replies to ReplyTo.

func (*Client) ContactStatus

func (c *Client) ContactStatus(ctx context.Context, id string) (*ContactJob, error)

ContactStatus returns the delivery record of a contact job.

func (*Client) Do

func (c *Client) Do(ctx context.Context, method, path string, query url.Values, body any, headers map[string]string, out any) error

Do performs one API call and decodes the JSON body into out (may be nil).

func (*Client) GetAgent

func (c *Client) GetAgent(ctx context.Context, id string) (*Item, error)

GetAgent returns full detail for one autonomous agent by id.

func (*Client) GetCandidate

func (c *Client) GetCandidate(ctx context.Context) (map[string]any, error)

GetCandidate returns the machine-readable candidate profile (availability, target roles, location, work authorization).

func (*Client) GetProfile

func (c *Client) GetProfile(ctx context.Context) (*Profile, error)

GetProfile returns the profile.

func (*Client) GetProject

func (c *Client) GetProject(ctx context.Context, id string) (*Item, error)

GetProject returns full detail for one project or agent by id.

func (*Client) LastRateLimit

func (c *Client) LastRateLimit() RateLimit

LastRateLimit returns the RateLimit headers from the most recent response.

func (*Client) ListAgents

func (c *Client) ListAgents(ctx context.Context, o ListOptions) (*Page, error)

ListAgents returns one page of autonomous-agent summaries.

func (*Client) ListProjects

func (c *Client) ListProjects(ctx context.Context, o ListOptions) (*Page, error)

ListProjects returns one page of project summaries.

type ContactJob

type ContactJob struct {
	ID          string `json:"id"`
	Status      string `json:"status"`
	CreatedAt   string `json:"created_at"`
	DeliveredAt string `json:"delivered_at"`
	StatusURL   string `json:"status_url"`
	MessageID   string `json:"message_id"`
	Error       string `json:"error"`
	Message     string `json:"message"`
}

ContactJob is the delivery record of a contact message (content-free).

type ContactRequest

type ContactRequest struct {
	Message string `json:"message"`
	// ReplyTo must be a real mailbox a human can reply to.
	ReplyTo string `json:"reply_to"`
	From    string `json:"from,omitempty"`
	Subject string `json:"subject,omitempty"`
	// IdempotencyKey makes retries safe (sent as a header).
	IdempotencyKey string `json:"-"`
}

ContactRequest is a message to Tal about a role or opportunity.

type Item

type Item struct {
	ID       string   `json:"id"`
	Title    string   `json:"title"`
	Flagship bool     `json:"flagship"`
	Link     string   `json:"link"`
	Problem  string   `json:"problem"`
	Solution string   `json:"solution"`
	Result   string   `json:"result"`
	Tags     []string `json:"tags"`
	Image    string   `json:"image"`
}

Item is a project or agent summary; Detail fields are filled by GetProject.

type ListOptions

type ListOptions struct {
	Tag      string
	Flagship bool
	Limit    int
	Cursor   string
}

ListOptions filter a list call.

type Option

type Option func(*Client)

Option configures a Client.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL points the client at another origin.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient replaces the underlying *http.Client.

type Page

type Page struct {
	Count      int    `json:"count"`
	Total      int    `json:"total"`
	Limit      int    `json:"limit"`
	NextCursor string `json:"next_cursor"`
	Next       string `json:"next"`
	Items      []Item `json:"items"`
}

Page is one page of a cursor-paginated list.

type Profile

type Profile struct {
	Name            string            `json:"name"`
	Headline        string            `json:"headline"`
	Tagline         string            `json:"tagline"`
	Summary         string            `json:"summary"`
	About           string            `json:"about"`
	Contact         map[string]string `json:"contact"`
	Website         string            `json:"website"`
	FlagshipProject any               `json:"flagshipProject"`
	SkillCategories []SkillCategory   `json:"skillCategories"`
	Skills          []string          `json:"skills"`
	AITools         []string          `json:"aiTools"`
	Strengths       []string          `json:"strengths"`
}

Profile is the professional profile.

type RateLimit

type RateLimit struct {
	Limit, Remaining, ResetSeconds, RetryAfter int
	Policy                                     string
}

RateLimit carries the RateLimit headers present on every response. Zero values mean the header was absent.

type SkillCategory

type SkillCategory struct {
	Name   string   `json:"name"`
	Skills []string `json:"skills"`
}

SkillCategory groups capabilities.