skillware 0.4.0__tar.gz → 0.4.2__tar.gz

{skillware-0.4.0/skillware.egg-info → skillware-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.4.0
+Version: 0.4.2
 Summary: A framework for modular, self-contained AI skills.
 Author-email: ARPA Hellenic Logical Systems <skillware-os@arpacorp.net>
 License: MIT License
@@ -88,6 +88,7 @@ Dynamic: license-file
 
 <div align="center">
   <a href="#mission">Mission</a> •
+  <a href="#how-it-works">How it works</a> •
   <a href="#architecture">Architecture</a> •
   <a href="#quick-start">Quick Start</a> •
   <a href="#documentation">Documentation</a> •
@@ -119,6 +120,18 @@ A **Skill** in this framework provides everything an Agent needs to master a dom
 
 Browse capabilities by category in the [Skill library](docs/skills/README.md) or on our <a href="https://skillware.site/skills" target="_blank" rel="noopener noreferrer">site&nbsp;↗</a>.
 
+## How it works
+
+```mermaid
+flowchart LR
+    Registry[Registry] -->|Load| Loader[Loader]
+    Loader -->|Adapt| Host[Host]
+    Host -->|Prompt + Tools| LogicalSystems([Logical Systems])
+    LogicalSystems -->|Tool Call| Host
+```
+
+Install the registry once. Skillware loads a bundle and adapts it to your model's tool format — you run the loop. For details on how the loader turns the manifest into a tool, see the [Introduction](docs/introduction.md).
+
 ## Architecture
 
 This repository is organized into a core framework, a registry of skills, and
@@ -225,9 +238,10 @@ load_env_file()
 # 1. Load the Skill from the Registry
 # The loader reads the code, manifest, and instructions automatically
 skill_bundle = SkillLoader.load_skill("finance/wallet_screening")
-skill = skill_bundle["module"].WalletScreeningSkill(
+skill = skill_bundle["class"](
     config={"ETHERSCAN_API_KEY": os.environ.get("ETHERSCAN_API_KEY")}
 )
+# Or: skill = skill_bundle["module"].WalletScreeningSkill(config={...})
 
 # 2. Client & Tool Setup
 client = genai.Client()

{skillware-0.4.0 → skillware-0.4.2}/README.md

@@ -17,6 +17,7 @@
 
 <div align="center">
   <a href="#mission">Mission</a> •
+  <a href="#how-it-works">How it works</a> •
   <a href="#architecture">Architecture</a> •
   <a href="#quick-start">Quick Start</a> •
   <a href="#documentation">Documentation</a> •
@@ -48,6 +49,18 @@ A **Skill** in this framework provides everything an Agent needs to master a dom
 
 Browse capabilities by category in the [Skill library](docs/skills/README.md) or on our <a href="https://skillware.site/skills" target="_blank" rel="noopener noreferrer">site&nbsp;↗</a>.
 
+## How it works
+
+```mermaid
+flowchart LR
+    Registry[Registry] -->|Load| Loader[Loader]
+    Loader -->|Adapt| Host[Host]
+    Host -->|Prompt + Tools| LogicalSystems([Logical Systems])
+    LogicalSystems -->|Tool Call| Host
+```
+
+Install the registry once. Skillware loads a bundle and adapts it to your model's tool format — you run the loop. For details on how the loader turns the manifest into a tool, see the [Introduction](docs/introduction.md).
+
 ## Architecture
 
 This repository is organized into a core framework, a registry of skills, and
@@ -154,9 +167,10 @@ load_env_file()
 # 1. Load the Skill from the Registry
 # The loader reads the code, manifest, and instructions automatically
 skill_bundle = SkillLoader.load_skill("finance/wallet_screening")
-skill = skill_bundle["module"].WalletScreeningSkill(
+skill = skill_bundle["class"](
     config={"ETHERSCAN_API_KEY": os.environ.get("ETHERSCAN_API_KEY")}
 )
+# Or: skill = skill_bundle["module"].WalletScreeningSkill(config={...})
 
 # 2. Client & Tool Setup
 client = genai.Client()

{skillware-0.4.0 → skillware-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillware"
-version = "0.4.0"
+version = "0.4.2"
 description = "A framework for modular, self-contained AI skills."
 readme = "README.md"
 authors = [

{skillware-0.4.0 → skillware-0.4.2}/skills/defi/evm_tx_handler/instructions.md

@@ -1,6 +1,6 @@
 # EVM Transaction Handler
 
-You are equipped with **`evm_tx_handler`**: a deterministic EVM tool for a **dedicated agent wallet** on Ethereum and Base.
+You are equipped with **`defi/evm_tx_handler`**: a deterministic EVM tool for a **dedicated agent wallet** on Ethereum and Base.
 
 ## Your job vs the skill's job
 

{skillware-0.4.0 → skillware-0.4.2}/skills/defi/evm_tx_handler/manifest.yaml

@@ -1,4 +1,4 @@
-name: evm_tx_handler
+name: defi/evm_tx_handler
 version: 0.2.0
 description: |
   Operates a dedicated EVM agent wallet for structured buy/sell on Ethereum and Base:

{skillware-0.4.0 → skillware-0.4.2}/skills/defi/evm_tx_handler/test_skill.py

@@ -81,12 +81,13 @@ def manifest():
 
 def test_manifest_consistency(skill, manifest):
     assert skill.manifest["name"] == manifest["name"]
+    assert manifest["name"] == "defi/evm_tx_handler"
 
 
 def test_loader_loads_skill(monkeypatch):
     monkeypatch.setenv("AGENT_WALLET_PRIVATE_KEY", TEST_KEY)
     bundle = SkillLoader.load_skill("defi/evm_tx_handler")
-    assert bundle["manifest"]["name"] == "evm_tx_handler"
+    assert bundle["manifest"]["name"] == "defi/evm_tx_handler"
     cls = bundle["module"].EvmTxHandlerSkill
     instance = cls()
     assert (

skillware-0.4.2/skills/finance/uk_companies_house_handler/card.json

@@ -0,0 +1,21 @@
+{
+  "name": "UK Companies House Handler",
+  "description": "Search, profile, officers, PSC, and filing history for UK-registered companies via Companies House API.",
+  "issuer": {
+    "name": "Areen Agrawal",
+    "email": "agrawalareen09@gmail.com",
+    "github": "Areen-09",
+    "org": "ARPAHLS"
+  },
+  "icon": "building-columns",
+  "color": "teal",
+  "ui_schema": {
+    "type": "card",
+    "fields": [
+      {"key": "status", "label": "Status", "type": "status_badge"},
+      {"key": "company_number", "label": "Company No."},
+      {"key": "company_name", "label": "Company Name"},
+      {"key": "company_status", "label": "Company Status", "type": "status_badge"}
+    ]
+  }
+}

skillware-0.4.2/skills/finance/uk_companies_house_handler/data/api_index.json

@@ -0,0 +1,127 @@
+{
+  "base_url": "https://api.company-information.service.gov.uk",
+  "auth": {
+    "method": "http_basic",
+    "username": "api_key",
+    "password": "empty",
+    "docs": "https://developer.company-information.service.gov.uk/"
+  },
+  "rate_limit": {
+    "requests_per_five_minutes": 600,
+    "note": "Rate limits apply per API key. 429 responses indicate throttling."
+  },
+  "endpoints": {
+    "search_companies": {
+      "method": "GET",
+      "path": "/search/companies",
+      "description": "Search for companies by name or number.",
+      "params": {
+        "q": {
+          "type": "string",
+          "required": true,
+          "description": "Company name or number search query"
+        },
+        "items_per_page": {
+          "type": "integer",
+          "required": false,
+          "default": 20,
+          "max": 100,
+          "description": "Number of results per page"
+        },
+        "start_index": {
+          "type": "integer",
+          "required": false,
+          "default": 0,
+          "description": "Offset for pagination"
+        }
+      },
+      "response_key": "items"
+    },
+    "get_company_profile": {
+      "method": "GET",
+      "path": "/company/{company_number}",
+      "description": "Get the full profile for a specific company.",
+      "params": {},
+      "response_key": null
+    },
+    "get_officers": {
+      "method": "GET",
+      "path": "/company/{company_number}/officers",
+      "description": "List officers (directors, secretaries) for a company.",
+      "params": {
+        "items_per_page": {
+          "type": "integer",
+          "required": false,
+          "description": "Number of results per page"
+        },
+        "start_index": {
+          "type": "integer",
+          "required": false,
+          "description": "Offset for pagination"
+        },
+        "order_by": {
+          "type": "string",
+          "required": false,
+          "enum": ["appointed_on", "resigned_on", "surname"],
+          "description": "Sort order for results"
+        }
+      },
+      "response_key": "items"
+    },
+    "get_pscs": {
+      "method": "GET",
+      "path": "/company/{company_number}/persons-with-significant-control",
+      "description": "List persons with significant control (beneficial owners).",
+      "params": {
+        "items_per_page": {
+          "type": "integer",
+          "required": false,
+          "description": "Number of results per page"
+        },
+        "start_index": {
+          "type": "integer",
+          "required": false,
+          "description": "Offset for pagination"
+        },
+        "register_view": {
+          "type": "boolean",
+          "required": false,
+          "description": "Show only active PSCs when true"
+        }
+      },
+      "response_key": "items"
+    },
+    "get_filing_history": {
+      "method": "GET",
+      "path": "/company/{company_number}/filing-history",
+      "description": "List filing history for a company.",
+      "params": {
+        "category": {
+          "type": "string",
+          "required": false,
+          "description": "Filter by filing category (e.g. accounts, confirmation-statement)"
+        },
+        "items_per_page": {
+          "type": "integer",
+          "required": false,
+          "description": "Number of results per page"
+        },
+        "start_index": {
+          "type": "integer",
+          "required": false,
+          "description": "Offset for pagination"
+        }
+      },
+      "response_key": "items"
+    }
+  },
+  "v2_planned": [
+    "charges",
+    "registers",
+    "insolvency",
+    "document_metadata",
+    "document_fetch",
+    "search_officers",
+    "search_disqualified_officers"
+  ]
+}

skillware-0.4.2/skills/finance/uk_companies_house_handler/data/terminology_map.yaml

@@ -0,0 +1,107 @@
+# Maps common (often US-centric) business terms to their UK Companies House
+# equivalents. The skill and instructions.md reference this so agents do not
+# hallucinate wrong roles or entity types.
+
+role_mappings:
+  ceo: director
+  chief_executive_officer: director
+  chief_executive: director
+  president: director
+  chairman: director
+  chairwoman: director
+  chairperson: director
+  board_member: director
+  managing_director: director
+  executive_director: director
+  non_executive_director: director
+  cfo: director
+  cto: director
+  coo: director
+  secretary: secretary
+  company_secretary: secretary
+  corporate_secretary: secretary
+  owner: person_with_significant_control
+  shareholder: person_with_significant_control
+  beneficial_owner: person_with_significant_control
+  stakeholder: person_with_significant_control
+  majority_owner: person_with_significant_control
+  controlling_shareholder: person_with_significant_control
+  partner: llp_designated_member
+  general_partner: llp_designated_member
+  limited_partner: llp_member
+
+entity_types:
+  corporation: ltd
+  inc: ltd
+  incorporated: ltd
+  limited: ltd
+  llc: ltd
+  co: ltd
+  company: ltd
+  public_company: plc
+  public_limited_company: plc
+  partnership: llp
+  limited_liability_partnership: llp
+  limited_partnership: lp
+  community_interest_company: cic
+  charity: charitable-incorporated-organisation
+
+status_mappings:
+  operating: active
+  open: active
+  running: active
+  trading: active
+  closed: dissolved
+  shutdown: dissolved
+  bankrupt: liquidation
+  insolvent: liquidation
+  in_administration: administration
+  winding_up: liquidation
+  struck_off: dissolved
+  dormant: dormant
+
+document_types:
+  annual_report: annual-return
+  10k: accounts
+  10q: confirmation-statement
+  financial_statements: accounts
+  balance_sheet: accounts
+  income_statement: accounts
+  articles: incorporation
+  articles_of_incorporation: incorporation
+  bylaws: incorporation
+  charter: incorporation
+  annual_filing: confirmation-statement
+  registration: incorporation
+
+# Maps user intent keywords to the appropriate skill action
+intent_to_action:
+  search: resolve_company
+  find: resolve_company
+  lookup: resolve_company
+  look_up: resolve_company
+  who_is: get_officers
+  directors: get_officers
+  officers: get_officers
+  board: get_officers
+  management: get_officers
+  leadership: get_officers
+  ceo: get_officers
+  owner: get_pscs
+  owners: get_pscs
+  ownership: get_pscs
+  shareholder: get_pscs
+  shareholders: get_pscs
+  beneficial_owner: get_pscs
+  psc: get_pscs
+  filings: get_filing_history
+  filing: get_filing_history
+  accounts: get_filing_history
+  annual_return: get_filing_history
+  documents: get_filing_history
+  profile: get_company_profile
+  details: get_company_profile
+  info: get_company_profile
+  information: get_company_profile
+  status: get_company_profile
+  registered: get_company_profile

skillware-0.4.2/skills/finance/uk_companies_house_handler/instructions.md

@@ -0,0 +1,73 @@
+# UK Companies House Handler — Instructions
+
+You are an agent equipped with the `finance/uk_companies_house_handler` skill. This tool lets you query the UK Companies House registry for company information, officers, ownership, and filing history through structured actions.
+
+## When to use
+
+Use this skill when the user:
+
+- Asks about a UK company (registered in England, Wales, Scotland, or Northern Ireland).
+- Wants to know who runs, owns, or controls a UK company.
+- Asks about directors, officers, or "the CEO" of a UK company.
+- Requests filing history, accounts, or annual returns for a UK company.
+- Mentions "Companies House" or refers to a UK company number (8 characters, e.g. 00102498).
+- Asks about beneficial owners, PSCs, or persons with significant control.
+
+## UK Terminology — Critical
+
+UK companies do **not** use the term "CEO" in a legal sense. When a user says "CEO", "president", or "chairman", you should look up **directors** via the `get_officers` action. The skill includes a terminology map:
+
+| User says | UK equivalent | Skill action |
+| :--- | :--- | :--- |
+| CEO, president, chairman | Director | `get_officers` |
+| Owner, shareholder, beneficial owner | Person with Significant Control (PSC) | `get_pscs` |
+| Secretary, corporate secretary | Secretary | `get_officers` |
+| Annual report, 10-K, financials | Accounts / Confirmation Statement | `get_filing_history` |
+| Company, corporation, LLC | Ltd, PLC, LLP | `resolve_company` |
+
+Always inform the user about these terminology differences when presenting results.
+
+## Available actions
+
+| Action | Purpose | Required params |
+| :--- | :--- | :--- |
+| `resolve_company` | Search by name, get ranked candidates | `query` |
+| `get_company_profile` | Full profile by company number | `company_number` |
+| `get_officers` | List directors and secretaries | `company_number` |
+| `get_pscs` | List persons with significant control | `company_number` |
+| `get_filing_history` | List filings (accounts, returns, etc.) | `company_number` |
+| `map_intent` | Translate intent keywords to action pipeline | `intent_keywords` or `entities` |
+
+## Workflow — Always map intent first
+
+1. **Always map intent first.** For every new user request, you MUST start by calling the `map_intent` action with the user's `intent_keywords` (as a comma-separated string) and `entities` (if applicable).
+2. Read the `suggested_pipeline` returned by the `map_intent` action.
+3. Follow the actions exactly as ordered in the `suggested_pipeline`.
+4. If a step (like `resolve_company`) returns a status of `needs_input`, present the candidates to the user and wait for their choice before proceeding.
+5. Once you have a confirmed `company_number`, continue with the remaining specific actions (`get_officers`, `get_pscs`, etc.) in your pipeline.
+
+## Understanding responses
+
+Every response includes a `status` field:
+
+- **`ready`**: The data was fetched successfully. Present it to the user.
+- **`needs_input`**: Multiple matches or missing information. Present the `candidates` to the user and ask for clarification. Use the `agent_hint` for guidance.
+- **`error`**: Something went wrong. Check `error_code` and `message`. Common errors:
+  - `not_found`: Company number does not exist.
+  - `rate_limited`: Too many requests; wait and retry.
+  - `missing_company_number`: You need to resolve a company first.
+
+Every response includes `fetched_at` (UTC timestamp) and `source` — always cite these when presenting data.
+
+## Limitations
+
+- **v1 scope only**: Search, profile, officers, PSC, and filing history. Charges, insolvency registers, and document downloads are not yet supported.
+- **No filing submission**: This skill is read-only; it cannot submit documents to Companies House.
+- **Rate limits**: Companies House API allows 600 requests per 5 minutes per key.
+- **Public data only**: Only publicly available data is returned. No confidential or protected information.
+
+## Safety
+
+- This skill provides company information. **It is not legal or accounting advice.**
+- Always include this disclaimer when presenting company data to users.
+- Always cite the `company_number` and `fetched_at` timestamp so the user knows the data source and currency.

skillware-0.4.2/skills/finance/uk_companies_house_handler/manifest.yaml

@@ -0,0 +1,67 @@
+name: finance/uk_companies_house_handler
+version: 1.0.0
+description: |
+  Deterministic UK Companies House API handler for agents. Provides structured
+  operations for company search, profile lookup, officer and PSC listing, filing
+  history, and intent-to-operation mapping with UK corporate terminology
+  translation. Returns status-based responses (ready, needs_input, error) with
+  disambiguation support. The agent owns natural-language dialogue; the skill
+  returns structured candidates and next actions.
+short_description: "UK Companies House search, officers, PSC, and filings via structured actions."
+issuer:
+  name: Areen Agrawal
+  email: agrawalareen09@gmail.com
+  github: Areen-09
+  org: ARPAHLS
+parameters:
+  type: object
+  properties:
+    action:
+      type: string
+      description: >
+        The operation to perform. One of: resolve_company, get_company_profile,
+        get_officers, get_pscs, get_filing_history, map_intent.
+      enum:
+        - resolve_company
+        - get_company_profile
+        - get_officers
+        - get_pscs
+        - get_filing_history
+        - map_intent
+    query:
+      type: string
+      description: "Company name or partial name for search (resolve_company)."
+    company_number:
+      type: string
+      description: "8-character UK company number (required for profile/officers/pscs/filing)."
+    active_only:
+      type: boolean
+      description: "Filter to current/active records only. Default false."
+    limit:
+      type: integer
+      description: "Max results to return (resolve_company). Default 5."
+    category:
+      type: string
+      description: "Filing category filter (get_filing_history)."
+    intent_keywords:
+      type: string
+      description: "Comma-separated keywords from user intent for map_intent action."
+    entities:
+      type: object
+      description: "Extracted entities for map_intent (e.g. company_query, role)."
+  required:
+    - action
+constitution: |
+  1. Use only publicly available Companies House data.
+  2. Require COMPANIES_HOUSE_API_KEY via environment; never hardcode or log the key.
+  3. Do not cache personal data (officer names, addresses) beyond the current request.
+  4. Always cite company_number and data timestamp (fetched_at) in responses.
+  5. Never guess a company number; return ranked search hits when ambiguous.
+  6. This skill provides company information, not legal or accounting advice.
+  7. Do not submit filings or modify Companies House records.
+env_vars:
+  COMPANIES_HOUSE_API_KEY:
+    description: "API key from the Companies House Developer Hub. Used as HTTP Basic username with empty password."
+    required: true
+requirements:
+  - requests