Create, Evaluate, and Connect AI Skills
Python ai-agentsai-skillsartificial-intelligenceknowledge-graphlarge-language-modelsnatural-language-processingopenkgskillnetskills
docs: refresh analysis examples and add routing walkthrough
Icarus-Chenb027a8cf3426
diff --git a/examples/analyze_example.py b/examples/analyze_example.pyindex b26c244..b0fdca7 100644--- a/examples/analyze_example.py+++ b/examples/analyze_example.py@@ -1,114 +1,168 @@-"""-Skill Relationship Analysis Example - Using SkillNetClient+"""Scenario Analysis Example - Using SkillNetClient.++Run from the repository root:+ python -m pip install -e "./skillnet-ai[graph]"+ python examples/analyze_example.py+ python examples/analyze_example.py ./my_skills --output-dir ./my_index++Configure API_KEY, BASE_URL, SKILLNET_MODEL and EMBEDDING_API_KEY,+EMBEDDING_BASE_URL, EMBEDDING_MODEL, or use saved SkillNet settings.+See skillnet-ai/README.md for model configuration.-Requires skillnet-ai[graph] and configured analysis and embedding endpoints.+Without a skills directory, create/update four illustrative SKILL.md files in+./demo_analysis_skills. Only their instructions are analyzed; no PDF or CSV is+processed. Model and embedding API calls may incur costs. Repeated analysis+reuses cached model results when their inputs are unchanged."""++import argparseimport json-import os-import shutil+from pathlib import Pathfrom skillnet_ai import SkillNetClient-# Define directory for demonstration-DEMO_SKILLS_DIR = "./demo_skills_library"--def setup_demo_environment() -> None:- """- Helper to create a few dummy skills locally so the analyzer has something to scan.- In a real scenario, you would point this to your actual skills directory.- """- if os.path.exists(DEMO_SKILLS_DIR):- shutil.rmtree(DEMO_SKILLS_DIR)- os.makedirs(DEMO_SKILLS_DIR)-- # Define some dummy skills with descriptions that imply relationships- dummy_skills = [- {- "name": "python_runtime",- "desc": "Sets up the base Python 3.10 environment with standard libraries. This is the foundational layer."- },- {- "name": "code_interpreter",- "desc": "Executes arbitrary Python code snippets safely. It strictly REQUIRES the 'python_runtime' to be installed and active to function."- },- {- "name": "code_review_agent",- "desc": "A high-level AI agent that manages the entire Pull Request review workflow, including syntax checking, logic analysis, and comment generation."- },- {- "name": "linter_tool",- "desc": "A specific tool that checks code style (PEP8). It is a built-in sub-component/module of the larger 'code_review_agent'."- },- {- "name": "git_diff_reader",- "desc": "Extracts changes between two git commits."- },- {- "name": "patch_generator",- "desc": "Generates a fix patch file. It is typically used immediately AFTER 'git_diff_reader' has identified the bugs."- },- {- "name": "postgres_client",- "desc": "A database client for connecting to PostgreSQL databases to execute SQL queries."- },- {- "name": "mysql_client",- "desc": "A database client for connecting to MySQL databases. It performs the same function as 'postgres_client' and can be used as a substitute."- }- ]-- # Create skill folders and SKILL.md files- for skill in dummy_skills:- skill_path = os.path.join(DEMO_SKILLS_DIR, skill["name"])- os.makedirs(skill_path, exist_ok=True)- with open(os.path.join(skill_path, "SKILL.md"), "w", encoding="utf-8") as f:- f.write(f"---\nname: {skill['name']}\ndescription: {skill['desc']}\n---\n")- f.write(f"# {skill['name']}\n\n{skill['desc']}")-- print(f"π¦ Created {len(dummy_skills)} dummy skills in '{DEMO_SKILLS_DIR}' for analysis.")+# Concrete handoffs and two alternative implementations of the same capability.+DEMO_SKILLS = {+ "pdf-table-to-csv": """---+name: pdf-table-to-csv+description: Extract a transaction table from a text-based PDF into a UTF-8 CSV.+---+# PDF transaction table to CSV++Use when a text-based PDF contains one transaction table with a header row and+an amount column. All amounts must be decimal numbers in the same currency.++1. Open the PDF with Python and pdfplumber. Extract the table, retaining the+ column names, row order and cell values. Use empty strings for empty cells.+2. Write transactions.csv with csv.writer, UTF-8 encoding and a header row.+3. Return the CSV path for subsequent quality checks and amount calculations.++Preserve the original PDF. Report ambiguous table boundaries or headers and+stop rather than guessing. Scanned PDFs require OCR outside this skill.+This step preserves missing values and duplicate rows for later inspection;+it does not validate, deduplicate or calculate transaction statistics.+""",+ "csv-quality-checker": """---+name: csv-quality-checker+description: Check a transaction CSV and produce a read-only data quality report.+---+# CSV quality check++Input: a UTF-8 transaction CSV with a header row and an amount column.+Use Python standard-library csv, decimal and json modules.++1. Read the CSV and check row widths, missing cells and duplicate rows.+2. Check that each amount parses as a finite Decimal. Record invalid values.+3. Write quality-report.json with the CSV path, row count, issue counts and+ passed=true only when at least one data row exists and every check passes.+4. Return the report and unchanged CSV paths. A passing report allows amount+ summarizers to use this CSV; otherwise the user must resolve the issues.++Never fill, delete, deduplicate or overwrite source data. Report malformed CSV+or a missing amount column as a failed check. Do not compute transaction means.+""",+ "csv-amount-summary": """---+name: csv-amount-summary+description: Calculate transaction count, total and mean using Python's standard library.+---+# Transaction amount summary++Input: a UTF-8 CSV with an amount column and a passing quality-report.json+for that unchanged file. Amounts must be finite decimals in one currency.++1. Read the report with json; confirm its CSV path and passed=true status.+2. Read the CSV with csv.DictReader and parse amounts using decimal.Decimal.+3. Calculate count, total and arithmetic mean; return them in a JSON report,+ representing decimal results as strings. Round the mean to two decimal+ places with ROUND_HALF_UP.++Stop on a failed or missing quality report, empty CSV or invalid amount.+Keep inputs unchanged. Use only the Python standard library. This skill+accepts user-provided transaction CSVs and performs no currency conversion.+""",+ "csv-amount-summary-pandas": """---+name: csv-amount-summary-pandas+description: Calculate transaction count, total and mean in a pandas workflow.+---+# Transaction amount summary with pandas++Input: a UTF-8 CSV with an amount column and a passing quality-report.json+for that unchanged file. Amounts must be finite decimals in one currency.++1. Read the report with json; confirm its CSV path and passed=true status.+2. Load the CSV with pandas.read_csv(dtype=str, keep_default_na=False).+3. Convert amounts to decimal.Decimal and calculate count, total and mean.+ Return a JSON report with decimal results as strings; round the mean to+ two decimal places with ROUND_HALF_UP.++Requires pandas in addition to Python. Stop on a failed or missing quality+report, empty CSV or invalid amount. Keep inputs unchanged. This skill accepts+user-provided transaction CSVs and performs no currency conversion.+""",+}+++def setup_demo_environment(skills_dir: Path) -> None:+ """Write the sample skill instructions, preserving existing analysis artifacts."""+ for name, source in DEMO_SKILLS.items():+ directory = skills_dir / name+ directory.mkdir(parents=True, exist_ok=True)+ (directory / "SKILL.md").write_text(source, encoding="utf-8")+ print(f"π¦ Prepared {len(DEMO_SKILLS)} demo skills in {skills_dir.resolve()}")def main() -> None:- # 1. Setup demo data (Optional: remove if you have your own skills folder)- setup_demo_environment()-- # 2. Initialize client- client = SkillNetClient(- api_key=os.getenv("API_KEY"),- base_url=os.getenv("BASE_URL", "https://api.openai.com/v1")+ """Analyze a local library and display scenario-specific relationships."""+ parser = argparse.ArgumentParser(description="Build and inspect a SkillNet analysis index.")+ parser.add_argument(+ "skills_dir",+ nargs="?",+ type=Path,+ help="Existing skill library; omit to create demo skills.",+ )+ parser.add_argument(+ "--output-dir",+ type=Path,+ default=Path("./demo_skillnet_index"),+ help="Analysis index directory (default: ./demo_skillnet_index).",)+ args = parser.parse_args()++ skills_dir = args.skills_dir+ if skills_dir is None:+ skills_dir = Path("./demo_analysis_skills")+ setup_demo_environment(skills_dir)++ # Model and embedding configuration comes from the environment or saved settings.+ client = SkillNetClient()+ print("\nπ Extracting scenarios and analyzing skill relationships...")+ analysis = client.analyze(skills_dir=skills_dir, output_dir=args.output_dir)+ print(f"Skills analyzed: {analysis.skill_count}")+ print(f"Relations: {analysis.relation_counts}")+ print(f"Cache hits: {analysis.cache_hits}")+ print(f"Index: {analysis.index_dir}")++ # CURRENT identifies the last successfully published snapshot.+ snapshot_name = (analysis.index_dir / "CURRENT").read_text(encoding="utf-8").strip()+ snapshot = analysis.index_dir / snapshot_name+ graph = json.loads((snapshot / "graph.json").read_text(encoding="utf-8"))+ print("\ncompose_with: predecessor -> successor under the stated conditions.")+ print("similar_to: comparable capabilities; check constraints before substituting.")+ if not graph["relations"]:+ print("No supported relationships found.")+ for relation in graph["relations"]:+ arrow = "->" if relation["type"] == "compose_with" else "<->"+ print(f"\n{relation['source']} {arrow} {relation['target']} ({relation['type']})")+ for context in relation["contexts"]:+ print(f" Scenario: {context['scenario']}")+ print(f" Explanation: {context['explanation']}")+ for condition in context["conditions"]:+ print(f" Condition: {condition}")++ print(f"\nπ Full graph: {snapshot / 'graph.json'}")+ print(f"π Wiki: {snapshot / 'wiki'}")+ print("Reuse this index with examples/route_example.py --index-dir <index directory>.")- # 3. Run Analysis- print("\nπ Analyzing relationships between skills...")- try:- analysis = client.analyze(skills_dir=DEMO_SKILLS_DIR)- snapshot_name = (analysis.index_dir / "CURRENT").read_text(encoding="utf-8").strip()- graph_path = analysis.index_dir / snapshot_name / "graph.json"- relationships = json.loads(graph_path.read_text(encoding="utf-8"))["relations"]-- # 4. Display Results- if not relationships:- print("No relationships detected.")- return-- print(f"\nβ Analysis Complete! Found {len(relationships)} connections:\n")-- # Simple header- print(f"{'Source':<20} | {'Relationship':<15} | {'Target':<20} | {'Reasoning'}")- print("-" * 100)-- for relationship in relationships:- source = relationship.get('source', 'N/A')- rtype = relationship.get('type', 'N/A')- target = relationship.get('target', 'N/A')- reason = relationship['contexts'][0]['explanation'][:40] + "..."-- print(f"{source:<20} | {rtype:<15} | {target:<20} | {reason}")-- print(f"\nπΎ relationships saved to: {graph_path}")-- except Exception as e:- print(f"β Analysis failed: {e}")if __name__ == "__main__":main()diff --git a/examples/route_example.py b/examples/route_example.pynew file mode 100644index 0000000..6f4c736--- /dev/null+++ b/examples/route_example.py@@ -0,0 +1,81 @@+"""Skill Routing Example - Using SkillNetClient.++First run examples/analyze_example.py from the repository root. Install one of+the following extras for your chosen Explorer SDK:+ python -m pip install -e "./skillnet-ai[graph,claude]"+ python -m pip install -e "./skillnet-ai[graph,codex]"++Configure SKILLNET_EXPLORER_API_KEY, SKILLNET_EXPLORER_BASE_URL and+SKILLNET_EXPLORER_MODEL for the chosen SDK, independently of the analysis+model. Keep EMBEDDING_API_KEY, EMBEDDING_BASE_URL and EMBEDDING_MODEL configured;+the embedding endpoint and model must match the index. Saved settings also work.+See skillnet-ai/README.md for model configuration.++Run the two demo tasks with either backend:+ python examples/route_example.py --backend claude+ python examples/route_example.py --backend codex++Or route your own task against an existing index:+ python examples/route_example.py "Check my CSV for duplicates" --index-dir ./my_index --k 3++Without --backend, use SKILLNET_EXPLORER_BACKEND or saved settings (default: claude).+Without a query, make two route calls using the sample tasks below. These calls+use the embedding and Explorer APIs; they select skills without executing them.+"""++import argparse+from pathlib import Path+from time import perf_counter++from skillnet_ai import SkillNetClient++DEMO_TASKS = (+ "I have a text-based PDF containing one transaction table with an amount column "+ "in a single currency. Extract it to CSV, check missing values, duplicate rows "+ "and invalid amounts, then calculate the mean amount if the checks pass.",+ "I already have transactions.csv with an amount column in a single currency "+ "and a passing quality-report.json for that unchanged file. Calculate the "+ "mean amount using only the Python standard library.",+)+++def main() -> None:+ """Select skills for complete and partially prepared tasks using one index."""+ parser = argparse.ArgumentParser(description="Route tasks through a SkillNet analysis index.")+ parser.add_argument("query", nargs="?", help="Task to route; omit to run both demo tasks.")+ parser.add_argument(+ "--index-dir",+ type=Path,+ default=Path("./demo_skillnet_index"),+ help="Existing analysis index (default: ./demo_skillnet_index).",+ )+ parser.add_argument("--backend", choices=("claude", "codex"), help="Explorer SDK override.")+ parser.add_argument("--k", type=int, default=5, help="Maximum skills per task (default: 5).")+ args = parser.parse_args()++ client = SkillNetClient()+ queries = DEMO_TASKS if args.query is None else (args.query,)+ print("Skills are returned as a set of choices, not an execution sequence.")+ print("The router may select fewer than k skills, including none.")+ for query in queries:+ print(f"\nπ Task: {query}")+ started = perf_counter()+ result = client.route(+ query=query,+ index_dir=args.index_dir,+ k=args.k,+ backend=args.backend,+ )+ print(f"Selected {len(result.skills)} skill(s) in {perf_counter() - started:.1f}s:")+ if not result.skills:+ print(" No suitable skills selected.")+ for skill in result.skills:+ print(f"\n {skill.name} ({skill.skill_id})")+ print(f" Path: {skill.path}")+ print(f" Reason: {skill.reason}")+ if result.usage:+ print(f"\nUsage: {result.usage}")+++if __name__ == "__main__":+ main()diff --git a/examples/scientific_workflow_demo.ipynb b/examples/scientific_workflow_demo.ipynbindex 86fbd42..3931b9e 100644--- a/examples/scientific_workflow_demo.ipynb+++ b/examples/scientific_workflow_demo.ipynb@@ -16,7 +16,7 @@"4. **Acquisition & Orchestration**: Skills are downloaded, validated, and composed into a pipeline.\n","5. **Execution**: The skills interact to generate scientific results.\n","\n",- "Analysis requires the `graph` extra and configured analysis (`API_KEY`, `BASE_URL`, `SKILLNET_MODEL`) and embedding (`EMBEDDING_API_KEY`, `EMBEDDING_BASE_URL`, `EMBEDDING_MODEL`) endpoints. See [SDK configuration](../skillnet-ai/README.md) for details. Analysis writes a reusable index; pass `analysis.index_dir` to `client.route` to select skills for a task, with a separately configured Explorer SDK. See [the analysis example](analyze_example.py).\n"+ "Analysis requires the `graph` extra and configured analysis (`API_KEY`, `BASE_URL`, `SKILLNET_MODEL`) and embedding (`EMBEDDING_API_KEY`, `EMBEDDING_BASE_URL`, `EMBEDDING_MODEL`) endpoints. See [SDK configuration](../skillnet-ai/README.md) for details. Analysis writes a reusable index; pass `analysis.index_dir` to `client.route` to select skills for a task, with a separately configured Explorer SDK. See [the analysis example](analyze_example.py) for scenario-specific relationships and [the routing example](route_example.py) for selecting up to `k` skills for tasks with different available inputs. Selection order is not execution order.\n"]},{@@ -76,10 +76,9 @@"sc.settings.verbosity = 3\n","sc.settings.set_figure_params(dpi=80, facecolor='white')\n","\n",- "# Set OpenAI API Key for SkillNet Evalaution & Analysis\n",- "# Replace with your actual key if available\n",- "os.environ[\"API_KEY\"] = \"your-api-key-here\" \n",- "os.environ[\"BASE_URL\"] = \"https://api.openai.com/v1\"\n"+ "# Use environment variables or settings saved by skillnet configure.\n",+ "# Evaluation and analysis use API_KEY, BASE_URL and SKILLNET_MODEL.\n",+ "# Analysis also requires the EMBEDDING_* settings described above.\n"]},{diff --git a/examples/skillnet_usage_demo.ipynb b/examples/skillnet_usage_demo.ipynbindex 63f4062..7008d2f 100644--- a/examples/skillnet_usage_demo.ipynb+++ b/examples/skillnet_usage_demo.ipynb@@ -14,6 +14,7 @@"3. **Create**: Create new skills from conversation logs, documents, or prompts\n","4. **Evaluate**: Evaluate skill quality across multiple dimensions\n","5. **Analyze**: Analyze skill relationships in the local skill library\n",+ "6. **Route**: Select task-relevant skills from an analyzed library\n","\n","## 0. Installation and Environment Configuration"]@@ -46,21 +47,12 @@],"source": ["import os\n",- "import sys\n","from skillnet_ai import SkillNetClient\n","\n",- "# Set API KEY (used for Create, Evaluate, and Analyze functions)\n",- "# Please replace with your actual API Key (e.g., OpenAI key)\n",- "os.environ[\"API_KEY\"] = \"your-api-key-here\" \n",- "os.environ[\"BASE_URL\"] = \"https://api.openai.com/v1\" # Optional: Set custom LLM Base URL\n",- "\n",- "# Initialize Client\n",- "# Note: Without an API Key, some functions (like Create, Evaluate) may not work, but Search usually works\n",- "client = SkillNetClient(\n",- " api_key=os.getenv(\"API_KEY\"),\n",- " base_url=os.getenv(\"BASE_URL\")\n",- " # github_token=\"ghp-...\" # Optional: For accessing private repos or increasing download rate limits\n",- ")\n",+ "# Use environment variables or settings saved by skillnet configure.\n",+ "# Create, evaluate and analyze use API_KEY, BASE_URL and SKILLNET_MODEL.\n",+ "# Analyze also requires the EMBEDDING_* settings described in section 5.\n",+ "client = SkillNetClient()\n","\n","print(\"SkillNetClient initialized successfully.\")"]@@ -229,9 +221,8 @@"try:\n"," # This step requires a valid API_KEY\n"," created_paths = client.create(\n",- " trajectory_content=trajectory_log, \n",- " output_dir=created_skills_dir,\n",- " model=\"gpt-4o\" # Specify model\n",+ " trajectory_content=trajectory_log,\n",+ " output_dir=created_skills_dir\n"," )\n"," print(f\"Created {len(created_paths)} skills:\")\n"," for path in created_paths:\n",@@ -301,9 +292,18 @@"source": ["## 5. Skill Relationship Analysis (Analyze)\n","\n",- "Analyze scenario-specific, directed `compose_with` and undirected `similar_to` relationships between skills.\n",+ "Extract scenarios and capabilities, then build an index containing the relationship\n",+ "graph and Wiki. `compose_with` is directed from predecessor to successor;\n",+ "`similar_to` describes comparable capabilities under their respective constraints.\n",+ "\n",+ "Use the `graph` extra installed above. Configure the analysis model with `API_KEY`,\n",+ "`BASE_URL` and `SKILLNET_MODEL`, and embeddings with `EMBEDDING_API_KEY`,\n",+ "`EMBEDDING_BASE_URL` and `EMBEDDING_MODEL`, or use saved settings.\n",+ "See [endpoint configuration](../skillnet-ai/README.md#analysis-and-routing-endpoints).\n","\n",- "Analysis requires the `graph` extra and configured analysis (`API_KEY`, `BASE_URL`, `SKILLNET_MODEL`) and embedding (`EMBEDDING_API_KEY`, `EMBEDDING_BASE_URL`, `EMBEDDING_MODEL`) endpoints. See [SDK configuration](../skillnet-ai/README.md) for details. Analysis writes a reusable index; pass `analysis.index_dir` to `client.route` to select skills for a task, with a separately configured Explorer SDK. See [the analysis example](analyze_example.py)."+ "The independent skills created in section 3 may have no relationships; their index\n",+ "is still usable for routing. See [analyze_example.py](analyze_example.py) for a\n",+ "small library demonstrating scenario-specific handoffs and similar capabilities.\n"]},{@@ -315,6 +315,7 @@"source": ["# Analyze the directory of created skills\n","analyze_target_dir = created_skills_dir\n",+ "analysis = None\n","\n","if os.path.exists(analyze_target_dir) and len(os.listdir(analyze_target_dir)) > 0:\n"," print(f\"--- Analyzing relationships in: {analyze_target_dir} ---\")\n",@@ -333,6 +334,64 @@"else:\n"," print(\"No skills directory found to analyze.\")"]+ },+ {+ "cell_type": "markdown",+ "id": "routing-guide",+ "metadata": {},+ "source": [+ "## 6. Select Skills for a Task (Route)\n",+ "\n",+ "Reuse the index from section 5 to select up to `k` skills. This example makes one\n",+ "route call for the temperature-conversion skill created earlier. Selection order\n",+ "is not execution order; the router may select fewer skills or none.\n",+ "\n",+ "Install **one** Explorer backend in this notebook's Python environment:\n",+ "\n",+ "- Claude: `%pip install -e \"../skillnet-ai[graph,claude]\"`\n",+ "- Codex: `%pip install -e \"../skillnet-ai[graph,codex]\"`\n",+ "\n",+ "Set `SKILLNET_EXPLORER_BACKEND` (`claude` or `codex`, default `claude`),\n",+ "`SKILLNET_EXPLORER_API_KEY`, `SKILLNET_EXPLORER_BASE_URL` and\n",+ "`SKILLNET_EXPLORER_MODEL`, or use saved settings. The endpoint must support the\n",+ "chosen SDK's protocol. Keep the embedding settings from section 5.\n",+ "See [endpoint configuration](../skillnet-ai/README.md#analysis-and-routing-endpoints).\n",+ "\n",+ "Routing calls the embedding and Explorer APIs. It reuses the index without\n",+ "rebuilding it or executing skills; most waiting comes from the SDK's model calls.\n",+ "The cell below displays elapsed time for your configuration. For a multi-step\n",+ "task and an example with existing intermediate inputs, see\n",+ "[route_example.py](route_example.py).\n"+ ]+ },+ {+ "cell_type": "code",+ "execution_count": null,+ "id": "routing-example",+ "metadata": {},+ "outputs": [],+ "source": [+ "from time import perf_counter\n",+ "\n",+ "if analysis is None:\n",+ " raise RuntimeError(\"Complete section 5 successfully before routing.\")\n",+ "\n",+ "# Reload settings if you configured the Explorer after initializing the client.\n",+ "client = SkillNetClient()\n",+ "started = perf_counter()\n",+ "result = client.route(\n",+ " query=\"Convert temperatures from degrees Celsius to Fahrenheit.\",\n",+ " index_dir=analysis.index_dir,\n",+ " k=3,\n",+ ")\n",+ "print(f\"Selected {len(result.skills)} skill(s) in {perf_counter() - started:.1f}s\")\n",+ "if not result.skills:\n",+ " print(\"No suitable skills selected.\")\n",+ "for skill in result.skills:\n",+ " print(f\"\\n{skill.name} ({skill.skill_id})\")\n",+ " print(f\"Path: {skill.path}\")\n",+ " print(f\"Reason: {skill.reason}\")\n"+ ]}],"metadata": {