210 lines
8.6 KiB
Go
210 lines
8.6 KiB
Go
package extension
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"time"
|
|
)
|
|
|
|
// RegulationsSchemaVersion is the only request schema the host accepts for
|
|
// EXT-20; any other value is rejected before reaching the provider.
|
|
const RegulationsSchemaVersion = 1
|
|
|
|
const (
|
|
RegulationsStateOK = "ok"
|
|
RegulationsStateEmpty = "empty"
|
|
RegulationsStateDegraded = "degraded"
|
|
RegulationsStateUnavailable = "unavailable"
|
|
|
|
RegulationDisclosureFull = "full"
|
|
RegulationDisclosureExcerpt = "excerpt"
|
|
RegulationDisclosureMetadataOnly = "metadata_only"
|
|
RegulationDisclosureWithheld = "withheld"
|
|
|
|
WebSearchStateOK = "ok"
|
|
WebSearchStateEmpty = "empty"
|
|
WebSearchStateUnavailable = "unavailable"
|
|
WebSearchStateRateLimited = "rate_limited"
|
|
WebSearchStateRejected = "rejected"
|
|
WebSearchStateError = "error"
|
|
|
|
WebCaptureStateCaptured = "captured"
|
|
WebCaptureStateRejected = "rejected"
|
|
WebCaptureStateFailed = "failed"
|
|
|
|
WebRetentionFull = "full"
|
|
WebRetentionExcerpt = "excerpt"
|
|
WebRetentionMetadataOnly = "metadata_only"
|
|
)
|
|
|
|
// ErrRegulationsUnavailable is returned by every RegulationsHost method when no
|
|
// trusted provider is registered. Callers must not fall back to KnowledgeSearch.
|
|
var ErrRegulationsUnavailable = errors.New("extension: regulations provider unavailable")
|
|
|
|
// RegulationsCaller is filled by the host from the trusted dispatch context.
|
|
// It deliberately has no project ID: shared regulation access neither widens
|
|
// nor narrows with a project.
|
|
type RegulationsCaller struct {
|
|
PluginID string `json:"pluginId"`
|
|
Actor string `json:"actor,omitempty"`
|
|
Owner string `json:"owner"`
|
|
}
|
|
|
|
// RegulationsSearchRequest searches the controlled regulation corpus. An empty
|
|
// CorpusRevision means the current published revision; the result echoes the
|
|
// revision actually searched.
|
|
type RegulationsSearchRequest struct {
|
|
SchemaVersion int `json:"schemaVersion"`
|
|
Query string `json:"query"`
|
|
CorpusRevision string `json:"corpusRevision,omitempty"`
|
|
Kinds []string `json:"kinds,omitempty"`
|
|
CurrentOnly bool `json:"currentOnly,omitempty"`
|
|
DocNo string `json:"docNo,omitempty"`
|
|
ClauseNo string `json:"clauseNo,omitempty"`
|
|
Limit int `json:"limit,omitempty"`
|
|
}
|
|
|
|
type RegulationsSearchResult struct {
|
|
CorpusRevision string `json:"corpusRevision"`
|
|
State string `json:"state"` // ok|empty|degraded|unavailable
|
|
DegradedReasons []string `json:"degradedReasons,omitempty"`
|
|
Hits []RegulationHit `json:"hits"`
|
|
}
|
|
|
|
type RegulationHit struct {
|
|
RegulationID string `json:"regulationId"`
|
|
EditionID string `json:"editionId"`
|
|
NodeID string `json:"nodeId"`
|
|
DocNo string `json:"docNo,omitempty"`
|
|
Title string `json:"title,omitempty"`
|
|
EditionLabel string `json:"editionLabel,omitempty"`
|
|
LegalStatus string `json:"legalStatus,omitempty"`
|
|
ClauseNo string `json:"clauseNo,omitempty"`
|
|
HeadingPath []string `json:"headingPath,omitempty"`
|
|
Excerpt string `json:"excerpt,omitempty"`
|
|
ExcerptStart int `json:"excerptStart,omitempty"`
|
|
ExcerptEnd int `json:"excerptEnd,omitempty"`
|
|
NodeSHA256 string `json:"nodeSha256,omitempty"`
|
|
SourceAssetSHA256 string `json:"sourceAssetSha256,omitempty"`
|
|
PageStart int `json:"pageStart,omitempty"`
|
|
PageEnd int `json:"pageEnd,omitempty"`
|
|
Disclosure string `json:"disclosure"` // full|excerpt|metadata_only|withheld
|
|
WithheldReason string `json:"withheldReason,omitempty"`
|
|
IsSummary bool `json:"isSummary,omitempty"`
|
|
MatchKinds []string `json:"matchKinds,omitempty"`
|
|
Score float64 `json:"score,omitempty"`
|
|
}
|
|
|
|
// RegulationEvidenceRequest retrieves the original text span of a node pinned
|
|
// to a corpus revision.
|
|
type RegulationEvidenceRequest struct {
|
|
SchemaVersion int `json:"schemaVersion"`
|
|
CorpusRevision string `json:"corpusRevision"`
|
|
NodeID string `json:"nodeId"`
|
|
Start int `json:"start,omitempty"`
|
|
End int `json:"end,omitempty"`
|
|
}
|
|
|
|
type RegulationEvidence struct {
|
|
CorpusRevision string `json:"corpusRevision"`
|
|
RegulationID string `json:"regulationId,omitempty"`
|
|
EditionID string `json:"editionId,omitempty"`
|
|
NodeID string `json:"nodeId"`
|
|
ClauseNo string `json:"clauseNo,omitempty"`
|
|
Excerpt string `json:"excerpt,omitempty"`
|
|
Start int `json:"start,omitempty"`
|
|
End int `json:"end,omitempty"`
|
|
NodeSHA256 string `json:"nodeSha256,omitempty"`
|
|
SourceAssetSHA256 string `json:"sourceAssetSha256,omitempty"`
|
|
PageStart int `json:"pageStart,omitempty"`
|
|
PageEnd int `json:"pageEnd,omitempty"`
|
|
Disclosure string `json:"disclosure"`
|
|
WithheldReason string `json:"withheldReason,omitempty"`
|
|
HashVerified bool `json:"hashVerified"`
|
|
}
|
|
|
|
// WebSearchRequest performs a real web search. Exclusions are caller-declared
|
|
// confidential terms (project names, numbers, people); a query containing any
|
|
// of them is rejected by the host before the provider sees it.
|
|
type WebSearchRequest struct {
|
|
SchemaVersion int `json:"schemaVersion"`
|
|
Query string `json:"query"`
|
|
Exclusions []string `json:"exclusions,omitempty"`
|
|
PreferOfficial bool `json:"preferOfficial,omitempty"`
|
|
Limit int `json:"limit,omitempty"`
|
|
}
|
|
|
|
type WebSearchResult struct {
|
|
Provider string `json:"provider,omitempty"`
|
|
SentQuery string `json:"sentQuery,omitempty"`
|
|
SearchedAt time.Time `json:"searchedAt"`
|
|
State string `json:"state"` // ok|empty|unavailable|rate_limited|rejected|error
|
|
Reason string `json:"reason,omitempty"`
|
|
Results []WebSearchHit `json:"results,omitempty"`
|
|
}
|
|
|
|
type WebSearchHit struct {
|
|
Rank int `json:"rank"`
|
|
URL string `json:"url"`
|
|
Title string `json:"title,omitempty"`
|
|
Snippet string `json:"snippet,omitempty"`
|
|
Publisher string `json:"publisher,omitempty"`
|
|
Official bool `json:"official,omitempty"`
|
|
}
|
|
|
|
// WebCaptureRequest fetches a page found by a prior SearchWeb call.
|
|
type WebCaptureRequest struct {
|
|
SchemaVersion int `json:"schemaVersion"`
|
|
URL string `json:"url"`
|
|
SearchProvider string `json:"searchProvider,omitempty"`
|
|
SearchQuery string `json:"searchQuery,omitempty"`
|
|
SearchRank int `json:"searchRank,omitempty"`
|
|
}
|
|
|
|
type WebCapture struct {
|
|
CaptureID string `json:"captureId,omitempty"`
|
|
FinalURL string `json:"finalUrl,omitempty"`
|
|
FetchedAt time.Time `json:"fetchedAt"`
|
|
ContentType string `json:"contentType,omitempty"`
|
|
ByteSize int64 `json:"byteSize,omitempty"`
|
|
SHA256 string `json:"sha256,omitempty"`
|
|
Retention string `json:"retention,omitempty"` // full|excerpt|metadata_only
|
|
// Text is present only when the source rights allow full retention.
|
|
Text string `json:"text,omitempty"`
|
|
Candidates []WebClauseCandidate `json:"candidates,omitempty"`
|
|
State string `json:"state"` // captured|rejected|failed
|
|
Reason string `json:"reason,omitempty"`
|
|
}
|
|
|
|
type WebClauseCandidate struct {
|
|
ClauseNo string `json:"clauseNo,omitempty"`
|
|
Excerpt string `json:"excerpt"`
|
|
Start int `json:"start"`
|
|
End int `json:"end"`
|
|
}
|
|
|
|
// RegulationsProvider is implemented and registered by the trusted regulations
|
|
// knowledge plugin (plugin ID "kbreg"); the host ships no implementation.
|
|
type RegulationsProvider interface {
|
|
SearchRegulations(context.Context, RegulationsCaller, RegulationsSearchRequest) (RegulationsSearchResult, error)
|
|
ResolveRegulationEvidence(context.Context, RegulationsCaller, RegulationEvidenceRequest) (RegulationEvidence, error)
|
|
SearchWeb(context.Context, RegulationsCaller, WebSearchRequest) (WebSearchResult, error)
|
|
CaptureWeb(context.Context, RegulationsCaller, WebCaptureRequest) (WebCapture, error)
|
|
}
|
|
|
|
// RegulationsRegistrar is optional on a compiled in-process Registry. Only
|
|
// plugin ID "kbreg" may register, and only once.
|
|
type RegulationsRegistrar interface {
|
|
RegisterRegulationsProvider(RegulationsProvider) error
|
|
}
|
|
|
|
// RegulationsHost is optional on dispatch Host handles (obtained by type
|
|
// assertion). A missing capability means unavailable; callers must not fall
|
|
// back to KnowledgeSearch.
|
|
type RegulationsHost interface {
|
|
SearchRegulations(context.Context, RegulationsSearchRequest) (RegulationsSearchResult, error)
|
|
ResolveRegulationEvidence(context.Context, RegulationEvidenceRequest) (RegulationEvidence, error)
|
|
SearchWeb(context.Context, WebSearchRequest) (WebSearchResult, error)
|
|
CaptureWeb(context.Context, WebCaptureRequest) (WebCapture, error)
|
|
}
|