Functor Logo
GitHub

Quick Start

Get up and running with Functor SDK in 5 minutes. This guide will walk you through your first query and basic operations.

Step 1: Install the SDK

If you haven't already, install the Functor SDK:

pip install functor-sdk

Step 2: Get Your API Key

You'll need an API key to authenticate. Set it as an environment variable:

export FUNCTOR_API_KEY=your-api-key-here
export FUNCTOR_BASE_URL=http://localhost:8000

Step 3: Execute Your First Query

Create a simple script to execute a query:

first_query.py
from functor_sdk import FunctorClient


# Create a client (uses environment variables)
client = FunctorClient()


# Execute a query
result = client.queries.execute("What is machine learning?")


# Display the results
print("Answer:", result.answer)
print("Pipeline:", result.pipeline_used)
print("Processing time:", result.processing_time_ms, "ms")
print("Citations:", len(result.citations))

Run the script:

python first_query.py

Step 4: Upload Some Data

Upload a document from a URL to build your knowledge graph:

upload_data.py
from functor_sdk import FunctorClient


client = FunctorClient()


# Upload from URL
result = client.ingestion.upload_url(
    url="https://www.who.int/news-room/fact-sheets/detail/diabetes",
    kg_name="KG_Universal",
    source_name="WHO Diabetes Facts"
)


print("Job ID:", result.job_id)
print("Message:", result.message)

Step 5: List Your Knowledge Graphs

See what knowledge graphs are available:

list_kgs.py
from functor_sdk import FunctorClient


client = FunctorClient()


# Get all knowledge graphs
kgs = client.knowledge_graphs.list(include_stats=True)


for kg in kgs:
    print(f"\n{kg.name} ({kg.display_name})")
    print(f"  Entities: {kg.entities_count}")
    print(f"  Relations: {kg.relations_count}")
    print(f"  Sources: {kg.sources_count}")

Step 6: Manage Sources

View and manage the sources in your knowledge graphs:

manage_sources.py
from functor_sdk import FunctorClient


client = FunctorClient()


# List sources for a specific KG
sources = client.sources.list_for_kg("KG_Universal")


for source in sources:
    print(f"\nSource: {source.source_name}")
    print(f"  ID: {source.id}")
    print(f"  Type: {source.source_type}")
    print(f"  Chunks: {source.chunks_count}")
    print(f"  Entities: {source.entities_count}")


# Get detailed stats for a source
if sources:
    stats = client.sources.get_stats(sources[0].id)
    print(f"\nDetailed stats for {stats.source_name}:")
    print(f"  Relations: {stats.relations_count}")
    print(f"  Vector points: {stats.vector_points_count}")

Complete Example

Here's a complete example that puts it all together:

complete_example.py
from functor_sdk import FunctorClient


def main():
    # Initialize client
    client = FunctorClient(api_key="your-api-key")
    
    # 1. Check system health
    print("Checking system health...")
    health = client.health.check()
    print(f"Status: {health['status']}")
    
    # 2. List available knowledge graphs
    print("\nAvailable knowledge graphs:")
    kgs = client.knowledge_graphs.list()
    for kg in kgs:
        print(f"  - {kg.name}")
    
    # 3. Upload a document
    print("\nUploading document...")
    upload_result = client.ingestion.upload_url(
        url="https://example.com/article.html",
        kg_name="KG_Universal",
        source_name="Example Article"
    )
    print(f"Job ID: {upload_result.job_id}")
    
    # 4. Execute a query
    print("\nExecuting query...")
    result = client.queries.execute(
        query="What are the main topics in the uploaded article?",
        max_results=5
    )
    print(f"Answer: {result.answer[:200]}...")
    
    # 5. List sources
    print("\nListing sources...")
    sources = client.sources.list_for_kg("KG_Universal")
    print(f"Total sources: {len(sources)}")
    
    print("\nāœ“ Complete!")


if __name__ == "__main__":
    main()

Async Version

For async applications, use the async methods:

async_example.py
import asyncio
from functor_sdk import FunctorClient


async def main():
    async with FunctorClient(api_key="your-key") as client:
        # All methods have _async versions
        result = await client.queries.execute_async(
            "What is artificial intelligence?"
        )
        print(result.answer)
        
        # Concurrent operations
        tasks = [
            client.queries.execute_async("What is ML?"),
            client.queries.execute_async("What is DL?"),
            client.queries.execute_async("What is NLP?")
        ]
        results = await asyncio.gather(*tasks)
        
        for i, result in enumerate(results, 1):
            print(f"\nQuery {i}: {result.answer[:100]}...")


if __name__ == "__main__":
    asyncio.run(main())

Error Handling

Always handle errors appropriately in production code:

from functor_sdk import (
    FunctorClient,
    FunctorAPIError,
    FunctorAuthenticationError,
    FunctorTimeoutError
)


client = FunctorClient()


try:
    result = client.queries.execute("Your query here")
    print(result.answer)
    
except FunctorAuthenticationError:
    print("Error: Invalid API key")
    
except FunctorTimeoutError:
    print("Error: Request timed out, try again")
    
except FunctorAPIError as e:
    print(f"API Error {e.status_code}: {e.message}")

Next Steps

Now that you've completed the quick start, explore more features: