Skip to content
Ishvana Ishvana Docs

Perceive Webpage

POST
/api/agents/perceive/webpage

Analyze webpage with comprehensive perception capabilities.

Performs deep analysis of webpage content including entity extraction, sentiment analysis, relationship mapping, and strategic insight generation using Lagan’s perception engine.

Process:

  1. Fetch webpage content via Lagan’s web scraping
  2. Extract entities (people, places, concepts)
  3. Analyze sentiment and tone
  4. Map relationships between entities
  5. Generate strategic insights

Args: request: WebpagePerceptionRequest with URL and analysis options

Returns: WebpagePerceptionResponse with entities, relationships, sentiment, insights

Raises: HTTPException 400: Invalid URL or request parameters HTTPException 502: Upstream AI provider returned an empty or schema-invalid extraction response (see detail) HTTPException 503: Lagan agent not available HTTPException 504: LLM did not respond within the configured timeout

Example:

POST /api/agents/discovery/perceive/webpage
{
    "url": "https://example.com/article",
    "depth": "strategic",
    "extract_entities": true,
    "analyze_sentiment": true,
    "map_relationships": true
}

Response:

{
    "success": true,
    "url": "https://example.com/article",
    "entities": [
        {"name": "AI Research", "entity_type": "concept", "confidence": 0.95}
    ],
    "relationships": [
        {"from_entity": "AI", "to_entity": "Machine Learning", "relationship_type": "includes"}
    ],
    "sentiment": {"overall_sentiment": "positive", "confidence": 0.87},
    "strategic_insights": ["Emerging AI trends indicate..."],
    "processing_time_ms": 1234
}

Request Body required

Section titled “Request Body required ”
WebpagePerceptionRequest

Request model for comprehensive webpage perception analysis.

Analyzes webpage content to extract entities, relationships, sentiment, and strategic insights using Lagan’s perception engine. Supports configurable analysis depth from surface-level scanning to deep prophetic insights.

Fields:

  • url: URL of the webpage to analyze (required, must be valid HTTP/HTTPS)
  • depth: Analysis depth level controlling thoroughness and insight depth
  • extract_entities: Whether to perform named entity recognition
  • analyze_sentiment: Whether to perform sentiment analysis
  • map_relationships: Whether to map entity relationships

Depth Levels:

  • surface: Quick scan, basic structure extraction
  • analytical: Detailed analysis with entity extraction
  • strategic: In-depth strategic insights and patterns
  • prophetic: Deep analysis with predictive insights

Usage: Used by perception routes to analyze webpage content for knowledge extraction.

Integration:

  • PerceptionRoutes: Request validation for /perception/webpage endpoint
  • LaganAgent: Web perception tool configuration
  • Frontend: Perception analysis request forms
object
url
required
Url

URL of the webpage to analyze

string format: uri
>= 1 characters <= 2083 characters
Example
https://example.com/article
depth
Depth

Analysis depth level (surface, analytical, strategic, prophetic)

string
default: analytical
Allowed values: surface analytical strategic prophetic
extractEntities
Extractentities

Whether to extract entities from content

boolean
default: true
analyzeSentiment
Analyzesentiment

Whether to perform sentiment analysis

boolean
default: true
mapRelationships
Maprelationships

Whether to map entity relationships

boolean
default: true

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

WebpagePerceptionResponse

Response model for webpage perception analysis.

Contains extracted entities, relationships, sentiment analysis, and strategic insights from the analyzed webpage. Provides comprehensive perception results for downstream processing and visualization.

Fields:

  • success: Whether the analysis completed successfully
  • url: URL that was analyzed
  • entities: List of extracted entities from content
  • relationships: List of entity relationships
  • sentiment: Sentiment analysis results (optional)
  • strategic_insights: List of strategic insights derived from content
  • content_summary: Brief summary of page content
  • metadata: Additional metadata (title, author, publication date, etc.)
  • processing_time_ms: Total processing time in milliseconds
  • timing: Per-phase timing breakdown (knowledge vs extraction)
  • extraction_retries: How many schema-violation retries the extraction call burned before producing valid output (0 on first-try success)

Usage: Returned by perception endpoints after webpage analysis.

Integration:

  • PerceptionRoutes: Response model for /perception/webpage endpoint
  • Frontend: Perception results display and visualization
  • Knowledge Base: Entity and relationship storage
object
success
required
Success

Whether analysis was successful

boolean
url
required
Url

URL that was analyzed

string
entities
Entities

Extracted entities from content

Array<object>
Entity

Extracted entity from content with type classification and confidence scoring.

Represents a named entity (person, place, organization, concept, etc.) extracted from analyzed content with confidence scoring and contextual information.

Fields:

  • name: Entity name or identifier as extracted from content
  • entity_type: Classification type (person, place, organization, concept, etc.)
  • confidence: Extraction confidence score from 0.0 to 1.0
  • context: Surrounding text context where entity was found

Usage: Used in perception and research responses to return extracted entities.

Integration:

  • WebpagePerceptionResponse: Entity list in perception results
  • ResearchResult: Entities extracted from research results
  • EnrichContentResponse: Additional entities from enrichment
object
name
required
Name

Entity name or identifier

string
entityType
required
Entitytype

Entity type (person, place, concept, etc.)

string
confidence
required
Confidence

Extraction confidence score

number
<= 1
context
Any of:
string
relationships
Relationships

Relationships between entities

Array<object>
Relationship

Relationship between two extracted entities.

Represents a directional relationship between two entities with type classification and confidence scoring. Used for building knowledge graphs and understanding entity interconnections.

Fields:

  • from_entity: Source entity name in the relationship
  • to_entity: Target entity name in the relationship
  • relationship_type: Type/nature of the relationship
  • confidence: Relationship confidence score from 0.0 to 1.0

Usage: Used in perception responses to map entity relationships.

Integration:

  • WebpagePerceptionResponse: Relationship list in perception results
  • Knowledge Graph: Entity relationship visualization
object
fromEntity
required
Fromentity

Source entity in relationship

string
toEntity
required
Toentity

Target entity in relationship

string
relationshipType
required
Relationshiptype

Type of relationship

string
confidence
required
Confidence

Relationship confidence

number
<= 1
sentiment
Any of:
SentimentAnalysis

Sentiment analysis results for analyzed content.

Provides comprehensive sentiment scoring including overall sentiment classification, confidence scoring, detected tones, and emotional indicators for nuanced content understanding.

Fields:

  • overall_sentiment: Primary sentiment classification (positive, neutral, negative)
  • confidence: Sentiment classification confidence score
  • tone: List of detected tones (professional, casual, technical, etc.)
  • emotional_indicators: Dictionary of emotional indicators with strength scores

Usage: Used in perception responses to provide sentiment analysis results.

Integration:

  • WebpagePerceptionResponse: Sentiment field in perception results
  • Frontend: Sentiment visualization and indicators
object
overallSentiment
required
Overallsentiment

Overall content sentiment

string
Allowed values: positive neutral negative
confidence
required
Confidence

Sentiment confidence score

number
<= 1
tone
Tone

Detected tones (professional, casual, etc.)

Array<string>
emotionalIndicators
Emotionalindicators

Emotional indicators with strength scores

object
key
additional properties
number
strategicInsights
Strategicinsights

Strategic insights derived from content

Array<string>
contentSummary
Any of:
string
metadata
Metadata

Additional metadata (title, author, date, etc.)

object
key
additional properties
string
processingTimeMs
required
Processingtimems

Processing time in milliseconds

integer
timing
Any of:
PerceptionTiming

Per-phase timing breakdown for a perception run.

Splits the total pipeline duration into its two dominant phases so users and UIs can diagnose which stage is slow:

  • knowledge_ms: Lagan’s knowledge-request collection (web fetch + streaming analysis) — typically the bulk of the time.
  • extract_ms: the structured-extraction LLM call that parses the Lagan output into entities / relationships / sentiment.
  • total_ms: wall-clock from endpoint entry to response build.

knowledge_ms + extract_ms may be slightly less than total_ms because the small entity-merge + response-build work is counted only under total_ms.

object
knowledgeMs
required
Knowledgems

Milliseconds spent collecting Lagan’s knowledge-request stream.

integer
extractMs
required
Extractms

Milliseconds spent on the structured-extraction LLM call.

integer
totalMs
required
Totalms

Total wall-clock milliseconds for the perception run.

integer
extractionRetries
Extractionretries

Number of schema-violation retries the extraction call burned before producing valid output. 0 = succeeded on first attempt.

integer
0

422

Section titled “422 ”

Validation Error

HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object