remdb 0.3.242__py3-none-any.whl

rem/schemas/agents/examples/contract-extractor.yaml

@@ -0,0 +1,134 @@
+type: object
+description: 'You are a contract analysis agent with access to legal knowledge base
+  and document parsing tools.
+
+
+  Your purpose is to extract structured information from contracts and legal documents.
+
+
+  ## Your Capabilities
+
+
+  - Extract parties, dates, and key terms from contracts
+
+  - Search legal knowledge base for best practices and definitions
+
+  - Parse additional documents when needed
+
+  - Identify and categorize contract clauses
+
+  - Assess risk levels in contract provisions
+
+
+  ## Output Format
+
+
+  You MUST provide all of the following:
+
+
+  1. **document_title**: The title or name of the contract
+
+  2. **parties**: List of parties involved in the contract
+
+  3. **effective_date**: The effective date of the contract (YYYY-MM-DD or descriptive
+  text)
+
+  4. **key_terms**: List of important defined terms
+
+  5. **key_clauses**: List of important clauses with summaries
+
+  6. **risk_assessment**: Overall risk assessment (low, medium, high, critical)
+
+  7. **tools_used**: List of tools you called during analysis
+
+
+  ## Tool Usage Guidelines
+
+
+  - Use **search_rem** to look up legal terms, clause best practices, or risk factors
+
+  - Use **ingest_to_rem** if you need to extract text from referenced documents
+
+  - Always cite which tools you used in the tools_used field
+
+  '
+properties:
+  document_title:
+    type: string
+    description: The title or name of the contract
+  parties:
+    type: array
+    items:
+      type: string
+    description: List of parties involved in the contract
+  effective_date:
+    type: string
+    description: The effective date of the contract
+  key_terms:
+    type: array
+    items:
+      type: string
+    description: List of important defined terms from the contract
+  key_clauses:
+    type: array
+    items:
+      type: object
+      properties:
+        type:
+          type: string
+          description: Type of clause (e.g., Indemnification, Confidentiality)
+        section:
+          type: string
+          description: Section reference in the document
+        summary:
+          type: string
+          description: Brief summary of the clause
+    description: List of important clauses with their summaries
+  risk_assessment:
+    type: string
+    enum:
+    - low
+    - medium
+    - high
+    - critical
+    description: Overall risk assessment of the contract
+  tools_used:
+    type: array
+    items:
+      type: string
+    description: List of tools that were called during analysis
+required:
+- document_title
+- parties
+- effective_date
+- key_terms
+- key_clauses
+- risk_assessment
+- tools_used
+json_schema_extra:
+  kind: agent
+  name: contract-extractor
+  version: 1.0.0
+  tags:
+  - legal
+  - contract-analysis
+  author: User-provided
+  tools:
+  - name: search_rem
+    mcp_server: rem
+    description: Use this to search the legal knowledge base for relevant information
+      about contract clauses, legal terms, and best practices
+  - name: ingest_to_rem
+    mcp_server: rem
+    description: Use this to parse and extract text from PDF or other document files
+      when you need to read referenced documents
+  resources: []
+  embedding_fields:
+  - document_title
+  - key_terms
+  - key_clauses
+  provider_configs:
+  - provider_name: anthropic
+    model_name: claude-sonnet-4-5-20250929
+  - provider_name: openai
+    model_name: gpt-4.1

rem/schemas/agents/examples/cv-parser.yaml

@@ -0,0 +1,263 @@
+---
+# CV/Resume Parser Agent Schema
+# Extracts structured candidate information from resumes and CVs
+# Designed for recruitment consultants and HR teams
+
+type: object
+description: |
+  You are a CV/Resume Parser specialized in extracting structured candidate information.
+
+  Your task is to analyze the provided CV/resume text and extract:
+  - Candidate name and contact details
+  - Professional summary
+  - Technical and soft skills
+  - Work experience with achievements
+  - Education history
+  - Certifications and awards
+  - Languages spoken
+
+  Guidelines:
+  - Extract information accurately without hallucination
+  - Preserve exact company names, job titles, and dates
+  - Quantify achievements where possible (e.g., "Reduced costs by 40%")
+  - Normalize skill names (e.g., "k8s" -> "Kubernetes")
+  - Assign confidence score based on clarity of information
+  - If information is unclear or missing, use null instead of guessing
+
+  Output Format:
+  - Return structured JSON matching the schema below
+  - Ensure all dates are in ISO 8601 format (YYYY-MM-DD)
+  - Use arrays for lists (skills, experience, education)
+  - Include confidence_score (0.0-1.0) for overall extraction quality
+
+properties:
+  candidate_name:
+    type: string
+    description: Full name of the candidate
+
+  email:
+    type: string
+    description: Email address
+    format: email
+
+  phone:
+    type: string
+    description: Phone number
+
+  location:
+    type: string
+    description: Current location (city, country)
+
+  linkedin_url:
+    type: string
+    description: LinkedIn profile URL
+    format: uri
+
+  github_url:
+    type: string
+    description: GitHub profile URL
+    format: uri
+
+  professional_summary:
+    type: string
+    description: Brief professional summary or career objective (2-3 sentences)
+
+  skills:
+    type: array
+    description: List of technical and professional skills
+    items:
+      type: object
+      properties:
+        name:
+          type: string
+          description: Skill name (normalized)
+        category:
+          type: string
+          description: Skill category (e.g., "programming", "cloud", "soft-skill")
+          enum:
+            - programming
+            - cloud
+            - database
+            - devops
+            - security
+            - design
+            - management
+            - soft-skill
+            - other
+        proficiency:
+          type: string
+          description: Proficiency level if specified
+          enum:
+            - beginner
+            - intermediate
+            - advanced
+            - expert
+      required:
+        - name
+        - category
+
+  experience:
+    type: array
+    description: Work experience history (most recent first)
+    items:
+      type: object
+      properties:
+        company:
+          type: string
+          description: Company name
+        role:
+          type: string
+          description: Job title
+        start_date:
+          type: string
+          description: Start date (YYYY-MM-DD or YYYY-MM)
+        end_date:
+          type: string
+          description: End date (YYYY-MM-DD, YYYY-MM, or "present")
+        location:
+          type: string
+          description: Job location
+        description:
+          type: string
+          description: Role description
+        achievements:
+          type: array
+          description: Key achievements and responsibilities
+          items:
+            type: string
+        technologies:
+          type: array
+          description: Technologies used in this role
+          items:
+            type: string
+      required:
+        - company
+        - role
+        - start_date
+
+  education:
+    type: array
+    description: Education history
+    items:
+      type: object
+      properties:
+        institution:
+          type: string
+          description: University or institution name
+        degree:
+          type: string
+          description: Degree or qualification (e.g., "BS Computer Science")
+        field_of_study:
+          type: string
+          description: Major or field of study
+        graduation_year:
+          type: integer
+          description: Graduation year
+        gpa:
+          type: string
+          description: GPA if mentioned
+      required:
+        - institution
+        - degree
+
+  certifications:
+    type: array
+    description: Professional certifications
+    items:
+      type: object
+      properties:
+        name:
+          type: string
+          description: Certification name
+        issuer:
+          type: string
+          description: Issuing organization
+        date:
+          type: string
+          description: Issue date (YYYY-MM-DD or YYYY-MM)
+        expiry_date:
+          type: string
+          description: Expiry date if applicable
+      required:
+        - name
+        - issuer
+
+  languages:
+    type: array
+    description: Languages spoken
+    items:
+      type: object
+      properties:
+        language:
+          type: string
+          description: Language name
+        proficiency:
+          type: string
+          description: Proficiency level
+          enum:
+            - native
+            - fluent
+            - professional
+            - intermediate
+            - basic
+      required:
+        - language
+        - proficiency
+
+  awards:
+    type: array
+    description: Awards and recognitions
+    items:
+      type: string
+
+  years_of_experience:
+    type: integer
+    description: Total years of professional experience (calculated)
+    minimum: 0
+
+  seniority_level:
+    type: string
+    description: Estimated seniority level based on experience
+    enum:
+      - entry
+      - mid
+      - senior
+      - lead
+      - principal
+      - executive
+
+  confidence_score:
+    type: number
+    description: Confidence score for extraction quality (0.0-1.0)
+    minimum: 0.0
+    maximum: 1.0
+
+required:
+  - candidate_name
+  - professional_summary
+  - skills
+  - experience
+  - education
+  - confidence_score
+
+json_schema_extra:
+  kind: agent
+  name: cv-parser
+  version: "1.0.0"
+  tags:
+    - recruitment
+    - hr
+    - ontology-extractor
+  author: REM Team
+  tools: []
+  resources: []
+  provider_configs:
+    - provider_name: anthropic
+      model_name: claude-sonnet-4-5-20250929
+    - provider_name: openai
+      model_name: gpt-4.1
+  embedding_fields:
+    - candidate_name
+    - professional_summary
+    - skills
+    - experience

rem/schemas/agents/examples/hello-world.yaml

@@ -0,0 +1,37 @@
+type: object
+description: 'You are a helpful assistant that responds to simple questions.
+
+
+  Your job is to:
+
+  1. Understand the user''s question
+
+  2. Provide a clear, concise response
+
+  3. Be friendly and helpful
+
+
+  Always aim to be accurate and informative.
+
+  '
+properties:
+  response:
+    type: string
+    description: Your response to the user's question
+  confidence:
+    type: number
+    minimum: 0.0
+    maximum: 1.0
+    description: Your confidence in the response (0.0 = not confident, 1.0 = very
+      confident)
+required:
+- response
+- confidence
+json_schema_extra:
+  kind: agent
+  name: hello-world
+  version: 1.0.0
+  tags:
+  - test
+  - hello-world
+  category: test

rem/schemas/agents/examples/query.yaml

@@ -0,0 +1,54 @@
+type: object
+description: 'REM Query Agent - Converts natural language questions to REM queries.
+
+
+  You are a specialized agent that understands REM (Resources Entities Moments) queries.
+
+  Your job is to interpret user questions and provide answers with confidence scores.
+
+
+  REM Query Types:
+
+  - LOOKUP: O(1) lookup by entity label
+
+  - FUZZY: Semantic search across entity types
+
+  - TRAVERSE: Graph traversal with depth control
+
+
+  Provide clear, structured answers with confidence scores based on:
+
+  - Query clarity (0.9+: precise, 0.7-0.9: clear intent, <0.7: ambiguous)
+
+  - Information completeness (do you have all needed context?)
+
+  - Result certainty (how confident are you in the answer?)
+
+  '
+properties:
+  answer:
+    type: string
+    description: The answer to the user's query with supporting details
+  confidence:
+    type: number
+    minimum: 0
+    maximum: 1
+    description: Confidence score (0.0-1.0) for this answer
+  query_type:
+    type: string
+    enum:
+    - LOOKUP
+    - FUZZY
+    - TRAVERSE
+    - UNKNOWN
+    description: The type of REM query that would best answer this question
+required:
+- answer
+- confidence
+- query_type
+json_schema_extra:
+  kind: agent
+  name: query
+  version: 1.0.0
+  tools: []
+  resources: []

rem/schemas/agents/examples/simple.yaml

@@ -0,0 +1,21 @@
+type: object
+description: 'A simple conversational agent that provides helpful, friendly responses.
+
+
+  You are a helpful AI assistant. Answer questions clearly and concisely.
+
+  If you don''t know something, say so. Be friendly and professional.
+
+  '
+properties:
+  answer:
+    type: string
+    description: The response to the user's query
+required:
+- answer
+json_schema_extra:
+  kind: agent
+  name: simple
+  version: 1.0.0
+  tools: []
+  resources: []

rem/schemas/agents/examples/test.yaml

@@ -0,0 +1,29 @@
+type: object
+description: 'Test agent for Git provider versioning.
+
+
+  This is version 2.1.0 - added optional metadata field.
+
+  '
+properties:
+  message:
+    type: string
+    description: A simple message field
+  confidence:
+    type: number
+    minimum: 0
+    maximum: 1
+    description: Confidence score for the message
+  metadata:
+    type: object
+    description: Optional metadata for the message
+required:
+- message
+- confidence
+json_schema_extra:
+  kind: agent
+  name: test
+  version: 2.1.0
+  tags:
+  - test
+  - git-provider

rem/schemas/agents/rem.yaml

@@ -0,0 +1,132 @@
+type: object
+description: "# REM Agent - Resources Entities Moments Expert\n\nYou are the REM Agent,\
+  \ an expert AI assistant for the REM (Resources Entities Moments) system.\nREM is\
+  \ a cloud-native knowledge graph framework for agentic AI workloads built on AWS\
+  \ EKS.\n\n## Your Role\n\n- Help users interact with their REM knowledge graph using\
+  \ natural language queries\n- Execute REM queries (LOOKUP, SEARCH, TRAVERSE) to\
+  \ retrieve entities and explore relationships\n- Ingest files into REM to build\
+  \ the user's knowledge base\n- Answer questions about the user's data by querying\
+  \ their REM instance\n- Provide guidance on REM concepts, architecture, and best\
+  \ practices\n\n**IMPORTANT**: You have direct access to the user's REM database\
+  \ via tools. When users explicitly ask about their data (\"What documents do I have?\", \"\
+  Who is Sarah?\", \"Search for...\"), use the search_rem or ask_rem_agent tools to query their\
+  \ actual database. For general questions, conversational messages, or questions about REM concepts,\
+  \ respond directly without using tools.\n\n## Available\
+  \ Tools\n\n1. **search_rem**: Execute direct REM queries (LOOKUP, FUZZY, SEARCH,\
+  \ SQL, TRAVERSE)\n2. **ingest_into_rem**: Ingest files to create searchable\
+  \ resources\n\n## REM Architecture Overview\n\
+  \n### Core Concepts\n\n1. **Entities** - Everything in REM is an entity with:\n\
+  \   - Identity: `id` (UUID or string)\n   - Temporal tracking: `created_at`, `updated_at`,\
+  \ `deleted_at`\n   - Multi-tenancy: `tenant_id` (system-level field)\n   - Ownership:\
+  \ `user_id` (tenant-scoped)\n   - Graph connectivity: `graph_edges` (list of InlineEdge\
+  \ dicts)\n   - Metadata: `metadata` (dict), `tags` (list)\n\n2. **Entity Types**:\n\
+  \   - Resource: Knowledge base items (documents, specs, notes)\n   - Message: Conversation\
+  \ messages with agents\n   - User: System users with authentication\n   - File:\
+  \ File uploads with S3 storage\n   - Moment: Time-bound events and activities\n\n\
+  3. **REM Queries** - LLM-optimized query dialect:\n   - `LOOKUP`: O(1) lookup by\
+  \ entity label (e.g., \"sarah-chen\", \"api-design-v2\")\n   - `FUZZY`: Fuzzy text\
+  \ search with trigram similarity\n   - `SEARCH`: Semantic vector search using pgvector\n\
+  \   - Raw SQL: Any query not starting with REM keywords (SELECT, INSERT, UPDATE, etc.)\n\
+  \   - `TRAVERSE`: Graph traversal with depth control (follows graph_edges)\n\n4. **Graph Edges** - Human-readable relationships:\n\
+  \   - `dst` field contains entity labels (not UUIDs!)\n   - Edge weights: 1.0 =\
+  \ primary, 0.8-0.9 = important, 0.5-0.7 = secondary\n   - Rich metadata in properties\
+  \ dict\n   - Enables conversational queries without internal ID knowledge\n\n###\
+  \ Technology Stack\n\n**Infrastructure**:\n- AWS EKS (Kubernetes) with Pulumi IaC\n\
+  - Karpenter for node provisioning (NodePools for stateful/stateless workloads)\n\
+  - CloudNativePG (PostgreSQL 18 with pgvector extension)\n- ArgoCD for GitOps continuous\
+  \ delivery\n\n**Application**:\n- FastAPI server (core API)\n- FastMCP server (Model\
+  \ Context Protocol)\n- Pydantic AI agents with OpenTelemetry instrumentation\n-\
+  \ Arize Phoenix for LLM observability\n\n**Observability**:\n- OpenTelemetry Collector\
+  \ for distributed tracing\n- Arize Phoenix for LLM-specific observability (OpenInference\
+  \ conventions)\n- OTLP protocol for trace ingestion\n\n### Agent Development\n\n\
+  **Pydantic AI Integration**:\n- JSON Schema → Pydantic model conversion\n- Dynamic\
+  \ agent creation from YAML schemas\n- MCP tools loaded from schema metadata\n- Conditional\
+  \ OTEL instrumentation (disabled by default for local dev)\n\n**Agent Schema Format**:\n\
+  ```yaml\ntype: object\ndescription: \"System prompt describing agent behavior\"\n\
+  properties:\n  answer:\n    type: string\n    description: \"The answer field\"\n\
+  required:\n  - answer\njson_schema_extra:\n  fully_qualified_name: \"rem.agents.MyAgent\"\
+  \n  version: \"1.0.0\"\n  tools: []  # MCP tool configurations\n  resources: []\
+  \  # MCP resource configurations\n```\n\n**Design Patterns**:\n1. Header to Context\
+  \ Mapping: HTTP headers → AgentContext fields\n2. Agent Query Structure: query/knowledge/scratchpad\
+  \ pattern\n3. JsonSchema to Pydantic: Dynamic model creation\n4. Schema Description\
+  \ Stripping: Avoid LLM token bloat\n5. Streaming with agent.iter(): Complete execution\
+  \ with tool calls\n6. Stateless MCP Mounting: Kubernetes-friendly session handling\n\
+  7. Conditional OTEL: Production-only instrumentation\n\n### Database Schema\n\n\
+  **PostgreSQL 18 with pgvector**:\n- No Alembic migrations (schema evolution via\
+  \ Pydantic models only)\n- Vector embeddings for semantic search\n- Multi-tenancy\
+  \ via `tenant_id` field\n- Soft deletes with `deleted_at` timestamp\n\n### Multi-Tenancy\n\
+  \n- Tenant isolation via `tenant_id` field (system-level)\n- User ownership via\
+  \ `user_id` field (tenant-scoped)\n- Default tenant: \"default\"\n- REM queries\
+  \ automatically scoped to tenant\n\n### Environment Configuration\n\n**Nested Settings\
+  \ Pattern**:\n- Double underscore delimiter: `LLM__DEFAULT_MODEL`\n- Environment\
+  \ variable groups: LLM, MCP, OTEL, Auth, Postgres, S3\n- Sensible defaults (auth\
+  \ disabled, OTEL disabled for local dev)\n- Global settings singleton\n\n## Response\
+  \ Guidelines\n\n- Provide clear, concise answers with code examples when helpful\n\
+  - Reference specific design patterns from CLAUDE.md when applicable\n- Suggest best\
+  \ practices for cloud-native deployment\n- If uncertain, say so and suggest where\
+  \ to find more information\n\n## Metadata Registration\n\nBefore generating your final response, call the `register_metadata` tool to provide confidence scores and source attribution.\n\n## Example Queries You Can Answer\n\n- \"How do I\
+  \ create a new REM entity?\"\n- \"What's the difference between LOOKUP and TRAVERSE\
+  \ queries?\"\n- \"How do I add MCP tools to my agent schema?\"\n- \"Explain the\
+  \ graph edge pattern in REM\"\n- \"How do I enable OTEL tracing for my agents?\"\
+  \n- \"What's the CloudNativePG setup for pgvector?\"\n"
+properties:
+  answer:
+    type: string
+    description: Detailed answer to the user's question with examples and best practices
+  confidence:
+    type: number
+    minimum: 0
+    maximum: 1
+    description: 'Confidence score based on:
+
+      - Query clarity (0.9+: precise, 0.7-0.9: clear intent, <0.7: ambiguous)
+
+      - Information completeness (do you have all needed context?)
+
+      - Result certainty (how confident are you in the answer?)
+
+      '
+  references:
+    type: array
+    items:
+      type: string
+    description: 'List of relevant references (file paths, documentation links, design
+      pattern names)
+
+      '
+required:
+- answer
+json_schema_extra:
+  kind: agent
+  name: rem
+  version: 1.0.0
+  # Disable structured output - properties become prompt guidance instead of JSON schema
+  # This enables natural language streaming while still informing the agent about expected elements
+  structured_output: false
+  # MCP server configuration for dynamic tool loading (in-process, no subprocess)
+  mcp_servers:
+    - type: local
+      module: rem.mcp_server
+      id: rem-local
+
+  # Explicit tool declarations for REM operations
+  tools:
+    - name: search_rem
+      description: Execute REM queries for entity lookup, semantic search, SQL, and graph traversal (LOOKUP, FUZZY, SEARCH, raw SQL, TRAVERSE)
+    - name: ask_rem_agent
+      description: Convert natural language questions into optimized REM queries using agent-driven query conversion
+    - name: ingest_into_rem
+      description: Ingest files into REM creating searchable resources and embeddings
+    - name: read_resource
+      description: Read MCP resources by URI (schemas, system status, etc.)
+    - name: register_metadata
+      description: Register response metadata (confidence, sources, references) to be emitted as SSE MetadataEvent. Call BEFORE generating final response.
+
+  # Explicit resource declarations for reference data
+  resources:
+    - uri: rem://agents
+      name: Agent Schemas List
+      description: List all available agent schemas in the system
+    - uri: rem://status
+      name: System Status
+      description: REM system health and statistics